summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPierre Ossman <ossman@cendio.se>2022-10-13 10:08:10 +0200
committerPierre Ossman <ossman@cendio.se>2022-12-27 12:20:40 +0100
commitf172633715adc9721e552f58ea2e117ac1ade3ea (patch)
tree66aceae4f1f0d9da99535a1ddd14ced340e28d1e
parente6fce71d6ac3ef4c5aaa22e3078f7f4994ca1db8 (diff)
downloadnovnc-f172633715adc9721e552f58ea2e117ac1ade3ea.tar.gz
Sort API alphabetically
So it is easier to find things as the API grows.
-rw-r--r--docs/API.md398
1 files 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.