jandres/noVNC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'api' of https://github.com/CendioOssman/noVNC

Browse Source
This commit is contained in:
Pierre Ossman
2017-11-10 14:19:05 +01:00
parent a1d547657f a80b5fdaaf
commit a201bfc5eb
19 changed files with 1675 additions and 1871 deletions
Download Patch File Download Diff File Expand all files Collapse all files

561
docs/API.md
View File

@@ -1,255 +1,424 @@
# 1. Modules / API
# noVNC API
The noVNC client is a composed of several modular components that handle
rendering, input, networking, etc. Each of the modules is designed to
be cross-browser and be useful as a standalone library in other
projects (see LICENSE.txt).
The interface of the noVNC client consists of a single RFB object that
is instantiated once per connection.
## RFB
## 1.1 Module List
The `RFB` object represents a single connection to a VNC server. It
communicates using a WebSocket that must provide a standard RFB
protocol stream.
* __Mouse__ (core/input/mouse.js): Mouse input event handler with
limited touch support.
### Constructor
* __Keyboard__ (core/input/keyboard.js): Keyboard input event handler with
non-US keyboard support. Translates keyDown and keyUp events to X11
keysym values.
[`RFB()`](#rfb-1)
- Creates and returns a new `RFB` object.
* __Display__ (core/display.js): Efficient 2D rendering abstraction
layered on the HTML5 canvas element.
### Properties
* __Websock__ (core/websock.js): Websock client from websockify
with transparent binary data support.
[Websock API](https://github.com/novnc/websockify/wiki/websock.js) wiki page.
`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.
* __RFB__ (core/rfb.js): Main class that implements the RFB
protocol and stitches the other classes together.
`focusOnClick`
- Is a `boolean` indicating if keyboard focus should automatically be
moved to the canvas when a `mousedown` or `touchstart` event is
received.
`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.
## 1.2 Configuration Attributes
`viewportScale`
- 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.
The Mouse, Keyboard, Display and RFB classes have a similar API for
configuration options. Each configuration option has a default value,
which can be overridden by a a configuration object passed to the
constructor. Configuration options can then be read and modified after
initialization with "get_*" and "set_*" methods respectively. For
example, the following initializes an RFB object with the 'encrypt'
configuration option enabled, then confirms it was set, then disables
it.
`clipViewport`
- 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.
var rfb = new RFB({'encrypt': true});
if (rfb.get_encrypt()) {
alert("Encryption is set");
}
rfb.set_encrypt(false);
`dragViewport`
- Is a `boolean` indicating if mouse events should control the
relative position of a clipped canvas. Only relevant if
`clipViewport` is enabled. Disabled by default.
Some attributes are read-only and cannot be changed. For example, the
Display 'render_mode' option will throw an exception if an attempt is
made to set it. The attribute mode is one of the following:
`isClipped` *Read only*
- Is a `boolean` indicating if the framebuffer is larger than the
current canvas, i.e. it is being clipped.
RO - read only
RW - read write
WO - write once
`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
## 1.3 Methods
### Events
In addition to the getter and setter methods to modify configuration
attributes, each of the modules has other methods that are available
in the object instance. For example, the Display module has method
named 'blitImage' which takes an array of pixel data and draws it to
the 2D canvas.
[`updatestate`](#updatestate)
- The `updatestate` event is fired when the connection state of the
`RFB` object changes.
## 1.4 Callbacks
[`notification`](#notification)
- The `notification` event is fired when the `RFB` usage has a
message to display to the user.
Each of the modules has certain events that can be hooked with
callback functions. For the Mouse, Keyboard, Display and RFB classes
the callback functions are assigned to configuration attributes. The
WebSock module has a method named 'on' that takes two parameters: the
callback event name, and the callback function.
[`disconnect`](#disconnected)
- The `disconnect` event is fired when the `RFB` object disconnects.
## 2. Modules
[`credentialsrequired`](#credentialsrequired)
- The `credentialsrequired` event is fired when more credentials must
be given to continue.
## 2.1 Mouse Module
[`clipboard`](#clipboard)
- The `clipboard` event is fired when clipboard data is received from
the server.
### 2.1.1 Configuration Attributes
[`bell`](#bell)
- The `bell` event is fired when a audible bell request is received
from the server.
| name | type | mode | default | description
| ----------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures mouse input
| touchButton | int | RW | 1 | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
[`fbresize`](#fbresize)
- The `fbresize` event is fired when the framebuffer size is changed.
### 2.1.2 Methods
[`desktopname`](#desktopname)
- The `desktopname` event is fired when the remote desktop name
changes.
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing mouse events
| ungrab | () | Stop capturing mouse events
[`capabilities`](#capabilities)
- The `capabilities` event is fired when `RFB.capabilities` is
updated.
### 2.1.2 Callbacks
### Methods
| name | parameters | description
| ------------- | ------------------- | ------------
| onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
| onMouseMove | (x, y) | Handler for mouse movement
[`RFB.disconnect()`](#rfbdisconnect)
- Disconnect from the server.
[`RFB.sendCredentials()`](#rfbsendcredentials)
- Send credentials to server. Should be called after the
[`credentialsrequired`](#credentialsrequired) event has fired.
## 2.2 Keyboard Module
[`RFB.sendKey()`](#rfbsendKey)
- Send a key event.
### 2.2.1 Configuration Attributes
[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
- Send Ctrl-Alt-Del key sequence.
| name | type | mode | default | description
| ------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures keyboard input
[`RFB.machineShutdown()`](#rfbmachineshutdown)
- Request a shutdown of the remote machine.
### 2.2.2 Methods
[`RFB.machineReboot()`](#rfbmachinereboot)
- Request a reboot of the remote machine.
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing keyboard events
| ungrab | () | Stop capturing keyboard events
[`RFB.machineReset()`](#rfbmachinereset)
- Request a reset of the remote machine.
### 2.2.3 Callbacks
[`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
- Send clipboard contents to server.
| name | parameters | description
| ---------- | -------------------- | ------------
| onKeyPress | (keysym, code, down) | Handler for key press/release
[`RFB.autoscale()`](#rfbautoscale)
- Set `RFB.viewportScale` so that the framebuffer fits a specified
container.
[`RFB.requestDesktopSize()`](#rfbrequestDesktopSize)
- Send a request to change the remote desktop size.
## 2.3 Display Module
[`RFB.viewportChangeSize()`](#rfbviewportChangeSize)
- Change size of the viewport.
### 2.3.1 Configuration Attributes
### Details
| name | type | mode | default | description
| ----------- | ----- | ---- | ------- | ------------
| target | DOM | WO | | Canvas element for rendering
| context | raw | RO | | Canvas 2D context for rendering
| logo | raw | RW | | Logo to display when cleared: {"width": width, "height": height, "type": mime-type, "data": data}
| scale | float | RW | 1.0 | Display area scale factor 0.0 - 1.0
| viewport | bool | RW | false | Use viewport clipping
| width | int | RO | | Display area width
| height | int | RO | | Display area height
| render_mode | str | RO | '' | Canvas rendering mode
| prefer_js | str | RW | | Prefer JavaScript over canvas methods
| cursor_uri | raw | RW | | Can we render cursor using data URI
#### RFB()
### 2.3.2 Methods
The `RFB()` constructor returns a new `RFB` object and initiates a new
connection to a specified VNC server.
| name | parameters | description
| ------------------ | ------------------------------------------------------- | ------------
| viewportChangePos | (deltaX, deltaY) | Move the viewport relative to the current location
| viewportChangeSize | (width, height) | Change size of the viewport
| absX | (x) | Return X relative to the remote display
| absY | (y) | Return Y relative to the remote display
| resize | (width, height) | Set width and height
| flip | (from_queue) | Update the visible canvas with the contents of the rendering canvas
| clear | () | Clear the display (show logo if set)
| pending | () | Check if there are waiting items in the render queue
| flush | () | Resume processing the render queue unless it's empty
| fillRect | (x, y, width, height, color, from_queue) | Draw a filled in rectangle
| copyImage | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
| imageRect | (x, y, mime, arr) | Draw a rectangle with an image
| startTile | (x, y, width, height, color) | Begin updating a tile
| subTile | (tile, x, y, w, h, color) | Update a sub-rectangle within the given tile
| finishTile | () | Draw the current tile to the display
| blitImage | (x, y, width, height, arr, offset, from_queue) | Blit pixels (of R,G,B,A) to the display
| blitRgbImage | (x, y, width, height, arr, offset, from_queue) | Blit RGB encoded image to display
| blitRgbxImage | (x, y, width, height, arr, offset, from_queue) | Blit RGBX encoded image to display
| drawImage | (img, x, y) | Draw image and track damage
| changeCursor | (pixels, mask, hotx, hoty, w, h) | Change cursor appearance
| defaultCursor | () | Restore default cursor appearance
| disableLocalCursor | () | Disable local (client-side) cursor
| clippingDisplay | () | Check if the remote display is larger than the client display
| autoscale | (containerWidth, containerHeight, downscaleOnly) | Scale the display
##### Syntax
### 2.3.3 Callbacks
var rfb = new RFB( target, url [, options] );
| name | parameters | description
| ------- | ---------- | ------------
| onFlush | () | A display flush has been requested and we are now ready to resume FBU processing
###### 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.
## 2.4 RFB Module
**`url`**
- A `DOMString` specifying the VNC server to connect to. This must be
a valid WebSocket URL.
### 2.4.1 Configuration Attributes
**`options`** *Optional*
- An `Object` specifying extra details about how the connection
should be made.
| name | type | mode | default | description
| ----------------- | ---- | ---- | ---------- | ------------
| target | DOM | WO | null | Canvas element for rendering (passed to Display, Mouse and Keyboard)
| encrypt | bool | RW | false | Use TLS/SSL encryption
| local_cursor | bool | RW | false | Request locally rendered cursor
| shared | bool | RW | true | Request shared VNC mode
| view_only | bool | RW | false | Disable client mouse/keyboard
| focus_on_click | bool | RW | true | Grab focus on canvas on mouse click
| xvp_password_sep | str | RW | '@' | Separator for XVP password fields
| disconnectTimeout | int | RW | 3 | Time (in seconds) to wait for disconnection
| wsProtocols | arr | RW | ['binary'] | Protocols to use in the WebSocket connection
| repeaterID | str | RW | '' | UltraVNC RepeaterID to connect to
| viewportDrag | bool | RW | false | Move the viewport on mouse drags
Possible options:
### 2.4.2 Methods
`shared`
- A `boolean` indicating if the remote server should be shared or
if any other connected clients should be disconnected. Enabled
by default.
| name | parameters | description
| ------------------ | ---------------------------- | ------------
| connect | (host, port, password, path) | Connect to the given host:port/path. Optional password and path.
| disconnect | () | Disconnect
| sendPassword | (passwd) | Send password after onPasswordRequired callback
| sendCtrlAltDel | () | Send Ctrl-Alt-Del key sequence
| xvpOp | (ver, op) | Send a XVP operation (2=shutdown, 3=reboot, 4=reset)
| xvpShutdown | () | Send XVP shutdown.
| xvpReboot | () | Send XVP reboot.
| xvpReset | () | Send XVP reset.
| 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
| requestDesktopSize | (width, height) | Send a request to change the remote desktop size.
`credentials`
- An `Object` specifying the credentials to provide to the server
when authenticating. The following credentials are possible:
### 2.4.3 Callbacks
| name | type | description
| ------------ | ----------- | -----------
| `"username"` | `DOMString` | The user that authenticates
| `"password"` | `DOMString` | Password for the user
| `"target"` | `DOMString` | Target machine or session
| 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.
| onPasswordRequired | (rfb, msg) | VNC password is required (use sendPassword), optionally comes with a message.
| onClipboard | (rfb, text) | RFB clipboard contents received
| onBell | (rfb) | RFB Bell message received
| onFBUReceive | (rfb, fbu) | RFB FBU received but not yet processed (see details below)
| onFBUComplete | (rfb, fbu) | RFB FBU received and processed (see details below)
| onFBResize | (rfb, width, height) | Frame buffer (remote desktop) size changed
| onDesktopName | (rfb, name) | VNC desktop name recieved
| onXvpInit | (version) | XVP extensions active for this connection.
`repeaterID`
- A `DOMString` specifying the ID to provide to any VNC repeater
encountered.
#### updatestate
__RFB onUpdateState callback details__
The `updatestate` event is fired after the noVNC connection state
changes. The `detail` property is an `Object` containg the property
`state` with the new connection state.
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.
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 - permanent end-state for this RFB object
| connection state | description
| ----------------- | ------------
| `"connecting"` | starting to connect
| `"connected"` | connected normally
| `"disconnecting"` | starting to disconnect
| `"disconnected"` | disconnected
__RFB onFBUReceive and on FBUComplete callback details__
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.
The onFBUReceive callback is invoked when a frame buffer update
message has been received from the server but before the RFB class has
done any additional handling. The onFBUComplete callback is invoked
with the same information but after the RFB class has handled the
message.
#### notification
The 'fbu' parameter is an object with the following structure:
The `notification` event is fired when the `RFB` object wants a message
displayed to the user. The `detail` property is an `Object` containing
the following properties:
{
x: FBU_x_position,
y: FBU_y_position,
width: FBU_width,
height: FBU_height,
encoding: FBU_encoding_number,
encodingName: FBU_encoding_string
}
| Property | Type | Description
| --------- | ----------- | -----------
| `message` | `DOMString` | The message to display
| `level` | `DOMString` | The severity of the message
The following levels are currently defined:
- `"normal"`
- `"warn"`
- `"error"`
#### disconnect
The `disconnect` event is fired when the connection has been
terminated. The `detail` property is an `Object` the optionally
contains the property `reason`. `reason` is a `DOMString` specifying
the reason in the event of an unexpected termination. `reason` will be
omitted for a clean termination.
#### 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.
#### 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.
#### fbresize
The `fbresize` event is fired when the framebuffer has changed
dimensions. The `detail` property is an `Object` with the properties
`width` and `height` specifying the new dimensions.
#### 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( );
#### 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
**`credentials`**
- An `Object` specifying the credentials to provide to the server
when authenticating. See [`RFB()`](#rfb-1) 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.viewportScale` to fit given dimensions.
##### Syntax
RFB.autoscale( width, height );
###### 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.
#### 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.
The [`fbresize`](#fbresize) event will be fired 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.clipViewport` 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.