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. Enabled by default.
  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 `qualityLevel`
  68   - Is an `int` in range `[0-9]` controlling the desired JPEG quality.
  69     Value `0` implies low quality and `9` implies high quality.
  70     Default value is `6`.
  71
  72 `compressionLevel`
  73   - Is an `int` in range `[0-9]` controlling the desired compression
  74     level. Value `0` means no compression. Level 1 uses a minimum of CPU
  75     resources and achieves weak compression ratios, while level 9 offers
  76     best compression but is slow in terms of CPU consumption on the server
  77     side. Use high levels with very slow network connections.
  78     Default value is `2`.
  79
  80 `capabilities` *Read only*
  81   - Is an `Object` indicating which optional extensions are available
  82     on the server. Some methods may only be called if the corresponding
  83     capability is set. The following capabilities are defined:
  84
  85     | name     | type      | description
  86     | -------- | --------- | -----------
  87     | `power`  | `boolean` | Machine power control is available
  88
  89 ### Events
  90
  91 [`connect`](#connect)
  92   - The `connect` event is fired when the `RFB` object has completed
  93     the connection and handshaking with the server.
  94
  95 [`disconnect`](#disconnected)
  96   - The `disconnect` event is fired when the `RFB` object disconnects.
  97
  98 [`credentialsrequired`](#credentialsrequired)
  99   - The `credentialsrequired` event is fired when more credentials must
 100     be given to continue.
 101
 102 [`securityfailure`](#securityfailure)
 103   - The `securityfailure` event is fired when the security negotiation
 104     with the server fails.
 105
 106 [`clipboard`](#clipboard)
 107   - The `clipboard` event is fired when clipboard data is received from
 108     the server.
 109
 110 [`bell`](#bell)
 111   - The `bell` event is fired when a audible bell request is received
 112     from the server.
 113
 114 [`desktopname`](#desktopname)
 115   - The `desktopname` event is fired when the remote desktop name
 116     changes.
 117
 118 [`capabilities`](#capabilities)
 119   - The `capabilities` event is fired when `RFB.capabilities` is
 120     updated.
 121
 122 ### Methods
 123
 124 [`RFB.disconnect()`](#rfbdisconnect)
 125   - Disconnect from the server.
 126
 127 [`RFB.sendCredentials()`](#rfbsendcredentials)
 128   - Send credentials to server. Should be called after the
 129     [`credentialsrequired`](#credentialsrequired) event has fired.
 130
 131 [`RFB.sendKey()`](#rfbsendKey)
 132   - Send a key event.
 133
 134 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
 135   - Send Ctrl-Alt-Del key sequence.
 136
 137 [`RFB.focus()`](#rfbfocus)
 138   - Move keyboard focus to the remote session.
 139
 140 [`RFB.blur()`](#rfbblur)
 141   - Remove keyboard focus from the remote session.
 142
 143 [`RFB.machineShutdown()`](#rfbmachineshutdown)
 144   - Request a shutdown of the remote machine.
 145
 146 [`RFB.machineReboot()`](#rfbmachinereboot)
 147   - Request a reboot of the remote machine.
 148
 149 [`RFB.machineReset()`](#rfbmachinereset)
 150   - Request a reset of the remote machine.
 151
 152 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
 153   - Send clipboard contents to server.
 154
 155 ### Details
 156
 157 #### RFB()
 158
 159 The `RFB()` constructor returns a new `RFB` object and initiates a new
 160 connection to a specified VNC server.
 161
 162 ##### Syntax
 163
 164     let rfb = new RFB( target, url [, options] );
 165
 166 ###### Parameters
 167
 168 **`target`**
 169   - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
 170     that specifies where the `RFB` object should attach itself. The
 171     existing contents of the `HTMLElement` will be untouched, but new
 172     elements will be added during the lifetime of the `RFB` object.
 173
 174 **`url`**
 175   - A `DOMString` specifying the VNC server to connect to. This must be
 176     a valid WebSocket URL.
 177
 178 **`options`** *Optional*
 179   - An `Object` specifying extra details about how the connection
 180     should be made.
 181
 182     Possible options:
 183
 184     `shared`
 185       - A `boolean` indicating if the remote server should be shared or
 186         if any other connected clients should be disconnected. Enabled
 187         by default.
 188
 189     `credentials`
 190       - An `Object` specifying the credentials to provide to the server
 191         when authenticating. The following credentials are possible:
 192
 193         | name         | type        | description
 194         | ------------ | ----------- | -----------
 195         | `"username"` | `DOMString` | The user that authenticates
 196         | `"password"` | `DOMString` | Password for the user
 197         | `"target"`   | `DOMString` | Target machine or session
 198
 199     `repeaterID`
 200       - A `DOMString` specifying the ID to provide to any VNC repeater
 201         encountered.
 202
 203     `wsProtocols`
 204       - An `Array` of `DOMString`s specifying the sub-protocols to use
 205         in the WebSocket connection. Empty by default.
 206
 207 #### connect
 208
 209 The `connect` event is fired after all the handshaking with the server
 210 is completed and the connection is fully established. After this event
 211 the `RFB` object is ready to recieve graphics updates and to send input.
 212
 213 #### disconnect
 214
 215 The `disconnect` event is fired when the connection has been
 216 terminated. The `detail` property is an `Object` that contains the
 217 property `clean`. `clean` is a `boolean` indicating if the termination
 218 was clean or not. In the event of an unexpected termination or an error
 219 `clean` will be set to false.
 220
 221 #### credentialsrequired
 222
 223 The `credentialsrequired` event is fired when the server requests more
 224 credentials than were specified to [`RFB()`](#rfb-1). The `detail`
 225 property is an `Object` containing the property `types` which is an
 226 `Array` of `DOMString` listing the credentials that are required.
 227
 228 #### securityfailure
 229
 230 The `securityfailure` event is fired when the handshaking process with
 231 the server fails during the security negotiation step. The `detail`
 232 property is an `Object` containing the following properties:
 233
 234 | Property | Type        | Description
 235 | -------- | ----------- | -----------
 236 | `status` | `long`      | The failure status code
 237 | `reason` | `DOMString` | The **optional** reason for the failure
 238
 239 The property `status` corresponds to the
 240 [SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult)
 241 status code in cases of failure. A status of zero will not be sent in
 242 this event since that indicates a successful security handshaking
 243 process. The optional property `reason` is provided by the server and
 244 thus the language of the string is not known. However most servers will
 245 probably send English strings. The server can choose to not send a
 246 reason and in these cases the `reason` property will be omitted.
 247
 248 #### clipboard
 249
 250 The `clipboard` event is fired when the server has sent clipboard data.
 251 The `detail` property is an `Object` containing the property `text`
 252 which is a `DOMString` with the clipboard data.
 253
 254 #### bell
 255
 256 The `bell` event is fired when the server has requested an audible
 257 bell.
 258
 259 #### desktopname
 260
 261 The `desktopname` event is fired when the name of the remote desktop
 262 changes. The `detail` property is an `Object` with the property `name`
 263 which is a `DOMString` specifying the new name.
 264
 265 #### capabilities
 266
 267 The `capabilities` event is fired whenever an entry is added or removed
 268 from `RFB.capabilities`. The `detail` property is an `Object` with the
 269 property `capabilities` containing the new value of `RFB.capabilities`.
 270
 271 #### RFB.disconnect()
 272
 273 The `RFB.disconnect()` method is used to disconnect from the currently
 274 connected server.
 275
 276 ##### Syntax
 277
 278     RFB.disconnect( );
 279
 280 #### RFB.sendCredentials()
 281
 282 The `RFB.sendCredentials()` method is used to provide the missing
 283 credentials after a `credentialsrequired` event has been fired.
 284
 285 ##### Syntax
 286
 287     RFB.sendCredentials( credentials );
 288
 289 ###### Parameters
 290
 291 **`credentials`**
 292   - An `Object` specifying the credentials to provide to the server
 293     when authenticating. See [`RFB()`](#rfb-1) for details.
 294
 295 #### RFB.sendKey()
 296
 297 The `RFB.sendKey()` method is used to send a key event to the server.
 298
 299 ##### Syntax
 300
 301     RFB.sendKey( keysym, code [, down] );
 302
 303 ###### Parameters
 304
 305 **`keysym`**
 306   - A `long` specifying the RFB keysym to send. Can be `0` if a valid
 307     **`code`** is specified.
 308
 309 **`code`**
 310   - A `DOMString` specifying the physical key to send. Valid values are
 311     those that can be specified to
 312     [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
 313     If the physical key cannot be determined then `null` shall be
 314     specified.
 315
 316 **`down`** *Optional*
 317   - A `boolean` specifying if a press or a release event should be
 318     sent. If omitted then both a press and release event are sent.
 319
 320 #### RFB.sendCtrlAltDel()
 321
 322 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
 323 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
 324 around [`RFB.sendKey()`](#rfbsendkey).
 325
 326 ##### Syntax
 327
 328     RFB.sendCtrlAltDel( );
 329
 330 #### RFB.focus()
 331
 332 The `RFB.focus()` method sets the keyboard focus on the remote session.
 333 Keyboard events will be sent to the remote server after this point.
 334
 335 ##### Syntax
 336
 337     RFB.focus( );
 338
 339 #### RFB.blur()
 340
 341 The `RFB.blur()` method remove keyboard focus on the remote session.
 342 Keyboard events will no longer be sent to the remote server after this
 343 point.
 344
 345 ##### Syntax
 346
 347     RFB.blur( );
 348
 349 #### RFB.machineShutdown()
 350
 351 The `RFB.machineShutdown()` method is used to request to shut down the
 352 remote machine. The capability `power` must be set for this method to
 353 have any effect.
 354
 355 ##### Syntax
 356
 357     RFB.machineShutdown( );
 358
 359 #### RFB.machineReboot()
 360
 361 The `RFB.machineReboot()` method is used to request a clean reboot of
 362 the remote machine. The capability `power` must be set for this method
 363 to have any effect.
 364
 365 ##### Syntax
 366
 367     RFB.machineReboot( );
 368
 369 #### RFB.machineReset()
 370
 371 The `RFB.machineReset()` method is used to request a forced reset of
 372 the remote machine. The capability `power` must be set for this method
 373 to have any effect.
 374
 375 ##### Syntax
 376
 377     RFB.machineReset( );
 378
 379 #### RFB.clipboardPasteFrom()
 380
 381 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
 382 to the remote server.
 383
 384 ##### Syntax
 385
 386     RFB.clipboardPasteFrom( text );
 387
 388 ###### Parameters
 389
 390 **`text`**
 391   - A `DOMString` specifying the clipboard data to send. Currently only
 392   characters from ISO 8859-1 are supported.