]>
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 | |
0460e5fd | 29 | `clipViewport` |
9b84f516 PO |
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. | |
5ce91550 | 33 | |
0460e5fd | 34 | `dragViewport` |
4f90c1d3 | 35 | - Is a `boolean` indicating if mouse events should control the |
9b84f516 | 36 | relative position of a clipped remote session. Only relevant if |
0460e5fd | 37 | `clipViewport` is enabled. Disabled by default. |
5ce91550 | 38 | |
9b84f516 PO |
39 | `scaleViewport` |
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. | |
44 | ||
45 | `resizeSession` | |
46 | - Is a `boolean` indicating if a request to resize the remote session | |
47 | should be sent whenever the container changes dimensions. Disabled | |
48 | by default. | |
5ce91550 | 49 | |
4c38179d AP |
50 | `showDotCursor` |
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. | |
54 | ||
d7791ebb MM |
55 | `background` |
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)` | |
59 | (solid gray color). | |
60 | ||
efd1f8a4 AT |
61 | `qualityLevel` |
62 | - Is an `int` in range `[0-9]` controlling the desired JPEG quality. | |
63 | Value `0` implies low quality and `9` implies high quality. | |
64 | Default value is `6`. | |
65 | ||
479d8cef SM |
66 | `compressionLevel` |
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. | |
72 | Default value is `2`. | |
73 | ||
4f90c1d3 PO |
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: | |
5ce91550 | 78 | |
4f90c1d3 PO |
79 | | name | type | description |
80 | | -------- | --------- | ----------- | |
81 | | `power` | `boolean` | Machine power control is available | |
5ce91550 | 82 | |
e89eef94 | 83 | ### Events |
5ce91550 | 84 | |
ee5cae9f SM |
85 | [`connect`](#connect) |
86 | - The `connect` event is fired when the `RFB` object has completed | |
87 | the connection and handshaking with the server. | |
5ce91550 | 88 | |
e89eef94 PO |
89 | [`disconnect`](#disconnected) |
90 | - The `disconnect` event is fired when the `RFB` object disconnects. | |
5ce91550 | 91 | |
e89eef94 PO |
92 | [`credentialsrequired`](#credentialsrequired) |
93 | - The `credentialsrequired` event is fired when more credentials must | |
94 | be given to continue. | |
5ce91550 | 95 | |
d472f3f1 SM |
96 | [`securityfailure`](#securityfailure) |
97 | - The `securityfailure` event is fired when the security negotiation | |
98 | with the server fails. | |
99 | ||
e89eef94 PO |
100 | [`clipboard`](#clipboard) |
101 | - The `clipboard` event is fired when clipboard data is received from | |
102 | the server. | |
5ce91550 | 103 | |
e89eef94 PO |
104 | [`bell`](#bell) |
105 | - The `bell` event is fired when a audible bell request is received | |
4f90c1d3 | 106 | from the server. |
f5d40c6a | 107 | |
e89eef94 PO |
108 | [`desktopname`](#desktopname) |
109 | - The `desktopname` event is fired when the remote desktop name | |
110 | changes. | |
f5d40c6a | 111 | |
e89eef94 PO |
112 | [`capabilities`](#capabilities) |
113 | - The `capabilities` event is fired when `RFB.capabilities` is | |
114 | updated. | |
f5d40c6a | 115 | |
4f90c1d3 | 116 | ### Methods |
f5d40c6a | 117 | |
4f90c1d3 PO |
118 | [`RFB.disconnect()`](#rfbdisconnect) |
119 | - Disconnect from the server. | |
5ce91550 | 120 | |
4f90c1d3 | 121 | [`RFB.sendCredentials()`](#rfbsendcredentials) |
e89eef94 PO |
122 | - Send credentials to server. Should be called after the |
123 | [`credentialsrequired`](#credentialsrequired) event has fired. | |
5ce91550 | 124 | |
4f90c1d3 PO |
125 | [`RFB.sendKey()`](#rfbsendKey) |
126 | - Send a key event. | |
5ce91550 | 127 | |
4f90c1d3 PO |
128 | [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) |
129 | - Send Ctrl-Alt-Del key sequence. | |
130 | ||
9b84f516 PO |
131 | [`RFB.focus()`](#rfbfocus) |
132 | - Move keyboard focus to the remote session. | |
133 | ||
134 | [`RFB.blur()`](#rfbblur) | |
135 | - Remove keyboard focus from the remote session. | |
136 | ||
4f90c1d3 PO |
137 | [`RFB.machineShutdown()`](#rfbmachineshutdown) |
138 | - Request a shutdown of the remote machine. | |
139 | ||
140 | [`RFB.machineReboot()`](#rfbmachinereboot) | |
141 | - Request a reboot of the remote machine. | |
142 | ||
143 | [`RFB.machineReset()`](#rfbmachinereset) | |
144 | - Request a reset of the remote machine. | |
145 | ||
146 | [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom) | |
147 | - Send clipboard contents to server. | |
148 | ||
4f90c1d3 PO |
149 | ### Details |
150 | ||
151 | #### RFB() | |
152 | ||
2f4516f2 PO |
153 | The `RFB()` constructor returns a new `RFB` object and initiates a new |
154 | connection to a specified VNC server. | |
4f90c1d3 PO |
155 | |
156 | ##### Syntax | |
157 | ||
2b5f94fa | 158 | let rfb = new RFB( target, url [, options] ); |
4f90c1d3 PO |
159 | |
160 | ###### Parameters | |
161 | ||
162 | **`target`** | |
9b84f516 PO |
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. | |
4f90c1d3 | 167 | |
2f4516f2 PO |
168 | **`url`** |
169 | - A `DOMString` specifying the VNC server to connect to. This must be | |
170 | a valid WebSocket URL. | |
171 | ||
172 | **`options`** *Optional* | |
173 | - An `Object` specifying extra details about how the connection | |
174 | should be made. | |
175 | ||
176 | Possible options: | |
177 | ||
178 | `shared` | |
179 | - A `boolean` indicating if the remote server should be shared or | |
180 | if any other connected clients should be disconnected. Enabled | |
181 | by default. | |
182 | ||
183 | `credentials` | |
184 | - An `Object` specifying the credentials to provide to the server | |
185 | when authenticating. The following credentials are possible: | |
186 | ||
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 | |
192 | ||
193 | `repeaterID` | |
194 | - A `DOMString` specifying the ID to provide to any VNC repeater | |
195 | encountered. | |
196 | ||
25b3d49d | 197 | `wsProtocols` |
c9122303 SM |
198 | - An `Array` of `DOMString`s specifying the sub-protocols to use |
199 | in the WebSocket connection. Empty by default. | |
25b3d49d | 200 | |
ee5cae9f | 201 | #### connect |
4f90c1d3 | 202 | |
ee5cae9f SM |
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. | |
4f90c1d3 | 206 | |
e89eef94 | 207 | #### disconnect |
4f90c1d3 | 208 | |
e89eef94 | 209 | The `disconnect` event is fired when the connection has been |
d472f3f1 SM |
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. | |
4f90c1d3 | 214 | |
e89eef94 | 215 | #### credentialsrequired |
4f90c1d3 | 216 | |
e89eef94 PO |
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. | |
4f90c1d3 | 221 | |
d472f3f1 SM |
222 | #### securityfailure |
223 | ||
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: | |
227 | ||
228 | | Property | Type | Description | |
229 | | -------- | ----------- | ----------- | |
230 | | `status` | `long` | The failure status code | |
231 | | `reason` | `DOMString` | The **optional** reason for the failure | |
232 | ||
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. | |
241 | ||
e89eef94 | 242 | #### clipboard |
4f90c1d3 | 243 | |
e89eef94 PO |
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. | |
4f90c1d3 | 247 | |
e89eef94 | 248 | #### bell |
4f90c1d3 | 249 | |
e89eef94 PO |
250 | The `bell` event is fired when the server has requested an audible |
251 | bell. | |
4f90c1d3 | 252 | |
e89eef94 | 253 | #### desktopname |
4f90c1d3 | 254 | |
e89eef94 PO |
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. | |
4f90c1d3 | 258 | |
e89eef94 | 259 | #### capabilities |
4f90c1d3 | 260 | |
e89eef94 PO |
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`. | |
4f90c1d3 | 264 | |
4f90c1d3 PO |
265 | #### RFB.disconnect() |
266 | ||
267 | The `RFB.disconnect()` method is used to disconnect from the currently | |
268 | connected server. | |
269 | ||
270 | ##### Syntax | |
271 | ||
272 | RFB.disconnect( ); | |
273 | ||
274 | #### RFB.sendCredentials() | |
275 | ||
276 | The `RFB.sendCredentials()` method is used to provide the missing | |
e89eef94 | 277 | credentials after a `credentialsrequired` event has been fired. |
4f90c1d3 PO |
278 | |
279 | ##### Syntax | |
280 | ||
281 | RFB.sendCredentials( credentials ); | |
282 | ||
283 | ###### Parameters | |
284 | ||
285 | **`credentials`** | |
286 | - An `Object` specifying the credentials to provide to the server | |
2f4516f2 | 287 | when authenticating. See [`RFB()`](#rfb-1) for details. |
4f90c1d3 PO |
288 | |
289 | #### RFB.sendKey() | |
290 | ||
291 | The `RFB.sendKey()` method is used to send a key event to the server. | |
292 | ||
293 | ##### Syntax | |
294 | ||
295 | RFB.sendKey( keysym, code [, down] ); | |
296 | ||
297 | ###### Parameters | |
298 | ||
299 | **`keysym`** | |
300 | - A `long` specifying the RFB keysym to send. Can be `0` if a valid | |
301 | **`code`** is specified. | |
302 | ||
303 | **`code`** | |
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 | |
308 | specified. | |
309 | ||
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. | |
313 | ||
314 | #### RFB.sendCtrlAltDel() | |
315 | ||
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). | |
319 | ||
320 | ##### Syntax | |
321 | ||
322 | RFB.sendCtrlAltDel( ); | |
323 | ||
9b84f516 PO |
324 | #### RFB.focus() |
325 | ||
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. | |
328 | ||
329 | ##### Syntax | |
330 | ||
331 | RFB.focus( ); | |
332 | ||
333 | #### RFB.blur() | |
334 | ||
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 | |
337 | point. | |
338 | ||
339 | ##### Syntax | |
340 | ||
341 | RFB.blur( ); | |
342 | ||
4f90c1d3 PO |
343 | #### RFB.machineShutdown() |
344 | ||
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 | |
347 | have any effect. | |
348 | ||
349 | ##### Syntax | |
350 | ||
351 | RFB.machineShutdown( ); | |
352 | ||
353 | #### RFB.machineReboot() | |
354 | ||
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 | |
357 | to have any effect. | |
358 | ||
359 | ##### Syntax | |
360 | ||
361 | RFB.machineReboot( ); | |
362 | ||
363 | #### RFB.machineReset() | |
364 | ||
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 | |
367 | to have any effect. | |
368 | ||
369 | ##### Syntax | |
370 | ||
371 | RFB.machineReset( ); | |
372 | ||
373 | #### RFB.clipboardPasteFrom() | |
374 | ||
375 | The `RFB.clipboardPasteFrom()` method is used to send clipboard data | |
376 | to the remote server. | |
377 | ||
378 | ##### Syntax | |
379 | ||
380 | RFB.clipboardPasteFrom( text ); | |
381 | ||
382 | ###### Parameters | |
383 | ||
384 | **`text`** | |
385 | - A `DOMString` specifying the clipboard data to send. Currently only | |
386 | characters from ISO 8859-1 are supported. |