The interface of the noVNC client consists of a single RFB object that is instantiated once per connection.
The RFB object represents a single connection to a VNC server. It
communicates using a WebSocket that must provide a standard RFB
protocol stream.
RFB object.viewOnly
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
boolean indicating if keyboard focus should automatically be
moved to the remote session when a mousedown or touchstart
event is received. Enabled by default.clipViewport
boolean indicating if the remote session should be clipped
to its container. When disabled scrollbars will be shown to handle
the resulting overflow. Disabled by default.dragViewport
boolean indicating if mouse events should control the
relative position of a clipped remote session. Only relevant if
clipViewport is enabled. Disabled by default.scaleViewport
boolean indicating if the remote session should be scaled
locally so it fits its container. When disabled it will be centered
if the remote session is smaller than its container, or handled
according to clipViewport if it is larger. Disabled by default.resizeSession
boolean indicating if a request to resize the remote session
should be sent whenever the container changes dimensions. Disabled
by default.showDotCursor
boolean indicating whether a dot cursor should be shown
instead of a zero-sized or fully-transparent cursor if the server
sets such invisible cursor. Disabled by default.background
rgb(40, 40, 40)
(solid gray color).qualityLevel
int in range [0-9] controlling the desired JPEG quality.
Value 0 implies low quality and 9 implies high quality.
Default value is 6.compressionLevel
int in range [0-9] controlling the desired compression
level. Value 0 means no compression. Level 1 uses a minimum of CPU
resources and achieves weak compression ratios, while level 9 offers
best compression but is slow in terms of CPU consumption on the server
side. Use high levels with very slow network connections.
Default value is 2.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 |
connect event is fired when the RFB object has completed
the connection and handshaking with the server.disconnect event is fired when the RFB object disconnects.serververification event is fired when the server identity
must be confirmed by the user.credentialsrequired event is fired when more credentials must
be given to continue.securityfailure event is fired when the security negotiation
with the server fails.clipboard event is fired when clipboard data is received from
the server.bell event is fired when a audible bell request is received
from the server.desktopname event is fired when the remote desktop name
changes.capabilities event is fired when RFB.capabilities is
updated.serververification event has fired and the
user has verified the identity of the server.credentialsrequired event has fired.The RFB() constructor returns a new RFB object and initiates a new
connection to a specified VNC server.
let rfb = new RFB( target, url [, options] );
target
HTMLElement
that specifies where the RFB object should attach itself. The
existing contents of the HTMLElement will be untouched, but new
elements will be added during the lifetime of the RFB object.urlOrDataChannel
DOMString specifying the VNC server to connect to. This must be
a valid WebSocket URL. This can also be a WebSocket or RTCDataChannel.options Optional
An Object specifying extra details about how the connection
should be made.
Possible options:
shared
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
DOMString specifying the ID to provide to any VNC repeater
encountered.wsProtocols
Array of DOMStrings specifying the sub-protocols to use
in the WebSocket connection. Empty by default.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.
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.
The serververification event is fired when the server provides
information that allows the user to verify that it is the correct server
and protect against a man-in-the-middle attack. The detail property is
an Object containing the property type which is a DOMString
specifying which type of information the server has provided. Other
properties are also available, depending on the value of type:
"RSA"
publickey is a Uint8Array containing the public key in a unsigned
big endian representation.The credentialsrequired event is fired when the server requests more
credentials than were specified to RFB(). The detail
property is an Object containing the property types which is an
Array of DOMString listing the credentials that are required.
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
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.
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.
The bell event is fired when the server has requested an audible
bell.
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.
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.
The RFB.disconnect() method is used to disconnect from the currently
connected server.
RFB.disconnect( );
The RFB.approveServer() method is used to signal that the user has
verified the server identity provided in a serververification event
and that the connection can continue.
RFB.approveServer( );
The RFB.sendCredentials() method is used to provide the missing
credentials after a credentialsrequired event has been fired.
RFB.sendCredentials( credentials );
credentials
Object specifying the credentials to provide to the server
when authenticating. See RFB() for details.The RFB.sendKey() method is used to send a key event to the server.
RFB.sendKey( keysym, code [, down] );
keysym
long specifying the RFB keysym to send. Can be 0 if a valid
code is specified.code
DOMString specifying the physical key to send. Valid values are
those that can be specified to
KeyboardEvent.code.
If the physical key cannot be determined then null shall be
specified.down Optional
boolean specifying if a press or a release event should be
sent. If omitted then both a press and release event are sent.The RFB.sendCtrlAltDel() method is used to send the key sequence
left Control, left Alt, Delete. This is a convenience wrapper
around RFB.sendKey().
RFB.sendCtrlAltDel( );
The RFB.focus() method sets the keyboard focus on the remote session.
Keyboard events will be sent to the remote server after this point.
RFB.focus( [options] );
options Optional
object providing options to control how the focus will be
performed. Please see HTMLElement.focus()
for available options.The RFB.blur() method remove keyboard focus on the remote session.
Keyboard events will no longer be sent to the remote server after this
point.
RFB.blur( );
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.
RFB.machineShutdown( );
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.
RFB.machineReboot( );
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.
RFB.machineReset( );
The RFB.clipboardPasteFrom() method is used to send clipboard data
to the remote server.
RFB.clipboardPasteFrom( text );
text
DOMString specifying the clipboard data to send.