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

Follow MDN style in API documentation

This commit is contained in:
Pierre Ossman 2017-10-16 14:47:03 +02:00
parent 747b462337
commit 4f90c1d387
1 changed files with 460 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

529
docs/API.md
View File

@ -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.
[`RFB.onnotification()`](#rfbonnotification)
- An event handler called when the `RFB` usage has a message to
display to the user.
[`RFB.ondisconnected()`](#rfbondisconnected)
- An event handler called when the `RFB` object disconnects.
[`RFB.oncredentialsrequired()`](#rfboncredentialsrequired)
- An event hander called when more credentials must be given to
continue.
[`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 - permanent end-state for this RFB object
| ----------------- | ------------
| `"connecting"` | starting to connect
| `"connected"` | connected normally
| `"disconnecting"` | starting to disconnect
| `"disconnected"` | disconnected
__RFB onCredentialsRequired 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 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:
##### Syntax
| name | description
| -------- | ------------
| username | User that authenticates
| password | Password for user
| target | String specifying target machine or session
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.