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.
- Creates and returns a new
RFB
object.
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 remote session when amousedown
ortouchstart
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 asMouseEvent.button
. Is set to1
by default.
clipViewport
- Is a
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
- Is a
boolean
indicating if mouse events should control the relative position of a clipped remote session. Only relevant ifclipViewport
is enabled. Disabled by default.
scaleViewport
- Is a
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 toclipViewport
if it is larger. Disabled by default.
resizeSession
- Is a
boolean
indicating if a request to resize the remote session should be sent whenever the container changes dimensions. Disabled by default.
showDotCursor
- Is a
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
- Is a valid CSS background
style value indicating which background style should be applied
to the element containing the remote session screen. The default value is
rgb(40, 40, 40)
(solid gray color).
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
- The
connect
event is fired when theRFB
object has completed the connection and handshaking with the server.
- The
disconnect
event is fired when theRFB
object disconnects.
- The
credentialsrequired
event is fired when more credentials must be given to continue.
- The
securityfailure
event is fired when the security negotiation with the server fails.
- The
clipboard
event is fired when clipboard data is received from the server.
- The
bell
event is fired when a audible bell request is received from the server.
- The
desktopname
event is fired when the remote desktop name changes.
- The
capabilities
event is fired whenRFB.capabilities
is updated.
- Disconnect from the server.
- Send credentials to server. Should be called after the
credentialsrequired
event has fired.
- Send a key event.
- Send Ctrl-Alt-Del key sequence.
- Move keyboard focus to the remote session.
- Remove keyboard focus from the remote session.
- Request a shutdown of the remote machine.
- Request a reboot of the remote machine.
- Request a reset of the remote machine.
- Send clipboard contents to server.
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
- A block
HTMLElement
that specifies where theRFB
object should attach itself. The existing contents of theHTMLElement
will be untouched, but new elements will be added during the lifetime of theRFB
object.
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.
wsProtocols
- An
Array
ofDOMString
s specifying the sub-protocols to use in the WebSocket connection. Empty by default.
- A
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 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.sendCredentials()
method is used to provide the missing
credentials after a credentialsrequired
event has been fired.
RFB.sendCredentials( credentials );
credentials
- An
Object
specifying the credentials to provide to the server when authenticating. SeeRFB()
for details.
The RFB.sendKey()
method is used to send a key event to the server.
RFB.sendKey( keysym, code [, down] );
keysym
- A
long
specifying the RFB keysym to send. Can be0
if a validcode
is specified.
code
- A
DOMString
specifying the physical key to send. Valid values are those that can be specified toKeyboardEvent.code
. If the physical key cannot be determined thennull
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.
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( );
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
- A
DOMString
specifying the clipboard data to send. Currently only characters from ISO 8859-1 are supported.