diff --git a/docs/API.md b/docs/API.md index 77e90567..34a77f97 100644 --- a/docs/API.md +++ b/docs/API.md @@ -16,61 +16,12 @@ protocol stream. ### Properties -`viewOnly` - - Is a `boolean` indicating if any events (e.g. key presses or mouse - movement) should be prevented from being sent to the server. - Disabled by default. - -`focusOnClick` - - Is a `boolean` indicating if keyboard focus should automatically be - moved to the remote session when a `mousedown` or `touchstart` - event is received. Enabled by default. - -`clipViewport` - - Is a `boolean` indicating if the remote session should be clipped - to its container. When disabled scrollbars will be shown to handle - the resulting overflow. Disabled by default. - -`dragViewport` - - Is a `boolean` indicating if mouse events should control the - relative position of a clipped remote session. Only relevant if - `clipViewport` is enabled. Disabled by default. - -`scaleViewport` - - Is a `boolean` indicating if the remote session should be scaled - locally so it fits its container. When disabled it will be centered - if the remote session is smaller than its container, or handled - according to `clipViewport` if it is larger. Disabled by default. - -`resizeSession` - - Is a `boolean` indicating if a request to resize the remote session - should be sent whenever the container changes dimensions. Disabled - by default. - -`showDotCursor` - - Is a `boolean` indicating whether a dot cursor should be shown - instead of a zero-sized or fully-transparent cursor if the server - sets such invisible cursor. Disabled by default. - `background` - Is a valid CSS [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background) style value indicating which background style should be applied to the element containing the remote session screen. The default value is `rgb(40, 40, 40)` (solid gray color). -`qualityLevel` - - Is an `int` in range `[0-9]` controlling the desired JPEG quality. - Value `0` implies low quality and `9` implies high quality. - Default value is `6`. - -`compressionLevel` - - Is an `int` in range `[0-9]` controlling the desired compression - level. Value `0` means no compression. Level 1 uses a minimum of CPU - resources and achieves weak compression ratios, while level 9 offers - best compression but is slow in terms of CPU consumption on the server - side. Use high levels with very slow network connections. - Default value is `2`. - `capabilities` *Read only* - Is an `Object` indicating which optional extensions are available on the server. Some methods may only be called if the corresponding @@ -80,71 +31,113 @@ protocol stream. | -------- | --------- | ----------- | `power` | `boolean` | Machine power control is available +`clipViewport` + - Is a `boolean` indicating if the remote session should be clipped + to its container. When disabled scrollbars will be shown to handle + the resulting overflow. Disabled by default. + +`compressionLevel` + - Is an `int` in range `[0-9]` controlling the desired compression + level. Value `0` means no compression. Level 1 uses a minimum of CPU + resources and achieves weak compression ratios, while level 9 offers + best compression but is slow in terms of CPU consumption on the server + side. Use high levels with very slow network connections. + Default value is `2`. + +`dragViewport` + - Is a `boolean` indicating if mouse events should control the + relative position of a clipped remote session. Only relevant if + `clipViewport` is enabled. Disabled by default. + +`focusOnClick` + - Is a `boolean` indicating if keyboard focus should automatically be + moved to the remote session when a `mousedown` or `touchstart` + event is received. Enabled by default. + +`qualityLevel` + - Is an `int` in range `[0-9]` controlling the desired JPEG quality. + Value `0` implies low quality and `9` implies high quality. + Default value is `6`. + +`resizeSession` + - Is a `boolean` indicating if a request to resize the remote session + should be sent whenever the container changes dimensions. Disabled + by default. + +`scaleViewport` + - Is a `boolean` indicating if the remote session should be scaled + locally so it fits its container. When disabled it will be centered + if the remote session is smaller than its container, or handled + according to `clipViewport` if it is larger. Disabled by default. + +`showDotCursor` + - Is a `boolean` indicating whether a dot cursor should be shown + instead of a zero-sized or fully-transparent cursor if the server + sets such invisible cursor. Disabled by default. + +`viewOnly` + - Is a `boolean` indicating if any events (e.g. key presses or mouse + movement) should be prevented from being sent to the server. + Disabled by default. + ### Events -[`connect`](#connect) - - The `connect` event is fired when the `RFB` object has completed - the connection and handshaking with the server. - -[`disconnect`](#disconnect) - - The `disconnect` event is fired when the `RFB` object disconnects. - -[`serververification`](#serververification) - - The `serververification` event is fired when the server identity - must be confirmed by the user. - -[`credentialsrequired`](#credentialsrequired) - - The `credentialsrequired` event is fired when more credentials must - be given to continue. - -[`securityfailure`](#securityfailure) - - The `securityfailure` event is fired when the security negotiation - with the server fails. - -[`clipboard`](#clipboard) - - The `clipboard` event is fired when clipboard data is received from - the server. - [`bell`](#bell) - The `bell` event is fired when a audible bell request is received from the server. -[`desktopname`](#desktopname) - - The `desktopname` event is fired when the remote desktop name - changes. - [`capabilities`](#capabilities) - The `capabilities` event is fired when `RFB.capabilities` is updated. -### Methods +[`clipboard`](#clipboard) + - The `clipboard` event is fired when clipboard data is received from + the server. -[`RFB.disconnect()`](#rfbdisconnect) - - Disconnect from the server. +[`connect`](#connect) + - The `connect` event is fired when the `RFB` object has completed + the connection and handshaking with the server. + +[`credentialsrequired`](#credentialsrequired) + - The `credentialsrequired` event is fired when more credentials must + be given to continue. + +[`desktopname`](#desktopname) + - The `desktopname` event is fired when the remote desktop name + changes. + +[`disconnect`](#disconnect) + - The `disconnect` event is fired when the `RFB` object disconnects. + +[`securityfailure`](#securityfailure) + - The `securityfailure` event is fired when the security negotiation + with the server fails. + +[`serververification`](#serververification) + - The `serververification` event is fired when the server identity + must be confirmed by the user. + +### Methods [`RFB.approveServer()`](#rfbapproveserver) - Proceed connecting to the server. Should be called after the [`serververification`](#serververification) event has fired and the user has verified the identity of the server. -[`RFB.sendCredentials()`](#rfbsendcredentials) - - Send credentials to server. Should be called after the - [`credentialsrequired`](#credentialsrequired) event has fired. +[`RFB.blur()`](#rfbblur) + - Remove keyboard focus from the remote session. -[`RFB.sendKey()`](#rfbsendkey) - - Send a key event. +[`RFB.clipboardPasteFrom()`](#rfbclipboardpastefrom) + - Send clipboard contents to server. -[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) - - Send Ctrl-Alt-Del key sequence. +[`RFB.disconnect()`](#rfbdisconnect) + - Disconnect from the server. [`RFB.focus()`](#rfbfocus) - Move keyboard focus to the remote session. -[`RFB.blur()`](#rfbblur) - - Remove keyboard focus from the remote session. - -[`RFB.machineShutdown()`](#rfbmachineshutdown) - - Request a shutdown of the remote machine. +[`RFB.getImageData()`](#rfbgetimagedata) + - Return the current content of the screen as an ImageData array. [`RFB.machineReboot()`](#rfbmachinereboot) - Request a reboot of the remote machine. @@ -152,18 +145,25 @@ protocol stream. [`RFB.machineReset()`](#rfbmachinereset) - Request a reset of the remote machine. -[`RFB.clipboardPasteFrom()`](#rfbclipboardpastefrom) - - Send clipboard contents to server. +[`RFB.machineShutdown()`](#rfbmachineshutdown) + - Request a shutdown of the remote machine. -[`RFB.getImageData()`](#rfbgetimagedata) - - Return the current content of the screen as an ImageData array. +[`RFB.sendCredentials()`](#rfbsendcredentials) + - Send credentials to server. Should be called after the + [`credentialsrequired`](#credentialsrequired) event has fired. -[`RFB.toDataURL()`](#rfbtodataurl) - - Return the current content of the screen as data-url encoded image file. +[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) + - Send Ctrl-Alt-Del key sequence. + +[`RFB.sendKey()`](#rfbsendkey) + - Send a key event. [`RFB.toBlob()`](#rfbtoblob) - Return the current content of the screen as Blob encoded image file. +[`RFB.toDataURL()`](#rfbtodataurl) + - Return the current content of the screen as data-url encoded image file. + ### Details #### RFB() @@ -216,12 +216,42 @@ connection to a specified VNC server. - An `Array` of `DOMString`s specifying the sub-protocols to use in the WebSocket connection. Empty by default. +#### bell + +The `bell` event is fired when the server has requested an audible +bell. + +#### capabilities + +The `capabilities` event is fired whenever an entry is added or removed +from `RFB.capabilities`. The `detail` property is an `Object` with the +property `capabilities` containing the new value of `RFB.capabilities`. + +#### clipboard + +The `clipboard` event is fired when the server has sent clipboard data. +The `detail` property is an `Object` containing the property `text` +which is a `DOMString` with the clipboard data. + +#### credentialsrequired + +The `credentialsrequired` event is fired when the server requests more +credentials than were specified to [`RFB()`](#rfb-1). The `detail` +property is an `Object` containing the property `types` which is an +`Array` of `DOMString` listing the credentials that are required. + #### connect The `connect` event is fired after all the handshaking with the server is completed and the connection is fully established. After this event the `RFB` object is ready to recieve graphics updates and to send input. +#### desktopname + +The `desktopname` event is fired when the name of the remote desktop +changes. The `detail` property is an `Object` with the property `name` +which is a `DOMString` specifying the new name. + #### disconnect The `disconnect` event is fired when the connection has been @@ -230,27 +260,6 @@ property `clean`. `clean` is a `boolean` indicating if the termination was clean or not. In the event of an unexpected termination or an error `clean` will be set to false. -#### serververification - -The `serververification` event is fired when the server provides -information that allows the user to verify that it is the correct server -and protect against a man-in-the-middle attack. The `detail` property is -an `Object` containing the property `type` which is a `DOMString` -specifying which type of information the server has provided. Other -properties are also available, depending on the value of `type`: - -`"RSA"` - - The server identity is verified using just a RSA key. The property - `publickey` is a `Uint8Array` containing the public key in a unsigned - big endian representation. - -#### credentialsrequired - -The `credentialsrequired` event is fired when the server requests more -credentials than were specified to [`RFB()`](#rfb-1). The `detail` -property is an `Object` containing the property `types` which is an -`Array` of `DOMString` listing the credentials that are required. - #### securityfailure The `securityfailure` event is fired when the handshaking process with @@ -271,37 +280,19 @@ thus the language of the string is not known. However most servers will probably send English strings. The server can choose to not send a reason and in these cases the `reason` property will be omitted. -#### clipboard +#### serververification -The `clipboard` event is fired when the server has sent clipboard data. -The `detail` property is an `Object` containing the property `text` -which is a `DOMString` with the clipboard data. +The `serververification` event is fired when the server provides +information that allows the user to verify that it is the correct server +and protect against a man-in-the-middle attack. The `detail` property is +an `Object` containing the property `type` which is a `DOMString` +specifying which type of information the server has provided. Other +properties are also available, depending on the value of `type`: -#### bell - -The `bell` event is fired when the server has requested an audible -bell. - -#### desktopname - -The `desktopname` event is fired when the name of the remote desktop -changes. The `detail` property is an `Object` with the property `name` -which is a `DOMString` specifying the new name. - -#### capabilities - -The `capabilities` event is fired whenever an entry is added or removed -from `RFB.capabilities`. The `detail` property is an `Object` with the -property `capabilities` containing the new value of `RFB.capabilities`. - -#### RFB.disconnect() - -The `RFB.disconnect()` method is used to disconnect from the currently -connected server. - -##### Syntax - - RFB.disconnect( ); +`"RSA"` + - The server identity is verified using just a RSA key. The property + `publickey` is a `Uint8Array` containing the public key in a unsigned + big endian representation. #### RFB.approveServer() @@ -313,6 +304,94 @@ and that the connection can continue. RFB.approveServer( ); +#### RFB.blur() + +The `RFB.blur()` method remove keyboard focus on the remote session. +Keyboard events will no longer be sent to the remote server after this +point. + +##### Syntax + + RFB.blur( ); + +#### RFB.clipboardPasteFrom() + +The `RFB.clipboardPasteFrom()` method is used to send clipboard data +to the remote server. + +##### Syntax + + RFB.clipboardPasteFrom( text ); + +###### Parameters + +**`text`** + - A `DOMString` specifying the clipboard data to send. + +#### RFB.disconnect() + +The `RFB.disconnect()` method is used to disconnect from the currently +connected server. + +##### Syntax + + RFB.disconnect( ); + +#### RFB.focus() + +The `RFB.focus()` method sets the keyboard focus on the remote session. +Keyboard events will be sent to the remote server after this point. + +##### Syntax + + RFB.focus( [options] ); + +###### Parameters + +**`options`** *Optional* + - A `object` providing options to control how the focus will be + performed. Please see [`HTMLElement.focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) + for available options. + +#### RFB.getImageData() + +The `RFB.getImageData()` method is used to return the current content of the +screen encoded as [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData). + +##### Syntax + + RFB.getImageData(); + +#### RFB.machineReboot() + +The `RFB.machineReboot()` method is used to request a clean reboot of +the remote machine. The capability `power` must be set for this method +to have any effect. + +##### Syntax + + RFB.machineReboot( ); + +#### RFB.machineReset() + +The `RFB.machineReset()` method is used to request a forced reset of +the remote machine. The capability `power` must be set for this method +to have any effect. + +##### Syntax + + RFB.machineReset( ); + +#### RFB.machineShutdown() + +The `RFB.machineShutdown()` method is used to request to shut down the +remote machine. The capability `power` must be set for this method to +have any effect. + +##### Syntax + + RFB.machineShutdown( ); + #### RFB.sendCredentials() The `RFB.sendCredentials()` method is used to provide the missing @@ -328,6 +407,16 @@ credentials after a `credentialsrequired` event has been fired. - An `Object` specifying the credentials to provide to the server when authenticating. See [`RFB()`](#rfb-1) for details. +#### RFB.sendCtrlAltDel() + +The `RFB.sendCtrlAltDel()` method is used to send the key sequence +*left Control*, *left Alt*, *Delete*. This is a convenience wrapper +around [`RFB.sendKey()`](#rfbsendkey). + +##### Syntax + + RFB.sendCtrlAltDel( ); + #### RFB.sendKey() The `RFB.sendKey()` method is used to send a key event to the server. @@ -353,115 +442,6 @@ The `RFB.sendKey()` method is used to send a key event to the server. - A `boolean` specifying if a press or a release event should be sent. If omitted then both a press and release event are sent. -#### RFB.sendCtrlAltDel() - -The `RFB.sendCtrlAltDel()` method is used to send the key sequence -*left Control*, *left Alt*, *Delete*. This is a convenience wrapper -around [`RFB.sendKey()`](#rfbsendkey). - -##### Syntax - - RFB.sendCtrlAltDel( ); - -#### RFB.focus() - -The `RFB.focus()` method sets the keyboard focus on the remote session. -Keyboard events will be sent to the remote server after this point. - -##### Syntax - - RFB.focus( [options] ); - -###### Parameters - -**`options`** *Optional* - - A `object` providing options to control how the focus will be - performed. Please see [`HTMLElement.focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) - for available options. - -#### RFB.blur() - -The `RFB.blur()` method remove keyboard focus on the remote session. -Keyboard events will no longer be sent to the remote server after this -point. - -##### Syntax - - RFB.blur( ); - -#### RFB.machineShutdown() - -The `RFB.machineShutdown()` method is used to request to shut down the -remote machine. The capability `power` must be set for this method to -have any effect. - -##### Syntax - - RFB.machineShutdown( ); - -#### RFB.machineReboot() - -The `RFB.machineReboot()` method is used to request a clean reboot of -the remote machine. The capability `power` must be set for this method -to have any effect. - -##### Syntax - - RFB.machineReboot( ); - -#### RFB.machineReset() - -The `RFB.machineReset()` method is used to request a forced reset of -the remote machine. The capability `power` must be set for this method -to have any effect. - -##### Syntax - - RFB.machineReset( ); - -#### RFB.clipboardPasteFrom() - -The `RFB.clipboardPasteFrom()` method is used to send clipboard data -to the remote server. - -##### Syntax - - RFB.clipboardPasteFrom( text ); - -###### Parameters - -**`text`** - - A `DOMString` specifying the clipboard data to send. - -#### RFB.getImageData() - -The `RFB.getImageData()` method is used to return the current content of the -screen encoded as [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData). - -##### Syntax - - RFB.getImageData(); - -#### RFB.toDataURL() - -The `RFB.toDataURL()` method is used to return the current content of the -screen encoded as a data URL that could for example be put in the `src` attribute -of an `img` tag. - -##### Syntax - - RFB.toDataURL(); - RFB.toDataURL(type); - RFB.toDataURL(type, encoderOptions); - -###### Parameters - -**`type`** *Optional* - - A string indicating the requested MIME type of the image - -**`encoderOptions`** *Optional* - - A number between 0 and 1 indicating the image quality. - #### RFB.toBlob() The `RFB.toBlob()` method is used to return the current content of the @@ -484,3 +464,23 @@ screen encoded as [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob **`encoderOptions`** *Optional* - A number between 0 and 1 indicating the image quality. + +#### RFB.toDataURL() + +The `RFB.toDataURL()` method is used to return the current content of the +screen encoded as a data URL that could for example be put in the `src` attribute +of an `img` tag. + +##### Syntax + + RFB.toDataURL(); + RFB.toDataURL(type); + RFB.toDataURL(type, encoderOptions); + +###### Parameters + +**`type`** *Optional* + - A string indicating the requested MIME type of the image + +**`encoderOptions`** *Optional* + - A number between 0 and 1 indicating the image quality.