GitHub/noVNC
1
0
Fork 0
mirror of https://github.com/novnc/noVNC.git synced 2026-05-26 15:13:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
ee5cae9fee484794211d89de55e9d454abd4d599
noVNC/docs/API.md
Samuel Mannehed ee5cae9fee Replace updatestate event with connect 
Instead of exposing all the internal connection states, the RFB module
will now only send events on connect and on disconnect. This makes it
simpler for the application and gets rid of the double events that were
being sent on disconnect (previously updatestate and disconnect).
2017-11-14 14:10:36 +01:00

391 lines
11 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.
[`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` 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.
Reference in New Issue View Git Blame Copy Permalink