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