From f172633715adc9721e552f58ea2e117ac1ade3ea Mon Sep 17 00:00:00 2001 From: Pierre Ossman Date: Thu, 13 Oct 2022 10:08:10 +0200 Subject: Sort API alphabetically So it is easier to find things as the API grows. --- docs/API.md | 398 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 199 insertions(+), 199 deletions(-) diff --git a/docs/API.md b/docs/API.md index 77e9056..34a77f9 100644 --- a/docs/API.md +++ b/docs/API.md @@ -16,135 +16,128 @@ 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. +`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). -`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. +`capabilities` *Read only* + - Is an `Object` indicating which optional extensions are available + on the server. Some methods may only be called if the corresponding + capability is set. The following capabilities are defined: + + | name | type | description + | -------- | --------- | ----------- + | `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. -`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. +`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. -`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`. +`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. -`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`. +### Events -`capabilities` *Read only* - - Is an `Object` indicating which optional extensions are available - on the server. Some methods may only be called if the corresponding - capability is set. The following capabilities are defined: +[`bell`](#bell) + - The `bell` event is fired when a audible bell request is received + from the server. - | name | type | description - | -------- | --------- | ----------- - | `power` | `boolean` | Machine power control is available +[`capabilities`](#capabilities) + - The `capabilities` event is fired when `RFB.capabilities` is + updated. -### Events +[`clipboard`](#clipboard) + - The `clipboard` event is fired when clipboard data is received from + the server. [`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. +[`disconnect`](#disconnect) + - The `disconnect` event is fired when the `RFB` object disconnects. -### Methods +[`securityfailure`](#securityfailure) + - The `securityfailure` event is fired when the security negotiation + with the server fails. -[`RFB.disconnect()`](#rfbdisconnect) - - Disconnect from the server. +[`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 - -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. - -#### 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. +#### serververification -##### Syntax +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`: - 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,55 +304,38 @@ and that the connection can continue. RFB.approveServer( ); -#### RFB.sendCredentials() +#### RFB.blur() -The `RFB.sendCredentials()` method is used to provide the missing -credentials after a `credentialsrequired` event has been fired. +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.sendCredentials( credentials ); - -###### Parameters - -**`credentials`** - - An `Object` specifying the credentials to provide to the server - when authenticating. See [`RFB()`](#rfb-1) for details. + RFB.blur( ); -#### RFB.sendKey() +#### RFB.clipboardPasteFrom() -The `RFB.sendKey()` method is used to send a key event to the server. +The `RFB.clipboardPasteFrom()` method is used to send clipboard data +to the remote server. ##### Syntax - RFB.sendKey( keysym, code [, down] ); + RFB.clipboardPasteFrom( text ); ###### Parameters -**`keysym`** - - A `long` specifying the RFB keysym to send. Can be `0` if a valid - **`code`** is specified. - -**`code`** - - A `DOMString` specifying the physical key to send. Valid values are - those that can be specified to - [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code). - If the physical key cannot be determined then `null` shall be - specified. - -**`down`** *Optional* - - A `boolean` specifying if a press or a release event should be - sent. If omitted then both a press and release event are sent. +**`text`** + - A `DOMString` specifying the clipboard data to send. -#### RFB.sendCtrlAltDel() +#### RFB.disconnect() -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). +The `RFB.disconnect()` method is used to disconnect from the currently +connected server. ##### Syntax - RFB.sendCtrlAltDel( ); + RFB.disconnect( ); #### RFB.focus() @@ -379,25 +353,14 @@ Keyboard events will be sent to the remote server after this point. 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() +#### RFB.getImageData() -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. +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.machineShutdown( ); + RFB.getImageData(); #### RFB.machineReboot() @@ -419,48 +382,65 @@ to have any effect. RFB.machineReset( ); -#### RFB.clipboardPasteFrom() +#### RFB.machineShutdown() -The `RFB.clipboardPasteFrom()` method is used to send clipboard data -to the remote server. +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.clipboardPasteFrom( text ); + RFB.machineShutdown( ); + +#### RFB.sendCredentials() + +The `RFB.sendCredentials()` method is used to provide the missing +credentials after a `credentialsrequired` event has been fired. + +##### Syntax + + RFB.sendCredentials( credentials ); ###### Parameters -**`text`** - - A `DOMString` specifying the clipboard data to send. +**`credentials`** + - An `Object` specifying the credentials to provide to the server + when authenticating. See [`RFB()`](#rfb-1) for details. -#### RFB.getImageData() +#### RFB.sendCtrlAltDel() -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). +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.getImageData(); + RFB.sendCtrlAltDel( ); -#### RFB.toDataURL() +#### RFB.sendKey() -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. +The `RFB.sendKey()` method is used to send a key event to the server. ##### Syntax - RFB.toDataURL(); - RFB.toDataURL(type); - RFB.toDataURL(type, encoderOptions); + RFB.sendKey( keysym, code [, down] ); ###### Parameters -**`type`** *Optional* - - A string indicating the requested MIME type of the image +**`keysym`** + - A `long` specifying the RFB keysym to send. Can be `0` if a valid + **`code`** is specified. -**`encoderOptions`** *Optional* - - A number between 0 and 1 indicating the image quality. +**`code`** + - A `DOMString` specifying the physical key to send. Valid values are + those that can be specified to + [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code). + If the physical key cannot be determined then `null` shall be + specified. + +**`down`** *Optional* + - 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.toBlob() @@ -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. -- cgit v1.2.1