docs/API.md

   1 # noVNC API
   2
   3 The interface of the noVNC client consists of a single RFB object that
   4 is instantiated once per connection.
   5
   6 ## RFB
   7
   8 The `RFB` object represents a single connection to a VNC server. It
   9 communicates using a WebSocket that must provide a standard RFB
  10 protocol stream.
  11
  12 ### Constructor
  13
  14 [`RFB()`](#rfb-1)
  15   - Creates and returns a new `RFB` object.
  16
  17 ### Properties
  18
  19 `viewOnly`
  20   - Is a `boolean` indicating if any events (e.g. key presses or mouse
  21     movement) should be prevented from being sent to the server.
  22     Disabled by default.
  23
  24 `focusOnClick`
  25   - Is a `boolean` indicating if keyboard focus should automatically be
  26     moved to the remote session when a `mousedown` or `touchstart`
  27     event is received.
  28
  29 `touchButton`
  30   - Is a `long` controlling the button mask that should be simulated
  31     when a touch event is recieved. Uses the same values as
  32     [`MouseEvent.button`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button).
  33     Is set to `1` by default.
  34
  35 `clipViewport`
  36   - Is a `boolean` indicating if the remote session should be clipped
  37     to its container. When disabled scrollbars will be shown to handle
  38     the resulting overflow. Disabled by default.
  39
  40 `dragViewport`
  41   - Is a `boolean` indicating if mouse events should control the
  42     relative position of a clipped remote session. Only relevant if
  43     `clipViewport` is enabled. Disabled by default.
  44
  45 `scaleViewport`
  46   - Is a `boolean` indicating if the remote session should be scaled
  47     locally so it fits its container. When disabled it will be centered
  48     if the remote session is smaller than its container, or handled
  49     according to `clipViewport` if it is larger. Disabled by default.
  50
  51 `resizeSession`
  52   - Is a `boolean` indicating if a request to resize the remote session
  53     should be sent whenever the container changes dimensions. Disabled
  54     by default.
  55
  56 `showDotCursor`
  57   - Is a `boolean` indicating whether a dot cursor should be shown
  58     instead of a zero-sized or fully-transparent cursor if the server
  59     sets such invisible cursor. Disabled by default.
  60
  61 `background`
  62   - Is a valid CSS [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
  63     style value indicating which background style should be applied
  64     to the element containing the remote session screen. The default value is `rgb(40, 40, 40)`
  65     (solid gray color).
  66
  67 `capabilities` *Read only*
  68   - Is an `Object` indicating which optional extensions are available
  69     on the server. Some methods may only be called if the corresponding
  70     capability is set. The following capabilities are defined:
  71
  72     | name     | type      | description
  73     | -------- | --------- | -----------
  74     | `power`  | `boolean` | Machine power control is available
  75
  76 ### Events
  77
  78 [`connect`](#connect)
  79   - The `connect` event is fired when the `RFB` object has completed
  80     the connection and handshaking with the server.
  81
  82 [`disconnect`](#disconnected)
  83   - The `disconnect` event is fired when the `RFB` object disconnects.
  84
  85 [`credentialsrequired`](#credentialsrequired)
  86   - The `credentialsrequired` event is fired when more credentials must
  87     be given to continue.
  88
  89 [`securityfailure`](#securityfailure)
  90   - The `securityfailure` event is fired when the security negotiation
  91     with the server fails.
  92
  93 [`clipboard`](#clipboard)
  94   - The `clipboard` event is fired when clipboard data is received from
  95     the server.
  96
  97 [`bell`](#bell)
  98   - The `bell` event is fired when a audible bell request is received
  99     from the server.
 100
 101 [`desktopname`](#desktopname)
 102   - The `desktopname` event is fired when the remote desktop name
 103     changes.
 104
 105 [`capabilities`](#capabilities)
 106   - The `capabilities` event is fired when `RFB.capabilities` is
 107     updated.
 108
 109 ### Methods
 110
 111 [`RFB.disconnect()`](#rfbdisconnect)
 112   - Disconnect from the server.
 113
 114 [`RFB.sendCredentials()`](#rfbsendcredentials)
 115   - Send credentials to server. Should be called after the
 116     [`credentialsrequired`](#credentialsrequired) event has fired.
 117
 118 [`RFB.sendKey()`](#rfbsendKey)
 119   - Send a key event.
 120
 121 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
 122   - Send Ctrl-Alt-Del key sequence.
 123
 124 [`RFB.focus()`](#rfbfocus)
 125   - Move keyboard focus to the remote session.
 126
 127 [`RFB.blur()`](#rfbblur)
 128   - Remove keyboard focus from the remote session.
 129
 130 [`RFB.machineShutdown()`](#rfbmachineshutdown)
 131   - Request a shutdown of the remote machine.
 132
 133 [`RFB.machineReboot()`](#rfbmachinereboot)
 134   - Request a reboot of the remote machine.
 135
 136 [`RFB.machineReset()`](#rfbmachinereset)
 137   - Request a reset of the remote machine.
 138
 139 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
 140   - Send clipboard contents to server.
 141
 142 ### Details
 143
 144 #### RFB()
 145
 146 The `RFB()` constructor returns a new `RFB` object and initiates a new
 147 connection to a specified VNC server.
 148
 149 ##### Syntax
 150
 151     let rfb = new RFB( target, url [, options] );
 152
 153 ###### Parameters
 154
 155 **`target`**
 156   - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
 157     that specifies where the `RFB` object should attach itself. The
 158     existing contents of the `HTMLElement` will be untouched, but new
 159     elements will be added during the lifetime of the `RFB` object.
 160
 161 **`url`**
 162   - A `DOMString` specifying the VNC server to connect to. This must be
 163     a valid WebSocket URL.
 164
 165 **`options`** *Optional*
 166   - An `Object` specifying extra details about how the connection
 167     should be made.
 168
 169     Possible options:
 170
 171     `shared`
 172       - A `boolean` indicating if the remote server should be shared or
 173         if any other connected clients should be disconnected. Enabled
 174         by default.
 175
 176     `credentials`
 177       - An `Object` specifying the credentials to provide to the server
 178         when authenticating. The following credentials are possible:
 179
 180         | name         | type        | description
 181         | ------------ | ----------- | -----------
 182         | `"username"` | `DOMString` | The user that authenticates
 183         | `"password"` | `DOMString` | Password for the user
 184         | `"target"`   | `DOMString` | Target machine or session
 185
 186     `repeaterID`
 187       - A `DOMString` specifying the ID to provide to any VNC repeater
 188         encountered.
 189
 190     `wsProtocols`
 191       - An `Array` of `DOMString`s specifying the sub-protocols to use
 192         in the WebSocket connection. Empty by default.
 193
 194 #### connect
 195
 196 The `connect` event is fired after all the handshaking with the server
 197 is completed and the connection is fully established. After this event
 198 the `RFB` object is ready to recieve graphics updates and to send input.
 199
 200 #### disconnect
 201
 202 The `disconnect` event is fired when the connection has been
 203 terminated. The `detail` property is an `Object` that contains the
 204 property `clean`. `clean` is a `boolean` indicating if the termination
 205 was clean or not. In the event of an unexpected termination or an error
 206 `clean` will be set to false.
 207
 208 #### credentialsrequired
 209
 210 The `credentialsrequired` event is fired when the server requests more
 211 credentials than were specified to [`RFB()`](#rfb-1). The `detail`
 212 property is an `Object` containing the property `types` which is an
 213 `Array` of `DOMString` listing the credentials that are required.
 214
 215 #### securityfailure
 216
 217 The `securityfailure` event is fired when the handshaking process with
 218 the server fails during the security negotiation step. The `detail`
 219 property is an `Object` containing the following properties:
 220
 221 | Property | Type        | Description
 222 | -------- | ----------- | -----------
 223 | `status` | `long`      | The failure status code
 224 | `reason` | `DOMString` | The **optional** reason for the failure
 225
 226 The property `status` corresponds to the
 227 [SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult)
 228 status code in cases of failure. A status of zero will not be sent in
 229 this event since that indicates a successful security handshaking
 230 process. The optional property `reason` is provided by the server and
 231 thus the language of the string is not known. However most servers will
 232 probably send English strings. The server can choose to not send a
 233 reason and in these cases the `reason` property will be omitted.
 234
 235 #### clipboard
 236
 237 The `clipboard` event is fired when the server has sent clipboard data.
 238 The `detail` property is an `Object` containing the property `text`
 239 which is a `DOMString` with the clipboard data.
 240
 241 #### bell
 242
 243 The `bell` event is fired when the server has requested an audible
 244 bell.
 245
 246 #### desktopname
 247
 248 The `desktopname` event is fired when the name of the remote desktop
 249 changes. The `detail` property is an `Object` with the property `name`
 250 which is a `DOMString` specifying the new name.
 251
 252 #### capabilities
 253
 254 The `capabilities` event is fired whenever an entry is added or removed
 255 from `RFB.capabilities`. The `detail` property is an `Object` with the
 256 property `capabilities` containing the new value of `RFB.capabilities`.
 257
 258 #### RFB.disconnect()
 259
 260 The `RFB.disconnect()` method is used to disconnect from the currently
 261 connected server.
 262
 263 ##### Syntax
 264
 265     RFB.disconnect( );
 266
 267 #### RFB.sendCredentials()
 268
 269 The `RFB.sendCredentials()` method is used to provide the missing
 270 credentials after a `credentialsrequired` event has been fired.
 271
 272 ##### Syntax
 273
 274     RFB.sendCredentials( credentials );
 275
 276 ###### Parameters
 277
 278 **`credentials`**
 279   - An `Object` specifying the credentials to provide to the server
 280     when authenticating. See [`RFB()`](#rfb-1) for details.
 281
 282 #### RFB.sendKey()
 283
 284 The `RFB.sendKey()` method is used to send a key event to the server.
 285
 286 ##### Syntax
 287
 288     RFB.sendKey( keysym, code [, down] );
 289
 290 ###### Parameters
 291
 292 **`keysym`**
 293   - A `long` specifying the RFB keysym to send. Can be `0` if a valid
 294     **`code`** is specified.
 295
 296 **`code`**
 297   - A `DOMString` specifying the physical key to send. Valid values are
 298     those that can be specified to
 299     [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
 300     If the physical key cannot be determined then `null` shall be
 301     specified.
 302
 303 **`down`** *Optional*
 304   - A `boolean` specifying if a press or a release event should be
 305     sent. If omitted then both a press and release event are sent.
 306
 307 #### RFB.sendCtrlAltDel()
 308
 309 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
 310 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
 311 around [`RFB.sendKey()`](#rfbsendkey).
 312
 313 ##### Syntax
 314
 315     RFB.sendCtrlAltDel( );
 316
 317 #### RFB.focus()
 318
 319 The `RFB.focus()` method sets the keyboard focus on the remote session.
 320 Keyboard events will be sent to the remote server after this point.
 321
 322 ##### Syntax
 323
 324     RFB.focus( );
 325
 326 #### RFB.blur()
 327
 328 The `RFB.blur()` method remove keyboard focus on the remote session.
 329 Keyboard events will no longer be sent to the remote server after this
 330 point.
 331
 332 ##### Syntax
 333
 334     RFB.blur( );
 335
 336 #### RFB.machineShutdown()
 337
 338 The `RFB.machineShutdown()` method is used to request to shut down the
 339 remote machine. The capability `power` must be set for this method to
 340 have any effect.
 341
 342 ##### Syntax
 343
 344     RFB.machineShutdown( );
 345
 346 #### RFB.machineReboot()
 347
 348 The `RFB.machineReboot()` method is used to request a clean reboot of
 349 the remote machine. The capability `power` must be set for this method
 350 to have any effect.
 351
 352 ##### Syntax
 353
 354     RFB.machineReboot( );
 355
 356 #### RFB.machineReset()
 357
 358 The `RFB.machineReset()` method is used to request a forced reset of
 359 the remote machine. The capability `power` must be set for this method
 360 to have any effect.
 361
 362 ##### Syntax
 363
 364     RFB.machineReset( );
 365
 366 #### RFB.clipboardPasteFrom()
 367
 368 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
 369 to the remote server.
 370
 371 ##### Syntax
 372
 373     RFB.clipboardPasteFrom( text );
 374
 375 ###### Parameters
 376
 377 **`text`**
 378   - A `DOMString` specifying the clipboard data to send. Currently only
 379   characters from ISO 8859-1 are supported.