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 `touchButton`
  25   - Is a `long` controlling the button mask that should be simulated
  26     when a touch event is recieved. Uses the same values as
  27     [`MouseEvent.button`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button).
  28     Is set to `1` by default.
  29
  30 `viewportScale`
  31   - Is a `double` indicating how the framebuffer contents should be
  32     scaled before being rendered on to the canvas. See also
  33     [`RFB.autoscale()`](#rfbautoscale). Is set to `1.0` by default.
  34
  35 `clipViewport`
  36   - Is a `boolean` indicating if the canvas should be clipped to its
  37     container. When disabled the container must be able to handle the
  38     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 canvas. Only relevant if
  43     `clipViewport` is enabled. Disabled by default.
  44
  45 `isClipped` *Read only*
  46   - Is a `boolean` indicating if the framebuffer is larger than the
  47     current canvas, i.e. it is being clipped.
  48
  49 `capabilities` *Read only*
  50   - Is an `Object` indicating which optional extensions are available
  51     on the server. Some methods may only be called if the corresponding
  52     capability is set. The following capabilities are defined:
  53
  54     | name     | type      | description
  55     | -------- | --------- | -----------
  56     | `power`  | `boolean` | Machine power control is available
  57     | `resize` | `boolean` | The framebuffer can be resized
  58
  59 ### Event handlers
  60
  61 [`RFB.onupdatestate()`](#rfbonupdatestate)
  62   - An event handler called when the connection state of the `RFB`
  63     object changes.
  64
  65 [`RFB.onnotification()`](#rfbonnotification)
  66   - An event handler called when the `RFB` usage has a message to
  67     display to the user.
  68
  69 [`RFB.ondisconnected()`](#rfbondisconnected)
  70   - An event handler called when the `RFB` object disconnects.
  71
  72 [`RFB.oncredentialsrequired()`](#rfboncredentialsrequired)
  73   - An event hander called when more credentials must be given to
  74     continue.
  75
  76 [`RFB.onclipboard()`](#rfbonclipboard)
  77   - An event handler called when clipboard data is received from the
  78     server.
  79
  80 [`RFB.onbell()`](#rfbonbell)
  81   - An event handler called when a audible bell request is received
  82     from the server.
  83
  84 [`RFB.onfbresize()`](#rfbonfbresize)
  85   - An event handler called when the framebuffer size is changed.
  86
  87 [`RFB.ondesktopname()`](#rfbondesktopname)
  88   - An event handler called when the remote desktop name changes.
  89
  90 [`RFB.oncapabilities()`](#rfboncapabilities)
  91   - An event handler called when `RFB.capabilities` is updated.
  92
  93 ### Methods
  94
  95 [`RFB.disconnect()`](#rfbdisconnect)
  96   - Disconnect from the server.
  97
  98 [`RFB.sendCredentials()`](#rfbsendcredentials)
  99   - Send credentials to server. Should be called after
 100     [`oncredentialsrequired`](#rfboncredentialsrequired) has been
 101     called.
 102
 103 [`RFB.sendKey()`](#rfbsendKey)
 104   - Send a key event.
 105
 106 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
 107   - Send Ctrl-Alt-Del key sequence.
 108
 109 [`RFB.machineShutdown()`](#rfbmachineshutdown)
 110   - Request a shutdown of the remote machine.
 111
 112 [`RFB.machineReboot()`](#rfbmachinereboot)
 113   - Request a reboot of the remote machine.
 114
 115 [`RFB.machineReset()`](#rfbmachinereset)
 116   - Request a reset of the remote machine.
 117
 118 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
 119   - Send clipboard contents to server.
 120
 121 [`RFB.autoscale()`](#rfbautoscale)
 122   - Set `RFB.viewportScale` so that the framebuffer fits a specified
 123     container.
 124
 125 [`RFB.requestDesktopSize()`](#rfbrequestDesktopSize)
 126   - Send a request to change the remote desktop size.
 127
 128 [`RFB.viewportChangeSize()`](#rfbviewportChangeSize)
 129   - Change size of the viewport.
 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 [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement)
 146     that specifies where graphics should be rendered and input events
 147     should be monitored.
 148
 149 **`url`**
 150   - A `DOMString` specifying the VNC server to connect to. This must be
 151     a valid WebSocket URL.
 152
 153 **`options`** *Optional*
 154   - An `Object` specifying extra details about how the connection
 155     should be made.
 156
 157     Possible options:
 158
 159     `shared`
 160       - A `boolean` indicating if the remote server should be shared or
 161         if any other connected clients should be disconnected. Enabled
 162         by default.
 163
 164     `credentials`
 165       - An `Object` specifying the credentials to provide to the server
 166         when authenticating. The following credentials are possible:
 167
 168         | name         | type        | description
 169         | ------------ | ----------- | -----------
 170         | `"username"` | `DOMString` | The user that authenticates
 171         | `"password"` | `DOMString` | Password for the user
 172         | `"target"`   | `DOMString` | Target machine or session
 173
 174     `repeaterID`
 175       - A `DOMString` specifying the ID to provide to any VNC repeater
 176         encountered.
 177
 178 #### RFB.onupdatestate
 179
 180 The `onupdatestate` event handler is fired after the noVNC connection
 181 state changes. Here is a list of the states that are reported:
 182
 183 | connection state  | description
 184 | ----------------- | ------------
 185 | `"connecting"`    | starting to connect
 186 | `"connected"`     | connected normally
 187 | `"disconnecting"` | starting to disconnect
 188 | `"disconnected"`  | disconnected
 189
 190 Note that a `RFB` objects can not transition from the disconnected
 191 state in any way, a new instance of the object has to be created for
 192 new connections.
 193
 194 ##### Syntax
 195
 196     RFB.onupdatestate = function(rfb, state) { ... }
 197
 198 #### RFB.onnotification
 199
 200 The `onnotification` event handler is fired when the `RFB` object wants
 201 a message displayed to the user. **`msg`** is a `DOMString` specifying
 202 the actual message, and **`level`** is a `DOMString` indicating the
 203 severity of the message. The following levels are currently defined:
 204
 205   - `"normal"`
 206   - `"warn"`
 207   - `"error"`
 208
 209 ##### Syntax
 210
 211     RFB.onnotification = function(rfb, msg, level) { ... }
 212
 213 #### RFB.ondisconnected
 214
 215 The `ondisconnected` event handler is fired when the connection has
 216 been terminated. **`reason`** is `undefined` for a clean termination
 217 and a `DOMString` specifying the reason in the event of an unexpected
 218 termination.
 219
 220 ##### Syntax
 221
 222     RFB.ondisconnected = function(rfb, reason) { ... }
 223
 224 #### RFB.oncredentialsrequired
 225
 226 The `oncredentialsrequired` event handler is fired when the server
 227 requests more credentials than were specified to [`RFB()`](#rfb-1). The
 228 **`types`** argument is a list of all the credentials that are
 229 required.
 230
 231 ##### Syntax
 232
 233     RFB.oncredentialsrequired = function(rfb, types) { ... }
 234
 235 #### RFB.onclipboard
 236
 237 The `onclipboard` event handler is fired when the server has sent
 238 clipboard data.
 239
 240 ##### Syntax
 241
 242     RFB.onclipboard = function(rfb, text) { ... }
 243
 244 #### RFB.onbell
 245
 246 The `onbell` event handler is fired when the server has requested an
 247 audible bell.
 248
 249 ##### Syntax
 250
 251     RFB.onbell = function(rfb) { ... }
 252
 253 #### RFB.onfbresize
 254
 255 The `onfbresize` event handler is fired when the framebuffer has
 256 changed dimensions.
 257
 258 ##### Syntax
 259
 260     RFB.onfbresize = function(rfb, width, height) { ... }
 261
 262 #### RFB.ondesktopname
 263
 264 The `ondesktopname` event handler is fired when the name of the remote
 265 desktop changes.
 266
 267 ##### Syntax
 268
 269     RFB.ondesktopname = function(rfb, name) { ... }
 270
 271 #### RFB.oncapabilities
 272
 273 The `oncapabilities` event handler is fired whenever an entry is added
 274 or removed from `RFB.capabilities`.
 275
 276 ##### Syntax
 277
 278     RFB.oncapabilities = function(rfb, capabilites) { ... }
 279
 280 #### RFB.disconnect()
 281
 282 The `RFB.disconnect()` method is used to disconnect from the currently
 283 connected server.
 284
 285 ##### Syntax
 286
 287     RFB.disconnect( );
 288
 289 #### RFB.sendCredentials()
 290
 291 The `RFB.sendCredentials()` method is used to provide the missing
 292 credentials after `RFB.oncredentialsrequired` has been fired.
 293
 294 ##### Syntax
 295
 296     RFB.sendCredentials( credentials );
 297
 298 ###### Parameters
 299
 300 **`credentials`**
 301   - An `Object` specifying the credentials to provide to the server
 302     when authenticating. See [`RFB()`](#rfb-1) for details.
 303
 304 #### RFB.sendKey()
 305
 306 The `RFB.sendKey()` method is used to send a key event to the server.
 307
 308 ##### Syntax
 309
 310     RFB.sendKey( keysym, code [, down] );
 311
 312 ###### Parameters
 313
 314 **`keysym`**
 315   - A `long` specifying the RFB keysym to send. Can be `0` if a valid
 316     **`code`** is specified.
 317
 318 **`code`**
 319   - A `DOMString` specifying the physical key to send. Valid values are
 320     those that can be specified to
 321     [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
 322     If the physical key cannot be determined then `null` shall be
 323     specified.
 324
 325 **`down`** *Optional*
 326   - A `boolean` specifying if a press or a release event should be
 327     sent. If omitted then both a press and release event are sent.
 328
 329 #### RFB.sendCtrlAltDel()
 330
 331 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
 332 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
 333 around [`RFB.sendKey()`](#rfbsendkey).
 334
 335 ##### Syntax
 336
 337     RFB.sendCtrlAltDel( );
 338
 339 #### RFB.machineShutdown()
 340
 341 The `RFB.machineShutdown()` method is used to request to shut down the
 342 remote machine. The capability `power` must be set for this method to
 343 have any effect.
 344
 345 ##### Syntax
 346
 347     RFB.machineShutdown( );
 348
 349 #### RFB.machineReboot()
 350
 351 The `RFB.machineReboot()` method is used to request a clean reboot of
 352 the remote machine. The capability `power` must be set for this method
 353 to have any effect.
 354
 355 ##### Syntax
 356
 357     RFB.machineReboot( );
 358
 359 #### RFB.machineReset()
 360
 361 The `RFB.machineReset()` method is used to request a forced reset of
 362 the remote machine. The capability `power` must be set for this method
 363 to have any effect.
 364
 365 ##### Syntax
 366
 367     RFB.machineReset( );
 368
 369 #### RFB.clipboardPasteFrom()
 370
 371 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
 372 to the remote server.
 373
 374 ##### Syntax
 375
 376     RFB.clipboardPasteFrom( text );
 377
 378 ###### Parameters
 379
 380 **`text`**
 381   - A `DOMString` specifying the clipboard data to send. Currently only
 382   characters from ISO 8859-1 are supported.
 383
 384 #### RFB.autoscale()
 385
 386 The `RFB.autoscale()` method is used to automatically adjust
 387 `RFB.viewportScale` to fit given dimensions.
 388
 389 ##### Syntax
 390
 391     RFB.autoscale( width, height );
 392
 393 ###### Parameters
 394
 395 **`width`**
 396   - A `long` specifying the maximum width of the canvas in CSS pixels.
 397
 398 **`height`**
 399   - A `long` specifying the maximum height of the canvas in CSS pixels.
 400
 401 #### RFB.requestDesktopSize()
 402
 403 The `RFB.requestDesktopSize()` method is used to request a change of
 404 the framebuffer. The capability `resize` must be set for this method to
 405 have any effect.
 406
 407 Note that this is merely a request and the server may deny it.
 408 [`RFB.onfbresize`](#rfbonfbresize) will be called when the framebuffer
 409 actually changes dimensions.
 410
 411 ##### Syntax
 412
 413     RFB.requestDesktopSize( width, height );
 414
 415 ###### Parameters
 416
 417 **`width`**
 418   - A `long` specifying the new requested width in CSS pixels.
 419
 420 **`height`**
 421   - A `long` specifying the new requested height in CSS pixels.
 422
 423 #### RFB.viewportChangeSize()
 424
 425 The `RFB.viewportChangeSize()` method is used to change the size of the
 426 canvas rather than the underlying framebuffer.
 427
 428 This method has no effect if `RFB.clipViewport` is set to `false`.
 429
 430 ##### Syntax
 431
 432     RFB.viewportChangeSize( width, height );
 433
 434 ###### Parameters
 435
 436 **`width`**
 437   - A `long` specifying the new width in CSS pixels.
 438
 439 **`height`**
 440   - A `long` specifying the new height in CSS pixels.