From 4f90c1d387dbd0de156a5f29f2868c05c7aa7854 Mon Sep 17 00:00:00 2001 From: Pierre Ossman Date: Mon, 16 Oct 2017 14:47:03 +0200 Subject: [PATCH] Follow MDN style in API documentation --- docs/API.md | 531 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 460 insertions(+), 71 deletions(-) diff --git a/docs/API.md b/docs/API.md index 64627698..ad16990a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,94 +1,483 @@ -# API +# noVNC API The interface of the noVNC client consists of a single RFB object that is instantiated once per connection. +## RFB -## 1 Configuration Attributes +The `RFB` object represents a single connection to a VNC server. It +communicates using a WebSocket that must provide a standard RFB +protocol stream. -| name | type | mode | default | description -| ----------------- | ----- | ---- | ---------- | ------------ -| localCursor | bool | RW | false | Request locally rendered cursor -| viewOnly | bool | RW | false | Disable client mouse/keyboard -| touchButton | int | RW | 1 | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks. -| scale | float | RW | 1.0 | Display area scale factor -| viewport | bool | RW | false | Use viewport clipping -| disconnectTimeout | int | RW | 3 | Time (in seconds) to wait for disconnection -| viewportDrag | bool | RW | false | Move the viewport on mouse drags -| capabilities | arr | RO | [] | Supported capabilities (can include: 'power', 'resize') +### Constructor +[`RFB()`](#rfb-1) + - Creates and returns a new `RFB` object. -## 2 Methods +### Properties -| name | parameters | description -| ------------------ | ------------------------------- | ------------ -| connect | (url, options) | Connect to the given URL -| disconnect | () | Disconnect -| sendCredentials | (credentials) | Send credentials after onCredentialsRequired callback -| sendCtrlAltDel | () | Send Ctrl-Alt-Del key sequence -| machineShutdown | () | Request a shutdown of the remote machine. -| machineReboot | () | Request a reboot of the remote machine. -| machineReset | () | Request a reset of the remote machine. -| sendKey | (keysym, code, down) | Send a key press event. If down not specified, send a down and up event. -| clipboardPasteFrom | (text) | Send a clipboard paste event -| autoscale | (width, height, downscaleOnly) | Scale the display -| clippingDisplay | () | Check if the remote display is larger than the client display -| requestDesktopSize | (width, height) | Send a request to change the remote desktop size. -| viewportChangeSize | (width, height) | Change size of the viewport +`localCursor` + - Is a `boolean` indicating if a client side cursor should be + requested. Disabled by default. -__connect() details__ +`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. -The connect() call supports the following options: +`touchButton` + - Is a `long` controlling the button mask that should be simulated + when a touch event is recieved. Uses the same values as + [`MouseEvent.button`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button). + Is set to `1` by default. -| name | type | default | description -| ----------------- | ----- | ---------- | ------------ -| shared | bool | true | Request shared VNC mode -| credentials | obj | {} | Credentials to use when authenticating -| repeaterID | str | '' | UltraVNC RepeaterID to connect to +`scale` + - Is a `double` indicating how the framebuffer contents should be + scaled before being rendered on to the canvas. See also + [`RFB.autoscale()`](#rfbautoscale). Is set to `1.0` by default. +`viewport` + - Is a `boolean` indicating if the canvas should be clipped to its + container. When disabled the container must be able to handle the + resulting overflow. Disabled by default. -## 3 Callbacks +`viewportDrag` + - Is a `boolean` indicating if mouse events should control the + relative position of a clipped canvas. Only relevant if `viewport` + is enabled. Disabled by default. -The RFB object has certain events that can be hooked with callback -functions. +`disconnectTimeout` + - Is a `long` indicating how many seconds to wait for a disconnect + request to complete. Is set to `3` by default. -| name | parameters | description -| --------------------- | -------------------------- | ------------ -| onupdatestate | (rfb, state, oldstate) | Connection state change (see details below) -| onnotification | (rfb, msg, level, options) | Notification for the UI (optional options) -| ondisconnected | (rfb, reason) | Disconnection finished with an optional reason. No reason specified means normal disconnect. -| oncredentialsrequired | (rfb, types) | VNC credentials are required (use sendCredentials) -| onclipboard | (rfb, text) | RFB clipboard contents received -| onbell | (rfb) | RFB Bell message received -| onfbresize | (rfb, width, height) | Frame buffer (remote desktop) size changed -| ondesktopname | (rfb, name) | VNC desktop name recieved -| oncapabilities | (rfb, capabilities) | The supported capabilities has changed +`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 + | `resize` | `boolean` | The framebuffer can be resized -__RFB onUpdateState callback details__ +### Event handlers -The RFB module has an 'onUpdateState' callback that is invoked after -the noVNC connection state changes. Here is a list of the states that -are reported. Note that the RFB module can not transition from the -disconnected state in any way, a new instance of the object has to be -created for new connections. +[`RFB.onupdatestate()`](#rfbonupdatestate) + - An event handler called when the connection state of the `RFB` + object changes. -| connection state | description -| ---------------- | ------------ -| connecting | starting to connect -| connected | connected normally -| disconnecting | starting to disconnect -| disconnected | disconnected - permanent end-state for this RFB object +[`RFB.onnotification()`](#rfbonnotification) + - An event handler called when the `RFB` usage has a message to + display to the user. -__RFB onCredentialsRequired callback details__ +[`RFB.ondisconnected()`](#rfbondisconnected) + - An event handler called when the `RFB` object disconnects. -The onCredentialsRequired callback is called when the server requests more -credentials than was specified to connect(). The types argument is a list -of all the credentials that are required. Currently the following are -defined: +[`RFB.oncredentialsrequired()`](#rfboncredentialsrequired) + - An event hander called when more credentials must be given to + continue. -| name | description -| -------- | ------------ -| username | User that authenticates -| password | Password for user -| target | String specifying target machine or session +[`RFB.onclipboard()`](#rfbonclipboard) + - An event handler called when clipboard data is received from the + server. + +[`RFB.onbell()`](#rfbonbell) + - An event handler called when a audible bell request is received + from the server. + +[`RFB.onfbresize()`](#rfbonfbresize) + - An event handler called when the framebuffer size is changed. + +[`RFB.ondesktopname()`](#rfbondesktopname) + - An event handler called when the remote desktop name changes. + +[`RFB.oncapabilities()`](#rfboncapabilities) + - An event handler called when `RFB.capabilities` is updated. + +### Methods + +[`RFB.connect()`](#rfbconnect) + - Connect to a server. + +[`RFB.disconnect()`](#rfbdisconnect) + - Disconnect from the server. + +[`RFB.sendCredentials()`](#rfbsendcredentials) + - Send credentials to server. Should be called after + [`oncredentialsrequired`](#rfboncredentialsrequired) has been + called. + +[`RFB.sendKey()`](#rfbsendKey) + - Send a key event. + +[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) + - Send Ctrl-Alt-Del key sequence. + +[`RFB.machineShutdown()`](#rfbmachineshutdown) + - Request a shutdown of the remote machine. + +[`RFB.machineReboot()`](#rfbmachinereboot) + - Request a reboot of the remote machine. + +[`RFB.machineReset()`](#rfbmachinereset) + - Request a reset of the remote machine. + +[`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom) + - Send clipboard contents to server. + +[`RFB.autoscale()`](#rfbautoscale) + - Set `RFB.scale` so that the framebuffer fits a specified container. + +[`RFB.clippingDisplay()`](#rfbclippingDisplay) + - Returns `true` if the framebuffer is larger than what is currently + displayed on the canvas. + +[`RFB.requestDesktopSize()`](#rfbrequestDesktopSize) + - Send a request to change the remote desktop size. + +[`RFB.viewportChangeSize()`](#rfbviewportChangeSize) + - Change size of the viewport. + +### Details + +#### RFB() + +The `RFB()` constructor returns a new `RFB` object. The object will +initially be disconnected and [`RFB.connect()`](#rfbconnect) must be +called before the object will be useful. + +##### Syntax + + var rfb = new RFB( target ); + +###### Parameters + +**`target`** + - A [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) + that specifies where graphics should be rendered and input events + should be monitored. + +#### RFB.onupdatestate + +The `onupdatestate` event handler is fired after the noVNC connection +state changes. Here is a list of the states that are reported: + +| connection state | description +| ----------------- | ------------ +| `"connecting"` | starting to connect +| `"connected"` | connected normally +| `"disconnecting"` | starting to disconnect +| `"disconnected"` | disconnected + +Note that a `RFB` objects can not transition from the disconnected +state in any way, a new instance of the object has to be created for +new connections. + +##### Syntax + + RFB.onupdatestate = function(rfb, state) { ... } + +#### RFB.onnotification + +The `onnotification` event handler is fired when the `RFB` object wants +a message displayed to the user. **`msg`** is a `DOMString` specifying +the actual message, and **`level`** is a `DOMString` indicating the +severity of the message. The following levels are currently defined: + + - `"normal"` + - `"warn"` + - `"error"` + +**`options`** is currently unused. + +##### Syntax + + RFB.onnotification = function(rfb, msg, level, options) { ... } + +#### RFB.ondisconnected + +The `ondisconnected` event handler is fired when the connection has +been terminated. **`reason`** is `undefined` for a clean termination +and a `DOMString` specifying the reason in the event of an unexpected +termination. + +##### Syntax + + RFB.ondisconnected = function(rfb, reason) { ... } + +#### RFB.oncredentialsrequired + +The `oncredentialsrequired` event handler is fired when the server +requests more credentials than were specified to +[`RFB.connect()`](#rfbconnect). The **`types`** argument is a list of +all the credentials that are required. + +##### Syntax + + RFB.oncredentialsrequired = function(rfb, types) { ... } + +#### RFB.onclipboard + +The `onclipboard` event handler is fired when the server has sent +clipboard data. + +##### Syntax + + RFB.onclipboard = function(rfb, text) { ... } + +#### RFB.onbell + +The `onbell` event handler is fired when the server has requested an +audible bell. + +##### Syntax + + RFB.onbell = function(rfb) { ... } + +#### RFB.onfbresize + +The `onfbresize` event handler is fired when the framebuffer has +changed dimensions. + +##### Syntax + + RFB.onfbresize = function(rfb, width, height) { ... } + +#### RFB.ondesktopname + +The `ondesktopname` event handler is fired when the name of the remote +desktop changes. + +##### Syntax + + RFB.ondesktopname = function(rfb, name) { ... } + +#### RFB.oncapabilities + +The `oncapabilities` event handler is fired whenever an entry is added +or removed from `RFB.capabilities`. + +##### Syntax + + RFB.oncapabilities = function(rfb, capabilites) { ... } + +#### RFB.connect() + +The `RFB.connect()` method is used to initiate a new connection to a +specified VNC server. + +##### Syntax + + RFB.connect( url [, options] ); + +###### Parameters + +**`url`** + - A `DOMString` specifying the VNC server to connect to. This must be + a valid WebSocket URL. + +**`options`** *Optional* + - An `Object` specifying extra details about how the connection + should be made. + + Possible options: + + `shared` + - A `boolean` indicating if the remote server should be shared or + if any other connected clients should be disconnected. Enabled + by default. + + `credentials` + - An `Object` specifying the credentials to provide to the server + when authenticating. The following credentials are possible: + + | name | type | description + | ------------ | ----------- | ----------- + | `"username"` | `DOMString` | The user that authenticates + | `"password"` | `DOMString` | Password for the user + | `"target"` | `DOMString` | Target machine or session + + `repeaterID` + - A `DOMString` specifying the ID to provide to any VNC repeater + encountered. + +#### RFB.disconnect() + +The `RFB.disconnect()` method is used to disconnect from the currently +connected server. + +##### Syntax + + RFB.disconnect( ); + +#### RFB.sendCredentials() + +The `RFB.sendCredentials()` method is used to provide the missing +credentials after `RFB.oncredentialsrequired` has been fired. + +##### Syntax + + RFB.sendCredentials( credentials ); + +###### Parameters + +**`credentials`** + - An `Object` specifying the credentials to provide to the server + when authenticating. See [`RFB.connect()`](#rfbconnect) for + details. + +#### RFB.sendKey() + +The `RFB.sendKey()` method is used to send a key event to the server. + +##### Syntax + + RFB.sendKey( keysym, code [, down] ); + +###### 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. + +#### 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.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. Currently only + characters from ISO 8859-1 are supported. + +#### RFB.autoscale() + +The `RFB.autoscale()` method is used to automatically adjust +`RFB.scale` to fit given dimensions. + +##### Syntax + + RFB.autoscale( width, height, downscaleOnly ); + +###### Parameters + +**`width`** + - A `long` specifying the maximum width of the canvas in CSS pixels. + +**`height`** + - A `long` specifying the maximum height of the canvas in CSS pixels. + +**`downscaleOnly`** + - A `boolean` specifying if the scale must be kept below `1.0`. + +#### RFB.clippingDisplay() + +The `RFB.clippingDisplay()` method is used to determine if the +framebuffer is larger than the current canvas, i.e. it is being +clipped. + +##### Syntax + + RFB.clippingDisplay( ); + +###### Return value + +Returns a `boolean` indicating if the framebuffer is currently being +clipped. + +#### RFB.requestDesktopSize() + +The `RFB.requestDesktopSize()` method is used to request a change of +the framebuffer. The capability `resize` must be set for this method to +have any effect. + +Note that this is merely a request and the server may deny it. +[`RFB.onfbresize`](#rfbonfbresize) will be called when the framebuffer +actually changes dimensions. + +##### Syntax + + RFB.requestDesktopSize( width, height ); + +###### Parameters + +**`width`** + - A `long` specifying the new requested width in CSS pixels. + +**`height`** + - A `long` specifying the new requested height in CSS pixels. + +#### RFB.viewportChangeSize() + +The `RFB.viewportChangeSize()` method is used to change the size of the +canvas rather than the underlying framebuffer. + +This method has no effect if `RFB.viewport` is set to `false`. + +##### Syntax + + RFB.viewportChangeSize( width, height ); + +###### Parameters + +**`width`** + - A `long` specifying the new width in CSS pixels. + +**`height`** + - A `long` specifying the new height in CSS pixels.