@novnc/novnc 1.3.0 → 1.4.0-beta

package/docs/API.md

@@ -16,126 +16,139 @@ 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][mdn-bg] 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.
+[mdn-bg]: https://developer.mozilla.org/en-US/docs/Web/CSS/background
+
+`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
+
+`clippingViewport` *Read only*
+  - Is a `boolean` indicating if the remote session is currently being
+    clipped to its container. Only relevant if `clipViewport` is
+    enabled.
 
 `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).
+`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.
 
-`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`.
+### Events
 
-`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`.
+[`bell`](#bell)
+  - The `bell` event is fired when a audible bell request is received
+    from the server.
 
-`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:
+[`capabilities`](#capabilities)
+  - The `capabilities` event is fired when `RFB.capabilities` is
+    updated.
 
-    | name     | type      | description
-    | -------- | --------- | -----------
-    | `power`  | `boolean` | Machine power control is available
+[`clipboard`](#clipboard)
+  - The `clipboard` event is fired when clipboard data is received from
+    the server.
 
-### Events
+[`clippingviewport`](#clippingviewport)
+  - The `clippingviewport` event is fired when `RFB.clippingViewport` is
+    updated.
 
 [`connect`](#connect)
   - The `connect` event is fired when the `RFB` object has completed
     the connection and handshaking with the server.
 
-[`disconnect`](#disconnected)
-  - The `disconnect` event is fired when the `RFB` object disconnects.
-
 [`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.
 
-[`clipboard`](#clipboard)
-  - The `clipboard` event is fired when clipboard data is received from
-    the server.
+[`serververification`](#serververification)
+  - The `serververification` event is fired when the server identity
+    must be confirmed by the user.
 
-[`bell`](#bell)
-  - The `bell` event is fired when a audible bell request is received
-    from the server.
+### Methods
 
-[`desktopname`](#desktopname)
-  - The `desktopname` event is fired when the remote desktop name
-    changes.
+[`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.
 
-[`capabilities`](#capabilities)
-  - The `capabilities` event is fired when `RFB.capabilities` is
-    updated.
+[`RFB.blur()`](#rfbblur)
+  - Remove keyboard focus from the remote session.
 
-### Methods
+[`RFB.clipboardPasteFrom()`](#rfbclipboardpastefrom)
+  - Send clipboard contents to server.
 
 [`RFB.disconnect()`](#rfbdisconnect)
   - Disconnect from the server.
 
-[`RFB.sendCredentials()`](#rfbsendcredentials)
-  - Send credentials to server. Should be called after the
-    [`credentialsrequired`](#credentialsrequired) event has fired.
-
-[`RFB.sendKey()`](#rfbsendKey)
-  - Send a key event.
-
-[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
-  - Send Ctrl-Alt-Del key sequence.
-
 [`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.
@@ -143,8 +156,24 @@ 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.sendCredentials()`](#rfbsendcredentials)
+  - Send credentials to server. Should be called after the
+    [`credentialsrequired`](#credentialsrequired) event has fired.
+
+[`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
 
@@ -155,17 +184,22 @@ connection to a specified VNC server.
 
 ##### Syntax
 
-    let rfb = new RFB( target, url [, options] );
+```js
+new RFB(target, urlOrChannel);
+new RFB(target, urlOrChannel, options);
+```
 
 ###### Parameters
 
 **`target`**
-  - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
-    that specifies where the `RFB` object should attach itself. The
-    existing contents of the `HTMLElement` will be untouched, but new
-    elements will be added during the lifetime of the `RFB` object.
+  - A block [`HTMLElement`][mdn-elem] that specifies where the `RFB`
+    object should attach itself. The existing contents of the
+    `HTMLElement` will be untouched, but new elements will be added
+    during the lifetime of the `RFB` object.
+
+[mdn-elem]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
 
-**`urlOrDataChannel`**
+**`urlOrChannel`**
   - A `DOMString` specifying the VNC server to connect to. This must be
     a valid WebSocket URL. This can also be a `WebSocket` or `RTCDataChannel`.
 
@@ -198,12 +232,48 @@ 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`.
+
+#### clippingviewport
+
+The `clippingviewport` event is fired whenever `RFB.clippingViewport`
+changes between `true` and `false`. The `detail` property is a `boolean`
+with the new value of `RFB.clippingViewport`.
+
+#### 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
@@ -212,13 +282,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.
 
-#### 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
@@ -230,8 +293,7 @@ property is an `Object` containing the following properties:
 | `status` | `long`      | The failure status code
 | `reason` | `DOMString` | The **optional** reason for the failure
 
-The property `status` corresponds to the
-[SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult)
+The property `status` corresponds to the [SecurityResult][rfb-secresult]
 status code in cases of failure. A status of zero will not be sent in
 this event since that indicates a successful security handshaking
 process. The optional property `reason` is provided by the server and
@@ -239,106 +301,130 @@ 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
+[rfb-secresult]: https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult
 
-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.
+#### serververification
 
-#### bell
+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`:
 
-The `bell` event is fired when the server has requested an audible
-bell.
+`"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.
 
-#### desktopname
+#### RFB.approveServer()
 
-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.
+The `RFB.approveServer()` method is used to signal that the user has
+verified the server identity provided in a `serververification` event
+and that the connection can continue.
 
-#### capabilities
+##### Syntax
 
-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`.
+```js
+RFB.approveServer();
+```
 
-#### RFB.disconnect()
+#### RFB.blur()
 
-The `RFB.disconnect()` method is used to disconnect from the currently
-connected server.
+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.disconnect( );
+```js
+RFB.blur();
+```
 
-#### RFB.sendCredentials()
+#### RFB.clipboardPasteFrom()
 
-The `RFB.sendCredentials()` method is used to provide the missing
-credentials after a `credentialsrequired` event has been fired.
+The `RFB.clipboardPasteFrom()` method is used to send clipboard data
+to the remote server.
 
 ##### Syntax
 
-    RFB.sendCredentials( credentials );
+```js
+RFB.clipboardPasteFrom(text);
+```
 
 ###### Parameters
 
-**`credentials`**
-  - An `Object` specifying the credentials to provide to the server
-    when authenticating. See [`RFB()`](#rfb-1) for details.
+**`text`**
+  - A `DOMString` specifying the clipboard data to send.
 
-#### RFB.sendKey()
+#### RFB.disconnect()
 
-The `RFB.sendKey()` method is used to send a key event to the server.
+The `RFB.disconnect()` method is used to disconnect from the currently
+connected server.
 
 ##### Syntax
 
-    RFB.sendKey( keysym, code [, down] );
+```js
+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
+
+```js
+RFB.focus();
+RFB.focus(options);
+```
 
 ###### Parameters
 
-**`keysym`**
-  - A `long` specifying the RFB keysym to send. Can be `0` if a valid
-    **`code`** is specified.
+**`options`** *Optional*
+  - A `object` providing options to control how the focus will be
+    performed. Please see [`HTMLElement.focus()`][mdn-focus] for
+    available options.
 
-**`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.
+[mdn-focus]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
 
-**`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.getImageData()
 
-#### RFB.sendCtrlAltDel()
+The `RFB.getImageData()` method is used to return the current content of
+the screen encoded as [`ImageData`][mdn-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).
+[mdn-imagedata]: https://developer.mozilla.org/en-US/docs/Web/API/ImageData
 
 ##### Syntax
 
-    RFB.sendCtrlAltDel( );
+```js
+RFB.getImageData();
+```
 
-#### RFB.focus()
+#### RFB.machineReboot()
 
-The `RFB.focus()` method sets the keyboard focus on the remote session.
-Keyboard events will be sent to the remote server after this point.
+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.focus( );
+```js
+RFB.machineReboot();
+```
 
-#### RFB.blur()
+#### RFB.machineReset()
 
-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.
+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.blur( );
+```js
+RFB.machineReset();
+```
 
 #### RFB.machineShutdown()
 
@@ -348,38 +434,113 @@ have any effect.
 
 ##### Syntax
 
-    RFB.machineShutdown( );
+```js
+RFB.machineShutdown();
+```
 
-#### RFB.machineReboot()
+#### RFB.sendCredentials()
 
-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.
+The `RFB.sendCredentials()` method is used to provide the missing
+credentials after a `credentialsrequired` event has been fired.
 
 ##### Syntax
 
-    RFB.machineReboot( );
+```js
+RFB.sendCredentials(credentials);
+```
 
-#### RFB.machineReset()
+###### Parameters
 
-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.
+**`credentials`**
+  - 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.machineReset( );
+```js
+RFB.sendCtrlAltDel();
+```
 
-#### RFB.clipboardPasteFrom()
+#### RFB.sendKey()
 
-The `RFB.clipboardPasteFrom()` method is used to send clipboard data
-to the remote server.
+The `RFB.sendKey()` method is used to send a key event to the server.
 
 ##### Syntax
 
-    RFB.clipboardPasteFrom( text );
+```js
+RFB.sendKey(keysym, code);
+RFB.sendKey(keysym, code, down);
+```
 
 ###### Parameters
 
-**`text`**
-  - A `DOMString` specifying the clipboard data to send.
+**`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`][mdn-keycode].
+    If the physical key cannot be determined then `null` shall be
+    specified.
+
+[mdn-keycode]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
+
+**`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()
+
+The `RFB.toBlob()` method is used to return the current content of the
+screen encoded as [`Blob`][mdn-blob].
+
+[mdn-blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
+
+##### Syntax
+
+```js
+RFB.toBlob(callback);
+RFB.toBlob(callback, type);
+RFB.toBlob(callback, type, quality);
+```
+
+###### Parameters
+
+**`callback`**
+  - A callback function which will receive the resulting
+    [`Blob`][mdn-blob] as the single argument
+
+**`type`** *Optional*
+  - A string indicating the requested MIME type of the image
+
+**`quality`** *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
+
+```js
+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.