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