3 The interface of the noVNC client consists of a single RFB object that
4 is instantiated once per connection.
8 The `RFB` object represents a single connection to a VNC server. It
9 communicates using a WebSocket that must provide a standard RFB
15 - Creates and returns a new `RFB` object.
20 - Is a `boolean` indicating if any events (e.g. key presses or mouse
21 movement) should be prevented from being sent to the server.
25 - Is a `boolean` indicating if keyboard focus should automatically be
26 moved to the remote session when a `mousedown` or `touchstart`
27 event is received. Enabled by default.
30 - Is a `boolean` indicating if the remote session should be clipped
31 to its container. When disabled scrollbars will be shown to handle
32 the resulting overflow. Disabled by default.
35 - Is a `boolean` indicating if mouse events should control the
36 relative position of a clipped remote session. Only relevant if
37 `clipViewport` is enabled. Disabled by default.
40 - Is a `boolean` indicating if the remote session should be scaled
41 locally so it fits its container. When disabled it will be centered
42 if the remote session is smaller than its container, or handled
43 according to `clipViewport` if it is larger. Disabled by default.
46 - Is a `boolean` indicating if a request to resize the remote session
47 should be sent whenever the container changes dimensions. Disabled
51 - Is a `boolean` indicating whether a dot cursor should be shown
52 instead of a zero-sized or fully-transparent cursor if the server
53 sets such invisible cursor. Disabled by default.
56 - Is a valid CSS [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
57 style value indicating which background style should be applied
58 to the element containing the remote session screen. The default value is `rgb(40, 40, 40)`
62 - Is an `int` in range `[0-9]` controlling the desired JPEG quality.
63 Value `0` implies low quality and `9` implies high quality.
67 - Is an `int` in range `[0-9]` controlling the desired compression
68 level. Value `0` means no compression. Level 1 uses a minimum of CPU
69 resources and achieves weak compression ratios, while level 9 offers
70 best compression but is slow in terms of CPU consumption on the server
71 side. Use high levels with very slow network connections.
74 `capabilities` *Read only*
75 - Is an `Object` indicating which optional extensions are available
76 on the server. Some methods may only be called if the corresponding
77 capability is set. The following capabilities are defined:
79 | name | type | description
80 | -------- | --------- | -----------
81 | `power` | `boolean` | Machine power control is available
86 - The `connect` event is fired when the `RFB` object has completed
87 the connection and handshaking with the server.
89 [`disconnect`](#disconnected)
90 - The `disconnect` event is fired when the `RFB` object disconnects.
92 [`credentialsrequired`](#credentialsrequired)
93 - The `credentialsrequired` event is fired when more credentials must
96 [`securityfailure`](#securityfailure)
97 - The `securityfailure` event is fired when the security negotiation
98 with the server fails.
100 [`clipboard`](#clipboard)
101 - The `clipboard` event is fired when clipboard data is received from
105 - The `bell` event is fired when a audible bell request is received
108 [`desktopname`](#desktopname)
109 - The `desktopname` event is fired when the remote desktop name
112 [`capabilities`](#capabilities)
113 - The `capabilities` event is fired when `RFB.capabilities` is
118 [`RFB.disconnect()`](#rfbdisconnect)
119 - Disconnect from the server.
121 [`RFB.sendCredentials()`](#rfbsendcredentials)
122 - Send credentials to server. Should be called after the
123 [`credentialsrequired`](#credentialsrequired) event has fired.
125 [`RFB.sendKey()`](#rfbsendKey)
128 [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
129 - Send Ctrl-Alt-Del key sequence.
131 [`RFB.focus()`](#rfbfocus)
132 - Move keyboard focus to the remote session.
134 [`RFB.blur()`](#rfbblur)
135 - Remove keyboard focus from the remote session.
137 [`RFB.machineShutdown()`](#rfbmachineshutdown)
138 - Request a shutdown of the remote machine.
140 [`RFB.machineReboot()`](#rfbmachinereboot)
141 - Request a reboot of the remote machine.
143 [`RFB.machineReset()`](#rfbmachinereset)
144 - Request a reset of the remote machine.
146 [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
147 - Send clipboard contents to server.
153 The `RFB()` constructor returns a new `RFB` object and initiates a new
154 connection to a specified VNC server.
158 let rfb = new RFB( target, url [, options] );
163 - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
164 that specifies where the `RFB` object should attach itself. The
165 existing contents of the `HTMLElement` will be untouched, but new
166 elements will be added during the lifetime of the `RFB` object.
169 - A `DOMString` specifying the VNC server to connect to. This must be
170 a valid WebSocket URL.
172 **`options`** *Optional*
173 - An `Object` specifying extra details about how the connection
179 - A `boolean` indicating if the remote server should be shared or
180 if any other connected clients should be disconnected. Enabled
184 - An `Object` specifying the credentials to provide to the server
185 when authenticating. The following credentials are possible:
187 | name | type | description
188 | ------------ | ----------- | -----------
189 | `"username"` | `DOMString` | The user that authenticates
190 | `"password"` | `DOMString` | Password for the user
191 | `"target"` | `DOMString` | Target machine or session
194 - A `DOMString` specifying the ID to provide to any VNC repeater
198 - An `Array` of `DOMString`s specifying the sub-protocols to use
199 in the WebSocket connection. Empty by default.
203 The `connect` event is fired after all the handshaking with the server
204 is completed and the connection is fully established. After this event
205 the `RFB` object is ready to recieve graphics updates and to send input.
209 The `disconnect` event is fired when the connection has been
210 terminated. The `detail` property is an `Object` that contains the
211 property `clean`. `clean` is a `boolean` indicating if the termination
212 was clean or not. In the event of an unexpected termination or an error
213 `clean` will be set to false.
215 #### credentialsrequired
217 The `credentialsrequired` event is fired when the server requests more
218 credentials than were specified to [`RFB()`](#rfb-1). The `detail`
219 property is an `Object` containing the property `types` which is an
220 `Array` of `DOMString` listing the credentials that are required.
224 The `securityfailure` event is fired when the handshaking process with
225 the server fails during the security negotiation step. The `detail`
226 property is an `Object` containing the following properties:
228 | Property | Type | Description
229 | -------- | ----------- | -----------
230 | `status` | `long` | The failure status code
231 | `reason` | `DOMString` | The **optional** reason for the failure
233 The property `status` corresponds to the
234 [SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult)
235 status code in cases of failure. A status of zero will not be sent in
236 this event since that indicates a successful security handshaking
237 process. The optional property `reason` is provided by the server and
238 thus the language of the string is not known. However most servers will
239 probably send English strings. The server can choose to not send a
240 reason and in these cases the `reason` property will be omitted.
244 The `clipboard` event is fired when the server has sent clipboard data.
245 The `detail` property is an `Object` containing the property `text`
246 which is a `DOMString` with the clipboard data.
250 The `bell` event is fired when the server has requested an audible
255 The `desktopname` event is fired when the name of the remote desktop
256 changes. The `detail` property is an `Object` with the property `name`
257 which is a `DOMString` specifying the new name.
261 The `capabilities` event is fired whenever an entry is added or removed
262 from `RFB.capabilities`. The `detail` property is an `Object` with the
263 property `capabilities` containing the new value of `RFB.capabilities`.
265 #### RFB.disconnect()
267 The `RFB.disconnect()` method is used to disconnect from the currently
274 #### RFB.sendCredentials()
276 The `RFB.sendCredentials()` method is used to provide the missing
277 credentials after a `credentialsrequired` event has been fired.
281 RFB.sendCredentials( credentials );
286 - An `Object` specifying the credentials to provide to the server
287 when authenticating. See [`RFB()`](#rfb-1) for details.
291 The `RFB.sendKey()` method is used to send a key event to the server.
295 RFB.sendKey( keysym, code [, down] );
300 - A `long` specifying the RFB keysym to send. Can be `0` if a valid
301 **`code`** is specified.
304 - A `DOMString` specifying the physical key to send. Valid values are
305 those that can be specified to
306 [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
307 If the physical key cannot be determined then `null` shall be
310 **`down`** *Optional*
311 - A `boolean` specifying if a press or a release event should be
312 sent. If omitted then both a press and release event are sent.
314 #### RFB.sendCtrlAltDel()
316 The `RFB.sendCtrlAltDel()` method is used to send the key sequence
317 *left Control*, *left Alt*, *Delete*. This is a convenience wrapper
318 around [`RFB.sendKey()`](#rfbsendkey).
322 RFB.sendCtrlAltDel( );
326 The `RFB.focus()` method sets the keyboard focus on the remote session.
327 Keyboard events will be sent to the remote server after this point.
335 The `RFB.blur()` method remove keyboard focus on the remote session.
336 Keyboard events will no longer be sent to the remote server after this
343 #### RFB.machineShutdown()
345 The `RFB.machineShutdown()` method is used to request to shut down the
346 remote machine. The capability `power` must be set for this method to
351 RFB.machineShutdown( );
353 #### RFB.machineReboot()
355 The `RFB.machineReboot()` method is used to request a clean reboot of
356 the remote machine. The capability `power` must be set for this method
361 RFB.machineReboot( );
363 #### RFB.machineReset()
365 The `RFB.machineReset()` method is used to request a forced reset of
366 the remote machine. The capability `power` must be set for this method
373 #### RFB.clipboardPasteFrom()
375 The `RFB.clipboardPasteFrom()` method is used to send clipboard data
376 to the remote server.
380 RFB.clipboardPasteFrom( text );
385 - A `DOMString` specifying the clipboard data to send.