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 canvas when a `mousedown` or `touchstart` event is
  27     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 `viewportScale`
  36   - Is a `double` indicating how the framebuffer contents should be
  37     scaled before being rendered on to the canvas. See also
  38     [`RFB.autoscale()`](#rfbautoscale). Is set to `1.0` by default.
  39
  40 `clipViewport`
  41   - Is a `boolean` indicating if the canvas should be clipped to its
  42     container. When disabled the container must be able to handle the
  43     resulting overflow. Disabled by default.
  44
  45 `dragViewport`
  46   - Is a `boolean` indicating if mouse events should control the
  47     relative position of a clipped canvas. Only relevant if
  48     `clipViewport` is enabled. Disabled by default.
  49
  50 `isClipped` *Read only*
  51   - Is a `boolean` indicating if the framebuffer is larger than the
  52     current canvas, i.e. it is being clipped.
  53
  54 `capabilities` *Read only*
  55   - Is an `Object` indicating which optional extensions are available
  56     on the server. Some methods may only be called if the corresponding
  57     capability is set. The following capabilities are defined:
  58
  59     | name     | type      | description
  60     | -------- | --------- | -----------
  61     | `power`  | `boolean` | Machine power control is available
  62     | `resize` | `boolean` | The framebuffer can be resized
  63
  64 ### Events
  65
  66 [`connect`](#connect)
  67   - The `connect` event is fired when the `RFB` object has completed
  68     the connection and handshaking with the server.
  69
  70 [`disconnect`](#disconnected)
  71   - The `disconnect` event is fired when the `RFB` object disconnects.
  72
  73 [`credentialsrequired`](#credentialsrequired)
  74   - The `credentialsrequired` event is fired when more credentials must
  75     be given to continue.
  76
  77 [`clipboard`](#clipboard)
  78   - The `clipboard` event is fired when clipboard data is received from
  79     the server.
  80
  81 [`bell`](#bell)
  82   - The `bell` event is fired when a audible bell request is received
  83     from the server.
  84
  85 [`fbresize`](#fbresize)
  86   - The `fbresize` event is fired when the framebuffer size is changed.
  87
  88 [`desktopname`](#desktopname)
  89   - The `desktopname` event is fired when the remote desktop name
  90     changes.
  91
  92 [`capabilities`](#capabilities)
  93   - The `capabilities` event is fired when `RFB.capabilities` is
  94     updated.
  95
  96 ### Methods
  97
  98 [`RFB.disconnect()`](#rfbdisconnect)
  99   - Disconnect from the server.
 100
 101 [`RFB.sendCredentials()`](#rfbsendcredentials)
 102   - Send credentials to server. Should be called after the
 103     [`credentialsrequired`](#credentialsrequired) event has fired.
 104
 105 [`RFB.sendKey()`](#rfbsendKey)
 106   - Send a key event.
 107
 108 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
 109   - Send Ctrl-Alt-Del key sequence.
 110
 111 [`RFB.machineShutdown()`](#rfbmachineshutdown)
 112   - Request a shutdown of the remote machine.
 113
 114 [`RFB.machineReboot()`](#rfbmachinereboot)
 115   - Request a reboot of the remote machine.
 116
 117 [`RFB.machineReset()`](#rfbmachinereset)
 118   - Request a reset of the remote machine.
 119
 120 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
 121   - Send clipboard contents to server.
 122
 123 [`RFB.autoscale()`](#rfbautoscale)
 124   - Set `RFB.viewportScale` so that the framebuffer fits a specified
 125     container.
 126
 127 [`RFB.requestDesktopSize()`](#rfbrequestDesktopSize)
 128   - Send a request to change the remote desktop size.
 129
 130 [`RFB.viewportChangeSize()`](#rfbviewportChangeSize)
 131   - Change size of the viewport.
 132
 133 ### Details
 134
 135 #### RFB()
 136
 137 The `RFB()` constructor returns a new `RFB` object and initiates a new
 138 connection to a specified VNC server.
 139
 140 ##### Syntax
 141
 142     var rfb = new RFB( target, url [, options] );
 143
 144 ###### Parameters
 145
 146 **`target`**
 147   - A [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement)
 148     that specifies where graphics should be rendered and input events
 149     should be monitored.
 150
 151 **`url`**
 152   - A `DOMString` specifying the VNC server to connect to. This must be
 153     a valid WebSocket URL.
 154
 155 **`options`** *Optional*
 156   - An `Object` specifying extra details about how the connection
 157     should be made.
 158
 159     Possible options:
 160
 161     `shared`
 162       - A `boolean` indicating if the remote server should be shared or
 163         if any other connected clients should be disconnected. Enabled
 164         by default.
 165
 166     `credentials`
 167       - An `Object` specifying the credentials to provide to the server
 168         when authenticating. The following credentials are possible:
 169
 170         | name         | type        | description
 171         | ------------ | ----------- | -----------
 172         | `"username"` | `DOMString` | The user that authenticates
 173         | `"password"` | `DOMString` | Password for the user
 174         | `"target"`   | `DOMString` | Target machine or session
 175
 176     `repeaterID`
 177       - A `DOMString` specifying the ID to provide to any VNC repeater
 178         encountered.
 179
 180 #### connect
 181
 182 The `connect` event is fired after all the handshaking with the server
 183 is completed and the connection is fully established. After this event
 184 the `RFB` object is ready to recieve graphics updates and to send input.
 185
 186 #### disconnect
 187
 188 The `disconnect` event is fired when the connection has been
 189 terminated. The `detail` property is an `Object` the optionally
 190 contains the property `reason`. `reason` is a `DOMString` specifying
 191 the reason in the event of an unexpected termination. `reason` will be
 192 omitted for a clean termination.
 193
 194 #### credentialsrequired
 195
 196 The `credentialsrequired` event is fired when the server requests more
 197 credentials than were specified to [`RFB()`](#rfb-1). The `detail`
 198 property is an `Object` containing the property `types` which is an
 199 `Array` of `DOMString` listing the credentials that are required.
 200
 201 #### clipboard
 202
 203 The `clipboard` event is fired when the server has sent clipboard data.
 204 The `detail` property is an `Object` containing the property `text`
 205 which is a `DOMString` with the clipboard data.
 206
 207 #### bell
 208
 209 The `bell` event is fired when the server has requested an audible
 210 bell.
 211
 212 #### fbresize
 213
 214 The `fbresize` event is fired when the framebuffer has changed
 215 dimensions. The `detail` property is an `Object` with the properties
 216 `width` and `height` specifying the new dimensions.
 217
 218 #### desktopname
 219
 220 The `desktopname` event is fired when the name of the remote desktop
 221 changes. The `detail` property is an `Object` with the property `name`
 222 which is a `DOMString` specifying the new name.
 223
 224 #### capabilities
 225
 226 The `capabilities` event is fired whenever an entry is added or removed
 227 from `RFB.capabilities`. The `detail` property is an `Object` with the
 228 property `capabilities` containing the new value of `RFB.capabilities`.
 229
 230 #### RFB.disconnect()
 231
 232 The `RFB.disconnect()` method is used to disconnect from the currently
 233 connected server.
 234
 235 ##### Syntax
 236
 237     RFB.disconnect( );
 238
 239 #### RFB.sendCredentials()
 240
 241 The `RFB.sendCredentials()` method is used to provide the missing
 242 credentials after a `credentialsrequired` event has been fired.
 243
 244 ##### Syntax
 245
 246     RFB.sendCredentials( credentials );
 247
 248 ###### Parameters
 249
 250 **`credentials`**
 251   - An `Object` specifying the credentials to provide to the server
 252     when authenticating. See [`RFB()`](#rfb-1) for details.
 253
 254 #### RFB.sendKey()
 255
 256 The `RFB.sendKey()` method is used to send a key event to the server.
 257
 258 ##### Syntax
 259
 260     RFB.sendKey( keysym, code [, down] );
 261
 262 ###### Parameters
 263
 264 **`keysym`**
 265   - A `long` specifying the RFB keysym to send. Can be `0` if a valid
 266     **`code`** is specified.
 267
 268 **`code`**
 269   - A `DOMString` specifying the physical key to send. Valid values are
 270     those that can be specified to
 271     [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
 272     If the physical key cannot be determined then `null` shall be
 273     specified.
 274
 275 **`down`** *Optional*
 276   - A `boolean` specifying if a press or a release event should be
 277     sent. If omitted then both a press and release event are sent.
 278
 279 #### RFB.sendCtrlAltDel()
 280
 281 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
 282 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
 283 around [`RFB.sendKey()`](#rfbsendkey).
 284
 285 ##### Syntax
 286
 287     RFB.sendCtrlAltDel( );
 288
 289 #### RFB.machineShutdown()
 290
 291 The `RFB.machineShutdown()` method is used to request to shut down the
 292 remote machine. The capability `power` must be set for this method to
 293 have any effect.
 294
 295 ##### Syntax
 296
 297     RFB.machineShutdown( );
 298
 299 #### RFB.machineReboot()
 300
 301 The `RFB.machineReboot()` method is used to request a clean reboot of
 302 the remote machine. The capability `power` must be set for this method
 303 to have any effect.
 304
 305 ##### Syntax
 306
 307     RFB.machineReboot( );
 308
 309 #### RFB.machineReset()
 310
 311 The `RFB.machineReset()` method is used to request a forced reset of
 312 the remote machine. The capability `power` must be set for this method
 313 to have any effect.
 314
 315 ##### Syntax
 316
 317     RFB.machineReset( );
 318
 319 #### RFB.clipboardPasteFrom()
 320
 321 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
 322 to the remote server.
 323
 324 ##### Syntax
 325
 326     RFB.clipboardPasteFrom( text );
 327
 328 ###### Parameters
 329
 330 **`text`**
 331   - A `DOMString` specifying the clipboard data to send. Currently only
 332   characters from ISO 8859-1 are supported.
 333
 334 #### RFB.autoscale()
 335
 336 The `RFB.autoscale()` method is used to automatically adjust
 337 `RFB.viewportScale` to fit given dimensions.
 338
 339 ##### Syntax
 340
 341     RFB.autoscale( width, height );
 342
 343 ###### Parameters
 344
 345 **`width`**
 346   - A `long` specifying the maximum width of the canvas in CSS pixels.
 347
 348 **`height`**
 349   - A `long` specifying the maximum height of the canvas in CSS pixels.
 350
 351 #### RFB.requestDesktopSize()
 352
 353 The `RFB.requestDesktopSize()` method is used to request a change of
 354 the framebuffer. The capability `resize` must be set for this method to
 355 have any effect.
 356
 357 Note that this is merely a request and the server may deny it.
 358 The [`fbresize`](#fbresize) event will be fired when the framebuffer
 359 actually changes dimensions.
 360
 361 ##### Syntax
 362
 363     RFB.requestDesktopSize( width, height );
 364
 365 ###### Parameters
 366
 367 **`width`**
 368   - A `long` specifying the new requested width in CSS pixels.
 369
 370 **`height`**
 371   - A `long` specifying the new requested height in CSS pixels.
 372
 373 #### RFB.viewportChangeSize()
 374
 375 The `RFB.viewportChangeSize()` method is used to change the size of the
 376 canvas rather than the underlying framebuffer.
 377
 378 This method has no effect if `RFB.clipViewport` is set to `false`.
 379
 380 ##### Syntax
 381
 382     RFB.viewportChangeSize( width, height );
 383
 384 ###### Parameters
 385
 386 **`width`**
 387   - A `long` specifying the new width in CSS pixels.
 388
 389 **`height`**
 390   - A `long` specifying the new height in CSS pixels.