]>
Commit | Line | Data |
---|---|---|
4f90c1d3 | 1 | # noVNC API |
5ce91550 | 2 | |
6929a0a1 PO |
3 | The interface of the noVNC client consists of a single RFB object that |
4 | is instantiated once per connection. | |
5ce91550 | 5 | |
4f90c1d3 | 6 | ## RFB |
5ce91550 | 7 | |
4f90c1d3 PO |
8 | The `RFB` object represents a single connection to a VNC server. It |
9 | communicates using a WebSocket that must provide a standard RFB | |
10 | protocol stream. | |
5ce91550 | 11 | |
4f90c1d3 | 12 | ### Constructor |
5ce91550 | 13 | |
4f90c1d3 PO |
14 | [`RFB()`](#rfb-1) |
15 | - Creates and returns a new `RFB` object. | |
5ce91550 | 16 | |
4f90c1d3 | 17 | ### Properties |
5ce91550 | 18 | |
4f90c1d3 PO |
19 | `viewOnly` |
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. | |
22 | Disabled by default. | |
5ce91550 | 23 | |
a201bfc5 PO |
24 | `focusOnClick` |
25 | - Is a `boolean` indicating if keyboard focus should automatically be | |
9b84f516 | 26 | moved to the remote session when a `mousedown` or `touchstart` |
27a6978e | 27 | event is received. Enabled by default. |
5ce91550 | 28 | |
4f90c1d3 PO |
29 | `touchButton` |
30 | - Is a `long` controlling the button mask that should be simulated | |
31 | when a touch event is recieved. Uses the same values as | |
32 | [`MouseEvent.button`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button). | |
33 | Is set to `1` by default. | |
5ce91550 | 34 | |
0460e5fd | 35 | `clipViewport` |
9b84f516 PO |
36 | - Is a `boolean` indicating if the remote session should be clipped |
37 | to its container. When disabled scrollbars will be shown to handle | |
38 | the resulting overflow. Disabled by default. | |
5ce91550 | 39 | |
0460e5fd | 40 | `dragViewport` |
4f90c1d3 | 41 | - Is a `boolean` indicating if mouse events should control the |
9b84f516 | 42 | relative position of a clipped remote session. Only relevant if |
0460e5fd | 43 | `clipViewport` is enabled. Disabled by default. |
5ce91550 | 44 | |
9b84f516 PO |
45 | `scaleViewport` |
46 | - Is a `boolean` indicating if the remote session should be scaled | |
47 | locally so it fits its container. When disabled it will be centered | |
48 | if the remote session is smaller than its container, or handled | |
49 | according to `clipViewport` if it is larger. Disabled by default. | |
50 | ||
51 | `resizeSession` | |
52 | - Is a `boolean` indicating if a request to resize the remote session | |
53 | should be sent whenever the container changes dimensions. Disabled | |
54 | by default. | |
5ce91550 | 55 | |
4c38179d AP |
56 | `showDotCursor` |
57 | - Is a `boolean` indicating whether a dot cursor should be shown | |
58 | instead of a zero-sized or fully-transparent cursor if the server | |
59 | sets such invisible cursor. Disabled by default. | |
60 | ||
d7791ebb MM |
61 | `background` |
62 | - Is a valid CSS [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background) | |
63 | style value indicating which background style should be applied | |
64 | to the element containing the remote session screen. The default value is `rgb(40, 40, 40)` | |
65 | (solid gray color). | |
66 | ||
efd1f8a4 AT |
67 | `qualityLevel` |
68 | - Is an `int` in range `[0-9]` controlling the desired JPEG quality. | |
69 | Value `0` implies low quality and `9` implies high quality. | |
70 | Default value is `6`. | |
71 | ||
479d8cef SM |
72 | `compressionLevel` |
73 | - Is an `int` in range `[0-9]` controlling the desired compression | |
74 | level. Value `0` means no compression. Level 1 uses a minimum of CPU | |
75 | resources and achieves weak compression ratios, while level 9 offers | |
76 | best compression but is slow in terms of CPU consumption on the server | |
77 | side. Use high levels with very slow network connections. | |
78 | Default value is `2`. | |
79 | ||
4f90c1d3 PO |
80 | `capabilities` *Read only* |
81 | - Is an `Object` indicating which optional extensions are available | |
82 | on the server. Some methods may only be called if the corresponding | |
83 | capability is set. The following capabilities are defined: | |
5ce91550 | 84 | |
4f90c1d3 PO |
85 | | name | type | description |
86 | | -------- | --------- | ----------- | |
87 | | `power` | `boolean` | Machine power control is available | |
5ce91550 | 88 | |
e89eef94 | 89 | ### Events |
5ce91550 | 90 | |
ee5cae9f SM |
91 | [`connect`](#connect) |
92 | - The `connect` event is fired when the `RFB` object has completed | |
93 | the connection and handshaking with the server. | |
5ce91550 | 94 | |
e89eef94 PO |
95 | [`disconnect`](#disconnected) |
96 | - The `disconnect` event is fired when the `RFB` object disconnects. | |
5ce91550 | 97 | |
e89eef94 PO |
98 | [`credentialsrequired`](#credentialsrequired) |
99 | - The `credentialsrequired` event is fired when more credentials must | |
100 | be given to continue. | |
5ce91550 | 101 | |
d472f3f1 SM |
102 | [`securityfailure`](#securityfailure) |
103 | - The `securityfailure` event is fired when the security negotiation | |
104 | with the server fails. | |
105 | ||
e89eef94 PO |
106 | [`clipboard`](#clipboard) |
107 | - The `clipboard` event is fired when clipboard data is received from | |
108 | the server. | |
5ce91550 | 109 | |
e89eef94 PO |
110 | [`bell`](#bell) |
111 | - The `bell` event is fired when a audible bell request is received | |
4f90c1d3 | 112 | from the server. |
f5d40c6a | 113 | |
e89eef94 PO |
114 | [`desktopname`](#desktopname) |
115 | - The `desktopname` event is fired when the remote desktop name | |
116 | changes. | |
f5d40c6a | 117 | |
e89eef94 PO |
118 | [`capabilities`](#capabilities) |
119 | - The `capabilities` event is fired when `RFB.capabilities` is | |
120 | updated. | |
f5d40c6a | 121 | |
4f90c1d3 | 122 | ### Methods |
f5d40c6a | 123 | |
4f90c1d3 PO |
124 | [`RFB.disconnect()`](#rfbdisconnect) |
125 | - Disconnect from the server. | |
5ce91550 | 126 | |
4f90c1d3 | 127 | [`RFB.sendCredentials()`](#rfbsendcredentials) |
e89eef94 PO |
128 | - Send credentials to server. Should be called after the |
129 | [`credentialsrequired`](#credentialsrequired) event has fired. | |
5ce91550 | 130 | |
4f90c1d3 PO |
131 | [`RFB.sendKey()`](#rfbsendKey) |
132 | - Send a key event. | |
5ce91550 | 133 | |
4f90c1d3 PO |
134 | [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) |
135 | - Send Ctrl-Alt-Del key sequence. | |
136 | ||
9b84f516 PO |
137 | [`RFB.focus()`](#rfbfocus) |
138 | - Move keyboard focus to the remote session. | |
139 | ||
140 | [`RFB.blur()`](#rfbblur) | |
141 | - Remove keyboard focus from the remote session. | |
142 | ||
4f90c1d3 PO |
143 | [`RFB.machineShutdown()`](#rfbmachineshutdown) |
144 | - Request a shutdown of the remote machine. | |
145 | ||
146 | [`RFB.machineReboot()`](#rfbmachinereboot) | |
147 | - Request a reboot of the remote machine. | |
148 | ||
149 | [`RFB.machineReset()`](#rfbmachinereset) | |
150 | - Request a reset of the remote machine. | |
151 | ||
152 | [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom) | |
153 | - Send clipboard contents to server. | |
154 | ||
4f90c1d3 PO |
155 | ### Details |
156 | ||
157 | #### RFB() | |
158 | ||
2f4516f2 PO |
159 | The `RFB()` constructor returns a new `RFB` object and initiates a new |
160 | connection to a specified VNC server. | |
4f90c1d3 PO |
161 | |
162 | ##### Syntax | |
163 | ||
2b5f94fa | 164 | let rfb = new RFB( target, url [, options] ); |
4f90c1d3 PO |
165 | |
166 | ###### Parameters | |
167 | ||
168 | **`target`** | |
9b84f516 PO |
169 | - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) |
170 | that specifies where the `RFB` object should attach itself. The | |
171 | existing contents of the `HTMLElement` will be untouched, but new | |
172 | elements will be added during the lifetime of the `RFB` object. | |
4f90c1d3 | 173 | |
2f4516f2 PO |
174 | **`url`** |
175 | - A `DOMString` specifying the VNC server to connect to. This must be | |
176 | a valid WebSocket URL. | |
177 | ||
178 | **`options`** *Optional* | |
179 | - An `Object` specifying extra details about how the connection | |
180 | should be made. | |
181 | ||
182 | Possible options: | |
183 | ||
184 | `shared` | |
185 | - A `boolean` indicating if the remote server should be shared or | |
186 | if any other connected clients should be disconnected. Enabled | |
187 | by default. | |
188 | ||
189 | `credentials` | |
190 | - An `Object` specifying the credentials to provide to the server | |
191 | when authenticating. The following credentials are possible: | |
192 | ||
193 | | name | type | description | |
194 | | ------------ | ----------- | ----------- | |
195 | | `"username"` | `DOMString` | The user that authenticates | |
196 | | `"password"` | `DOMString` | Password for the user | |
197 | | `"target"` | `DOMString` | Target machine or session | |
198 | ||
199 | `repeaterID` | |
200 | - A `DOMString` specifying the ID to provide to any VNC repeater | |
201 | encountered. | |
202 | ||
25b3d49d | 203 | `wsProtocols` |
c9122303 SM |
204 | - An `Array` of `DOMString`s specifying the sub-protocols to use |
205 | in the WebSocket connection. Empty by default. | |
25b3d49d | 206 | |
ee5cae9f | 207 | #### connect |
4f90c1d3 | 208 | |
ee5cae9f SM |
209 | The `connect` event is fired after all the handshaking with the server |
210 | is completed and the connection is fully established. After this event | |
211 | the `RFB` object is ready to recieve graphics updates and to send input. | |
4f90c1d3 | 212 | |
e89eef94 | 213 | #### disconnect |
4f90c1d3 | 214 | |
e89eef94 | 215 | The `disconnect` event is fired when the connection has been |
d472f3f1 SM |
216 | terminated. The `detail` property is an `Object` that contains the |
217 | property `clean`. `clean` is a `boolean` indicating if the termination | |
218 | was clean or not. In the event of an unexpected termination or an error | |
219 | `clean` will be set to false. | |
4f90c1d3 | 220 | |
e89eef94 | 221 | #### credentialsrequired |
4f90c1d3 | 222 | |
e89eef94 PO |
223 | The `credentialsrequired` event is fired when the server requests more |
224 | credentials than were specified to [`RFB()`](#rfb-1). The `detail` | |
225 | property is an `Object` containing the property `types` which is an | |
226 | `Array` of `DOMString` listing the credentials that are required. | |
4f90c1d3 | 227 | |
d472f3f1 SM |
228 | #### securityfailure |
229 | ||
230 | The `securityfailure` event is fired when the handshaking process with | |
231 | the server fails during the security negotiation step. The `detail` | |
232 | property is an `Object` containing the following properties: | |
233 | ||
234 | | Property | Type | Description | |
235 | | -------- | ----------- | ----------- | |
236 | | `status` | `long` | The failure status code | |
237 | | `reason` | `DOMString` | The **optional** reason for the failure | |
238 | ||
239 | The property `status` corresponds to the | |
240 | [SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult) | |
241 | status code in cases of failure. A status of zero will not be sent in | |
242 | this event since that indicates a successful security handshaking | |
243 | process. The optional property `reason` is provided by the server and | |
244 | thus the language of the string is not known. However most servers will | |
245 | probably send English strings. The server can choose to not send a | |
246 | reason and in these cases the `reason` property will be omitted. | |
247 | ||
e89eef94 | 248 | #### clipboard |
4f90c1d3 | 249 | |
e89eef94 PO |
250 | The `clipboard` event is fired when the server has sent clipboard data. |
251 | The `detail` property is an `Object` containing the property `text` | |
252 | which is a `DOMString` with the clipboard data. | |
4f90c1d3 | 253 | |
e89eef94 | 254 | #### bell |
4f90c1d3 | 255 | |
e89eef94 PO |
256 | The `bell` event is fired when the server has requested an audible |
257 | bell. | |
4f90c1d3 | 258 | |
e89eef94 | 259 | #### desktopname |
4f90c1d3 | 260 | |
e89eef94 PO |
261 | The `desktopname` event is fired when the name of the remote desktop |
262 | changes. The `detail` property is an `Object` with the property `name` | |
263 | which is a `DOMString` specifying the new name. | |
4f90c1d3 | 264 | |
e89eef94 | 265 | #### capabilities |
4f90c1d3 | 266 | |
e89eef94 PO |
267 | The `capabilities` event is fired whenever an entry is added or removed |
268 | from `RFB.capabilities`. The `detail` property is an `Object` with the | |
269 | property `capabilities` containing the new value of `RFB.capabilities`. | |
4f90c1d3 | 270 | |
4f90c1d3 PO |
271 | #### RFB.disconnect() |
272 | ||
273 | The `RFB.disconnect()` method is used to disconnect from the currently | |
274 | connected server. | |
275 | ||
276 | ##### Syntax | |
277 | ||
278 | RFB.disconnect( ); | |
279 | ||
280 | #### RFB.sendCredentials() | |
281 | ||
282 | The `RFB.sendCredentials()` method is used to provide the missing | |
e89eef94 | 283 | credentials after a `credentialsrequired` event has been fired. |
4f90c1d3 PO |
284 | |
285 | ##### Syntax | |
286 | ||
287 | RFB.sendCredentials( credentials ); | |
288 | ||
289 | ###### Parameters | |
290 | ||
291 | **`credentials`** | |
292 | - An `Object` specifying the credentials to provide to the server | |
2f4516f2 | 293 | when authenticating. See [`RFB()`](#rfb-1) for details. |
4f90c1d3 PO |
294 | |
295 | #### RFB.sendKey() | |
296 | ||
297 | The `RFB.sendKey()` method is used to send a key event to the server. | |
298 | ||
299 | ##### Syntax | |
300 | ||
301 | RFB.sendKey( keysym, code [, down] ); | |
302 | ||
303 | ###### Parameters | |
304 | ||
305 | **`keysym`** | |
306 | - A `long` specifying the RFB keysym to send. Can be `0` if a valid | |
307 | **`code`** is specified. | |
308 | ||
309 | **`code`** | |
310 | - A `DOMString` specifying the physical key to send. Valid values are | |
311 | those that can be specified to | |
312 | [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code). | |
313 | If the physical key cannot be determined then `null` shall be | |
314 | specified. | |
315 | ||
316 | **`down`** *Optional* | |
317 | - A `boolean` specifying if a press or a release event should be | |
318 | sent. If omitted then both a press and release event are sent. | |
319 | ||
320 | #### RFB.sendCtrlAltDel() | |
321 | ||
322 | The `RFB.sendCtrlAltDel()` method is used to send the key sequence | |
323 | *left Control*, *left Alt*, *Delete*. This is a convenience wrapper | |
324 | around [`RFB.sendKey()`](#rfbsendkey). | |
325 | ||
326 | ##### Syntax | |
327 | ||
328 | RFB.sendCtrlAltDel( ); | |
329 | ||
9b84f516 PO |
330 | #### RFB.focus() |
331 | ||
332 | The `RFB.focus()` method sets the keyboard focus on the remote session. | |
333 | Keyboard events will be sent to the remote server after this point. | |
334 | ||
335 | ##### Syntax | |
336 | ||
337 | RFB.focus( ); | |
338 | ||
339 | #### RFB.blur() | |
340 | ||
341 | The `RFB.blur()` method remove keyboard focus on the remote session. | |
342 | Keyboard events will no longer be sent to the remote server after this | |
343 | point. | |
344 | ||
345 | ##### Syntax | |
346 | ||
347 | RFB.blur( ); | |
348 | ||
4f90c1d3 PO |
349 | #### RFB.machineShutdown() |
350 | ||
351 | The `RFB.machineShutdown()` method is used to request to shut down the | |
352 | remote machine. The capability `power` must be set for this method to | |
353 | have any effect. | |
354 | ||
355 | ##### Syntax | |
356 | ||
357 | RFB.machineShutdown( ); | |
358 | ||
359 | #### RFB.machineReboot() | |
360 | ||
361 | The `RFB.machineReboot()` method is used to request a clean reboot of | |
362 | the remote machine. The capability `power` must be set for this method | |
363 | to have any effect. | |
364 | ||
365 | ##### Syntax | |
366 | ||
367 | RFB.machineReboot( ); | |
368 | ||
369 | #### RFB.machineReset() | |
370 | ||
371 | The `RFB.machineReset()` method is used to request a forced reset of | |
372 | the remote machine. The capability `power` must be set for this method | |
373 | to have any effect. | |
374 | ||
375 | ##### Syntax | |
376 | ||
377 | RFB.machineReset( ); | |
378 | ||
379 | #### RFB.clipboardPasteFrom() | |
380 | ||
381 | The `RFB.clipboardPasteFrom()` method is used to send clipboard data | |
382 | to the remote server. | |
383 | ||
384 | ##### Syntax | |
385 | ||
386 | RFB.clipboardPasteFrom( text ); | |
387 | ||
388 | ###### Parameters | |
389 | ||
390 | **`text`** | |
391 | - A `DOMString` specifying the clipboard data to send. Currently only | |
392 | characters from ISO 8859-1 are supported. |