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.connect()`](#rfbconnect)
  96   - Connect to a server.
  97
  98 [`RFB.disconnect()`](#rfbdisconnect)
  99   - Disconnect from the server.
 100
 101 [`RFB.sendCredentials()`](#rfbsendcredentials)
 102   - Send credentials to server. Should be called after
 103     [`oncredentialsrequired`](#rfboncredentialsrequired) has been
 104     called.
 105
 106 [`RFB.sendKey()`](#rfbsendKey)
 107   - Send a key event.
 108
 109 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
 110   - Send Ctrl-Alt-Del key sequence.
 111
 112 [`RFB.machineShutdown()`](#rfbmachineshutdown)
 113   - Request a shutdown of the remote machine.
 114
 115 [`RFB.machineReboot()`](#rfbmachinereboot)
 116   - Request a reboot of the remote machine.
 117
 118 [`RFB.machineReset()`](#rfbmachinereset)
 119   - Request a reset of the remote machine.
 120
 121 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
 122   - Send clipboard contents to server.
 123
 124 [`RFB.autoscale()`](#rfbautoscale)
 125   - Set `RFB.viewportScale` so that the framebuffer fits a specified
 126     container.
 127
 128 [`RFB.requestDesktopSize()`](#rfbrequestDesktopSize)
 129   - Send a request to change the remote desktop size.
 130
 131 [`RFB.viewportChangeSize()`](#rfbviewportChangeSize)
 132   - Change size of the viewport.
 133
 134 ### Details
 135
 136 #### RFB()
 137
 138 The `RFB()` constructor returns a new `RFB` object. The object will
 139 initially be disconnected and [`RFB.connect()`](#rfbconnect) must be
 140 called before the object will be useful.
 141
 142 ##### Syntax
 143
 144     var rfb = new RFB( target );
 145
 146 ###### Parameters
 147
 148 **`target`**
 149   - A [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement)
 150     that specifies where graphics should be rendered and input events
 151     should be monitored.
 152
 153 #### RFB.onupdatestate
 154
 155 The `onupdatestate` event handler is fired after the noVNC connection
 156 state changes. Here is a list of the states that are reported:
 157
 158 | connection state  | description
 159 | ----------------- | ------------
 160 | `"connecting"`    | starting to connect
 161 | `"connected"`     | connected normally
 162 | `"disconnecting"` | starting to disconnect
 163 | `"disconnected"`  | disconnected
 164
 165 Note that a `RFB` objects can not transition from the disconnected
 166 state in any way, a new instance of the object has to be created for
 167 new connections.
 168
 169 ##### Syntax
 170
 171     RFB.onupdatestate = function(rfb, state) { ... }
 172
 173 #### RFB.onnotification
 174
 175 The `onnotification` event handler is fired when the `RFB` object wants
 176 a message displayed to the user. **`msg`** is a `DOMString` specifying
 177 the actual message, and **`level`** is a `DOMString` indicating the
 178 severity of the message. The following levels are currently defined:
 179
 180   - `"normal"`
 181   - `"warn"`
 182   - `"error"`
 183
 184 **`options`** is currently unused.
 185
 186 ##### Syntax
 187
 188     RFB.onnotification = function(rfb, msg, level, options) { ... }
 189
 190 #### RFB.ondisconnected
 191
 192 The `ondisconnected` event handler is fired when the connection has
 193 been terminated. **`reason`** is `undefined` for a clean termination
 194 and a `DOMString` specifying the reason in the event of an unexpected
 195 termination.
 196
 197 ##### Syntax
 198
 199     RFB.ondisconnected = function(rfb, reason) { ... }
 200
 201 #### RFB.oncredentialsrequired
 202
 203 The `oncredentialsrequired` event handler is fired when the server
 204 requests more credentials than were specified to
 205 [`RFB.connect()`](#rfbconnect). The **`types`** argument is a list of
 206 all the credentials that are required.
 207
 208 ##### Syntax
 209
 210     RFB.oncredentialsrequired = function(rfb, types) { ... }
 211
 212 #### RFB.onclipboard
 213
 214 The `onclipboard` event handler is fired when the server has sent
 215 clipboard data.
 216
 217 ##### Syntax
 218
 219     RFB.onclipboard = function(rfb, text) { ... }
 220
 221 #### RFB.onbell
 222
 223 The `onbell` event handler is fired when the server has requested an
 224 audible bell.
 225
 226 ##### Syntax
 227
 228     RFB.onbell = function(rfb) { ... }
 229
 230 #### RFB.onfbresize
 231
 232 The `onfbresize` event handler is fired when the framebuffer has
 233 changed dimensions.
 234
 235 ##### Syntax
 236
 237     RFB.onfbresize = function(rfb, width, height) { ... }
 238
 239 #### RFB.ondesktopname
 240
 241 The `ondesktopname` event handler is fired when the name of the remote
 242 desktop changes.
 243
 244 ##### Syntax
 245
 246     RFB.ondesktopname = function(rfb, name) { ... }
 247
 248 #### RFB.oncapabilities
 249
 250 The `oncapabilities` event handler is fired whenever an entry is added
 251 or removed from `RFB.capabilities`.
 252
 253 ##### Syntax
 254
 255     RFB.oncapabilities = function(rfb, capabilites) { ... }
 256
 257 #### RFB.connect()
 258
 259 The `RFB.connect()` method is used to initiate a new connection to a
 260 specified VNC server.
 261
 262 ##### Syntax
 263
 264     RFB.connect( url [, options] );
 265
 266 ###### Parameters
 267
 268 **`url`**
 269   - A `DOMString` specifying the VNC server to connect to. This must be
 270     a valid WebSocket URL.
 271
 272 **`options`** *Optional*
 273   - An `Object` specifying extra details about how the connection
 274     should be made.
 275
 276     Possible options:
 277
 278     `shared`
 279       - A `boolean` indicating if the remote server should be shared or
 280         if any other connected clients should be disconnected. Enabled
 281         by default.
 282
 283     `credentials`
 284       - An `Object` specifying the credentials to provide to the server
 285         when authenticating. The following credentials are possible:
 286
 287         | name         | type        | description
 288         | ------------ | ----------- | -----------
 289         | `"username"` | `DOMString` | The user that authenticates
 290         | `"password"` | `DOMString` | Password for the user
 291         | `"target"`   | `DOMString` | Target machine or session
 292
 293     `repeaterID`
 294       - A `DOMString` specifying the ID to provide to any VNC repeater
 295         encountered.
 296
 297 #### RFB.disconnect()
 298
 299 The `RFB.disconnect()` method is used to disconnect from the currently
 300 connected server.
 301
 302 ##### Syntax
 303
 304     RFB.disconnect( );
 305
 306 #### RFB.sendCredentials()
 307
 308 The `RFB.sendCredentials()` method is used to provide the missing
 309 credentials after `RFB.oncredentialsrequired` has been fired.
 310
 311 ##### Syntax
 312
 313     RFB.sendCredentials( credentials );
 314
 315 ###### Parameters
 316
 317 **`credentials`**
 318   - An `Object` specifying the credentials to provide to the server
 319     when authenticating. See [`RFB.connect()`](#rfbconnect) for
 320     details.
 321
 322 #### RFB.sendKey()
 323
 324 The `RFB.sendKey()` method is used to send a key event to the server.
 325
 326 ##### Syntax
 327
 328     RFB.sendKey( keysym, code [, down] );
 329
 330 ###### Parameters
 331
 332 **`keysym`**
 333   - A `long` specifying the RFB keysym to send. Can be `0` if a valid
 334     **`code`** is specified.
 335
 336 **`code`**
 337   - A `DOMString` specifying the physical key to send. Valid values are
 338     those that can be specified to
 339     [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
 340     If the physical key cannot be determined then `null` shall be
 341     specified.
 342
 343 **`down`** *Optional*
 344   - A `boolean` specifying if a press or a release event should be
 345     sent. If omitted then both a press and release event are sent.
 346
 347 #### RFB.sendCtrlAltDel()
 348
 349 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
 350 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
 351 around [`RFB.sendKey()`](#rfbsendkey).
 352
 353 ##### Syntax
 354
 355     RFB.sendCtrlAltDel( );
 356
 357 #### RFB.machineShutdown()
 358
 359 The `RFB.machineShutdown()` method is used to request to shut down the
 360 remote machine. The capability `power` must be set for this method to
 361 have any effect.
 362
 363 ##### Syntax
 364
 365     RFB.machineShutdown( );
 366
 367 #### RFB.machineReboot()
 368
 369 The `RFB.machineReboot()` method is used to request a clean reboot of
 370 the remote machine. The capability `power` must be set for this method
 371 to have any effect.
 372
 373 ##### Syntax
 374
 375     RFB.machineReboot( );
 376
 377 #### RFB.machineReset()
 378
 379 The `RFB.machineReset()` method is used to request a forced reset of
 380 the remote machine. The capability `power` must be set for this method
 381 to have any effect.
 382
 383 ##### Syntax
 384
 385     RFB.machineReset( );
 386
 387 #### RFB.clipboardPasteFrom()
 388
 389 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
 390 to the remote server.
 391
 392 ##### Syntax
 393
 394     RFB.clipboardPasteFrom( text );
 395
 396 ###### Parameters
 397
 398 **`text`**
 399   - A `DOMString` specifying the clipboard data to send. Currently only
 400   characters from ISO 8859-1 are supported.
 401
 402 #### RFB.autoscale()
 403
 404 The `RFB.autoscale()` method is used to automatically adjust
 405 `RFB.viewportScale` to fit given dimensions.
 406
 407 ##### Syntax
 408
 409     RFB.autoscale( width, height );
 410
 411 ###### Parameters
 412
 413 **`width`**
 414   - A `long` specifying the maximum width of the canvas in CSS pixels.
 415
 416 **`height`**
 417   - A `long` specifying the maximum height of the canvas in CSS pixels.
 418
 419 #### RFB.requestDesktopSize()
 420
 421 The `RFB.requestDesktopSize()` method is used to request a change of
 422 the framebuffer. The capability `resize` must be set for this method to
 423 have any effect.
 424
 425 Note that this is merely a request and the server may deny it.
 426 [`RFB.onfbresize`](#rfbonfbresize) will be called when the framebuffer
 427 actually changes dimensions.
 428
 429 ##### Syntax
 430
 431     RFB.requestDesktopSize( width, height );
 432
 433 ###### Parameters
 434
 435 **`width`**
 436   - A `long` specifying the new requested width in CSS pixels.
 437
 438 **`height`**
 439   - A `long` specifying the new requested height in CSS pixels.
 440
 441 #### RFB.viewportChangeSize()
 442
 443 The `RFB.viewportChangeSize()` method is used to change the size of the
 444 canvas rather than the underlying framebuffer.
 445
 446 This method has no effect if `RFB.clipViewport` is set to `false`.
 447
 448 ##### Syntax
 449
 450     RFB.viewportChangeSize( width, height );
 451
 452 ###### Parameters
 453
 454 **`width`**
 455   - A `long` specifying the new width in CSS pixels.
 456
 457 **`height`**
 458   - A `long` specifying the new height in CSS pixels.