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