GitHub/noVNC
1
0
Fork 0
mirror of https://github.com/novnc/noVNC.git synced 2026-05-27 15:39:41 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
62bfc487591e6be75e9204badf26e840d541885e
noVNC/docs/API.md
Samuel Mannehed d472f3f19e Abstract RFB errors to avoid sending strings 
The API allowed strings to be passed from the RFB module to the
application using the disconnect reason. This caused problems since
the application didn't have control over translations for these
strings.

Most of the information being passed using this string was very
technical and not helpful to the end user. One exception to this was
the security result information regarding for example authentication
failures. The protocol allows the VNC server to pass a string
directly to the user in the security result.

So the disconnect reason is replaced by a boolean saying if the
disconnection was clean or not. And for the security result information
from the server, a new event has been added.
2017-11-14 15:36:12 +01:00

415 lines
12 KiB
Markdown
Raw Blame History

# noVNC API
The interface of the noVNC client consists of a single RFB object that
is instantiated once per connection.
## RFB
The `RFB` object represents a single connection to a VNC server. It
communicates using a WebSocket that must provide a standard RFB
protocol stream.
### Constructor
[`RFB()`](#rfb-1)
- Creates and returns a new `RFB` object.
### 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.
`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.
`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.
`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.
`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.
`isClipped` *Read only*
- Is a `boolean` indicating if the framebuffer is larger than the
current canvas, i.e. it is being clipped.
`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
### Events
[`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.
[`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.
[`fbresize`](#fbresize)
- The `fbresize` event is fired when the framebuffer size is changed.
[`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.
### Methods
[`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.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.viewportScale` so that the framebuffer fits a specified
container.
[`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 and initiates a new
connection to a specified VNC server.
##### Syntax
var rfb = new RFB( target, url [, options] );
###### 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.
**`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.
#### 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.
#### disconnect
The `disconnect` event is fired when the connection has been
terminated. The `detail` property is an `Object` that contains the
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
the server fails during the security negotiation step. The `detail`
property is an `Object` containing the following properties:
| Property | Type | Description
| -------- | ----------- | -----------
| `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)
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
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.
#### 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.
Reference in New Issue View Git Blame Copy Permalink