spb/admin-ka

1# noVNC API23The interface of the noVNC client consists of a single RFB object that4is instantiated once per connection.56## RFB78The `RFB` object represents a single connection to a VNC server. It9communicates using a WebSocket that must provide a standard RFB10protocol stream.1112### Constructor1314[`RFB()`](#rfb-1)15  - Creates and returns a new `RFB` object.1617### Properties1819`background`20  - Is a valid CSS [background][mdn-bg] style value indicating which21    background style should be applied to the element containing the22    remote session screen. The default value is `rgb(40, 40, 40)` (solid23    gray color).2425[mdn-bg]: https://developer.mozilla.org/en-US/docs/Web/CSS/background2627`capabilities` *Read only*28  - Is an `Object` indicating which optional extensions are available29    on the server. Some methods may only be called if the corresponding30    capability is set. The following capabilities are defined:3132    | name     | type      | description33    | -------- | --------- | -----------34    | `power`  | `boolean` | Machine power control is available3536`clippingViewport` *Read only*37  - Is a `boolean` indicating if the remote session is currently being38    clipped to its container. Only relevant if `clipViewport` is39    enabled.4041`clipViewport`42  - Is a `boolean` indicating if the remote session should be clipped43    to its container. When disabled scrollbars will be shown to handle44    the resulting overflow. Disabled by default.4546`compressionLevel`47  - Is an `int` in range `[0-9]` controlling the desired compression48    level. Value `0` means no compression. Level 1 uses a minimum of CPU49    resources and achieves weak compression ratios, while level 9 offers50    best compression but is slow in terms of CPU consumption on the server51    side. Use high levels with very slow network connections.52    Default value is `2`.5354`dragViewport`55  - Is a `boolean` indicating if mouse events should control the56    relative position of a clipped remote session. Only relevant if57    `clipViewport` is enabled. Disabled by default.5859`focusOnClick`60  - Is a `boolean` indicating if keyboard focus should automatically be61    moved to the remote session when a `mousedown` or `touchstart`62    event is received. Enabled by default.6364`qualityLevel`65  - Is an `int` in range `[0-9]` controlling the desired JPEG quality.66    Value `0` implies low quality and `9` implies high quality.67    Default value is `6`.6869`resizeSession`70  - Is a `boolean` indicating if a request to resize the remote session71    should be sent whenever the container changes dimensions. Disabled72    by default.7374`scaleViewport`75  - Is a `boolean` indicating if the remote session should be scaled76    locally so it fits its container. When disabled it will be centered77    if the remote session is smaller than its container, or handled78    according to `clipViewport` if it is larger. Disabled by default.7980`showDotCursor`81  - Is a `boolean` indicating whether a dot cursor should be shown82    instead of a zero-sized or fully-transparent cursor if the server83    sets such invisible cursor. Disabled by default.8485`viewOnly`86  - Is a `boolean` indicating if any events (e.g. key presses or mouse87    movement) should be prevented from being sent to the server.88    Disabled by default.8990### Events9192[`bell`](#bell)93  - The `bell` event is fired when a audible bell request is received94    from the server.9596[`capabilities`](#capabilities)97  - The `capabilities` event is fired when `RFB.capabilities` is98    updated.99100[`clipboard`](#clipboard)101  - The `clipboard` event is fired when clipboard data is received from102    the server.103104[`clippingviewport`](#clippingviewport)105  - The `clippingviewport` event is fired when `RFB.clippingViewport` is106    updated.107108[`connect`](#connect)109  - The `connect` event is fired when the `RFB` object has completed110    the connection and handshaking with the server.111112[`credentialsrequired`](#credentialsrequired)113  - The `credentialsrequired` event is fired when more credentials must114    be given to continue.115116[`desktopname`](#desktopname)117  - The `desktopname` event is fired when the remote desktop name118    changes.119120[`disconnect`](#disconnect)121  - The `disconnect` event is fired when the `RFB` object disconnects.122123[`securityfailure`](#securityfailure)124  - The `securityfailure` event is fired when the security negotiation125    with the server fails.126127[`serververification`](#serververification)128  - The `serververification` event is fired when the server identity129    must be confirmed by the user.130131### Methods132133[`RFB.approveServer()`](#rfbapproveserver)134  - Proceed connecting to the server. Should be called after the135    [`serververification`](#serververification) event has fired and the136    user has verified the identity of the server.137138[`RFB.blur()`](#rfbblur)139  - Remove keyboard focus from the remote session.140141[`RFB.clipboardPasteFrom()`](#rfbclipboardpastefrom)142  - Send clipboard contents to server.143144[`RFB.disconnect()`](#rfbdisconnect)145  - Disconnect from the server.146147[`RFB.focus()`](#rfbfocus)148  - Move keyboard focus to the remote session.149150[`RFB.getImageData()`](#rfbgetimagedata)151  - Return the current content of the screen as an ImageData array.152153[`RFB.machineReboot()`](#rfbmachinereboot)154  - Request a reboot of the remote machine.155156[`RFB.machineReset()`](#rfbmachinereset)157  - Request a reset of the remote machine.158159[`RFB.machineShutdown()`](#rfbmachineshutdown)160  - Request a shutdown of the remote machine.161162[`RFB.sendCredentials()`](#rfbsendcredentials)163  - Send credentials to server. Should be called after the164    [`credentialsrequired`](#credentialsrequired) event has fired.165166[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)167  - Send Ctrl-Alt-Del key sequence.168169[`RFB.sendKey()`](#rfbsendkey)170  - Send a key event.171172[`RFB.toBlob()`](#rfbtoblob)173  - Return the current content of the screen as Blob encoded image file.174175[`RFB.toDataURL()`](#rfbtodataurl)176  - Return the current content of the screen as data-url encoded image file.177178### Details179180#### RFB()181182The `RFB()` constructor returns a new `RFB` object and initiates a new183connection to a specified VNC server.184185##### Syntax186187```js188new RFB(target, urlOrChannel);189new RFB(target, urlOrChannel, options);190```191192###### Parameters193194**`target`**195  - A block [`HTMLElement`][mdn-elem] that specifies where the `RFB`196    object should attach itself. The existing contents of the197    `HTMLElement` will be untouched, but new elements will be added198    during the lifetime of the `RFB` object.199200[mdn-elem]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement201202**`urlOrChannel`**203  - A `DOMString` specifying the VNC server to connect to. This must be204    a valid WebSocket URL. This can also be a `WebSocket` or `RTCDataChannel`.205206**`options`** *Optional*207  - An `Object` specifying extra details about how the connection208    should be made.209210    Possible options:211212    `shared`213      - A `boolean` indicating if the remote server should be shared or214        if any other connected clients should be disconnected. Enabled215        by default.216217    `credentials`218      - An `Object` specifying the credentials to provide to the server219        when authenticating. The following credentials are possible:220221        | name         | type        | description222        | ------------ | ----------- | -----------223        | `"username"` | `DOMString` | The user that authenticates224        | `"password"` | `DOMString` | Password for the user225        | `"target"`   | `DOMString` | Target machine or session226227    `repeaterID`228      - A `DOMString` specifying the ID to provide to any VNC repeater229        encountered.230231    `wsProtocols`232      - An `Array` of `DOMString`s specifying the sub-protocols to use233        in the WebSocket connection. Empty by default.234235#### bell236237The `bell` event is fired when the server has requested an audible238bell.239240#### capabilities241242The `capabilities` event is fired whenever an entry is added or removed243from `RFB.capabilities`. The `detail` property is an `Object` with the244property `capabilities` containing the new value of `RFB.capabilities`.245246#### clippingviewport247248The `clippingviewport` event is fired whenever `RFB.clippingViewport`249changes between `true` and `false`. The `detail` property is a `boolean`250with the new value of `RFB.clippingViewport`.251252#### clipboard253254The `clipboard` event is fired when the server has sent clipboard data.255The `detail` property is an `Object` containing the property `text`256which is a `DOMString` with the clipboard data.257258#### credentialsrequired259260The `credentialsrequired` event is fired when the server requests more261credentials than were specified to [`RFB()`](#rfb-1). The `detail`262property is an `Object` containing the property `types` which is an263`Array` of `DOMString` listing the credentials that are required.264265#### connect266267The `connect` event is fired after all the handshaking with the server268is completed and the connection is fully established. After this event269the `RFB` object is ready to recieve graphics updates and to send input.270271#### desktopname272273The `desktopname` event is fired when the name of the remote desktop274changes. The `detail` property is an `Object` with the property `name`275which is a `DOMString` specifying the new name.276277#### disconnect278279The `disconnect` event is fired when the connection has been280terminated. The `detail` property is an `Object` that contains the281property `clean`. `clean` is a `boolean` indicating if the termination282was clean or not. In the event of an unexpected termination or an error283`clean` will be set to false.284285#### securityfailure286287The `securityfailure` event is fired when the handshaking process with288the server fails during the security negotiation step. The `detail`289property is an `Object` containing the following properties:290291| Property | Type        | Description292| -------- | ----------- | -----------293| `status` | `long`      | The failure status code294| `reason` | `DOMString` | The **optional** reason for the failure295296The property `status` corresponds to the [SecurityResult][rfb-secresult]297status code in cases of failure. A status of zero will not be sent in298this event since that indicates a successful security handshaking299process. The optional property `reason` is provided by the server and300thus the language of the string is not known. However most servers will301probably send English strings. The server can choose to not send a302reason and in these cases the `reason` property will be omitted.303304[rfb-secresult]: https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult305306#### serververification307308The `serververification` event is fired when the server provides309information that allows the user to verify that it is the correct server310and protect against a man-in-the-middle attack. The `detail` property is311an `Object` containing the property `type` which is a `DOMString`312specifying which type of information the server has provided. Other313properties are also available, depending on the value of `type`:314315`"RSA"`316 - The server identity is verified using just a RSA key. The property317   `publickey` is a `Uint8Array` containing the public key in a unsigned318   big endian representation.319320#### RFB.approveServer()321322The `RFB.approveServer()` method is used to signal that the user has323verified the server identity provided in a `serververification` event324and that the connection can continue.325326##### Syntax327328```js329RFB.approveServer();330```331332#### RFB.blur()333334The `RFB.blur()` method remove keyboard focus on the remote session.335Keyboard events will no longer be sent to the remote server after this336point.337338##### Syntax339340```js341RFB.blur();342```343344#### RFB.clipboardPasteFrom()345346The `RFB.clipboardPasteFrom()` method is used to send clipboard data347to the remote server.348349##### Syntax350351```js352RFB.clipboardPasteFrom(text);353```354355###### Parameters356357**`text`**358  - A `DOMString` specifying the clipboard data to send.359360#### RFB.disconnect()361362The `RFB.disconnect()` method is used to disconnect from the currently363connected server.364365##### Syntax366367```js368RFB.disconnect();369```370371#### RFB.focus()372373The `RFB.focus()` method sets the keyboard focus on the remote session.374Keyboard events will be sent to the remote server after this point.375376##### Syntax377378```js379RFB.focus();380RFB.focus(options);381```382383###### Parameters384385**`options`** *Optional*386  - A `object` providing options to control how the focus will be387    performed. Please see [`HTMLElement.focus()`][mdn-focus] for388    available options.389390[mdn-focus]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus391392#### RFB.getImageData()393394The `RFB.getImageData()` method is used to return the current content of395the screen encoded as [`ImageData`][mdn-imagedata].396397[mdn-imagedata]: https://developer.mozilla.org/en-US/docs/Web/API/ImageData398399##### Syntax400401```js402RFB.getImageData();403```404405#### RFB.machineReboot()406407The `RFB.machineReboot()` method is used to request a clean reboot of408the remote machine. The capability `power` must be set for this method409to have any effect.410411##### Syntax412413```js414RFB.machineReboot();415```416417#### RFB.machineReset()418419The `RFB.machineReset()` method is used to request a forced reset of420the remote machine. The capability `power` must be set for this method421to have any effect.422423##### Syntax424425```js426RFB.machineReset();427```428429#### RFB.machineShutdown()430431The `RFB.machineShutdown()` method is used to request to shut down the432remote machine. The capability `power` must be set for this method to433have any effect.434435##### Syntax436437```js438RFB.machineShutdown();439```440441#### RFB.sendCredentials()442443The `RFB.sendCredentials()` method is used to provide the missing444credentials after a `credentialsrequired` event has been fired.445446##### Syntax447448```js449RFB.sendCredentials(credentials);450```451452###### Parameters453454**`credentials`**455  - An `Object` specifying the credentials to provide to the server456    when authenticating. See [`RFB()`](#rfb-1) for details.457458#### RFB.sendCtrlAltDel()459460The `RFB.sendCtrlAltDel()` method is used to send the key sequence461*left Control*, *left Alt*, *Delete*. This is a convenience wrapper462around [`RFB.sendKey()`](#rfbsendkey).463464##### Syntax465466```js467RFB.sendCtrlAltDel();468```469470#### RFB.sendKey()471472The `RFB.sendKey()` method is used to send a key event to the server.473474##### Syntax475476```js477RFB.sendKey(keysym, code);478RFB.sendKey(keysym, code, down);479```480481###### Parameters482483**`keysym`**484  - A `long` specifying the RFB keysym to send. Can be `0` if a valid485    **`code`** is specified.486487**`code`**488  - A `DOMString` specifying the physical key to send. Valid values are489    those that can be specified to [`KeyboardEvent.code`][mdn-keycode].490    If the physical key cannot be determined then `null` shall be491    specified.492493[mdn-keycode]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code494495**`down`** *Optional*496  - A `boolean` specifying if a press or a release event should be497    sent. If omitted then both a press and release event are sent.498499#### RFB.toBlob()500501The `RFB.toBlob()` method is used to return the current content of the502screen encoded as [`Blob`][mdn-blob].503504[mdn-blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob505506##### Syntax507508```js509RFB.toBlob(callback);510RFB.toBlob(callback, type);511RFB.toBlob(callback, type, quality);512```513514###### Parameters515516**`callback`**517  - A callback function which will receive the resulting518    [`Blob`][mdn-blob] as the single argument519520**`type`** *Optional*521  - A string indicating the requested MIME type of the image522523**`quality`** *Optional*524  - A number between 0 and 1 indicating the image quality.525526#### RFB.toDataURL()527528The `RFB.toDataURL()` method is used to return the current content of the529screen encoded as a data URL that could for example be put in the `src` attribute530of an `img` tag.531532##### Syntax533534```js535RFB.toDataURL();536RFB.toDataURL(type);537RFB.toDataURL(type, encoderOptions);538```539540###### Parameters541542**`type`** *Optional*543  - A string indicating the requested MIME type of the image544545**`encoderOptions`** *Optional*546  - A number between 0 and 1 indicating the image quality.547