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