]>
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 PO |
26 | moved to the remote session when a `mousedown` or `touchstart` |
27 | event is received. | |
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 | |
4f90c1d3 PO |
56 | `capabilities` *Read only* |
57 | - Is an `Object` indicating which optional extensions are available | |
58 | on the server. Some methods may only be called if the corresponding | |
59 | capability is set. The following capabilities are defined: | |
5ce91550 | 60 | |
4f90c1d3 PO |
61 | | name | type | description |
62 | | -------- | --------- | ----------- | |
63 | | `power` | `boolean` | Machine power control is available | |
5ce91550 | 64 | |
e89eef94 | 65 | ### Events |
5ce91550 | 66 | |
ee5cae9f SM |
67 | [`connect`](#connect) |
68 | - The `connect` event is fired when the `RFB` object has completed | |
69 | the connection and handshaking with the server. | |
5ce91550 | 70 | |
e89eef94 PO |
71 | [`disconnect`](#disconnected) |
72 | - The `disconnect` event is fired when the `RFB` object disconnects. | |
5ce91550 | 73 | |
e89eef94 PO |
74 | [`credentialsrequired`](#credentialsrequired) |
75 | - The `credentialsrequired` event is fired when more credentials must | |
76 | be given to continue. | |
5ce91550 | 77 | |
d472f3f1 SM |
78 | [`securityfailure`](#securityfailure) |
79 | - The `securityfailure` event is fired when the security negotiation | |
80 | with the server fails. | |
81 | ||
e89eef94 PO |
82 | [`clipboard`](#clipboard) |
83 | - The `clipboard` event is fired when clipboard data is received from | |
84 | the server. | |
5ce91550 | 85 | |
e89eef94 PO |
86 | [`bell`](#bell) |
87 | - The `bell` event is fired when a audible bell request is received | |
4f90c1d3 | 88 | from the server. |
f5d40c6a | 89 | |
e89eef94 PO |
90 | [`desktopname`](#desktopname) |
91 | - The `desktopname` event is fired when the remote desktop name | |
92 | changes. | |
f5d40c6a | 93 | |
e89eef94 PO |
94 | [`capabilities`](#capabilities) |
95 | - The `capabilities` event is fired when `RFB.capabilities` is | |
96 | updated. | |
f5d40c6a | 97 | |
4f90c1d3 | 98 | ### Methods |
f5d40c6a | 99 | |
4f90c1d3 PO |
100 | [`RFB.disconnect()`](#rfbdisconnect) |
101 | - Disconnect from the server. | |
5ce91550 | 102 | |
4f90c1d3 | 103 | [`RFB.sendCredentials()`](#rfbsendcredentials) |
e89eef94 PO |
104 | - Send credentials to server. Should be called after the |
105 | [`credentialsrequired`](#credentialsrequired) event has fired. | |
5ce91550 | 106 | |
4f90c1d3 PO |
107 | [`RFB.sendKey()`](#rfbsendKey) |
108 | - Send a key event. | |
5ce91550 | 109 | |
4f90c1d3 PO |
110 | [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) |
111 | - Send Ctrl-Alt-Del key sequence. | |
112 | ||
9b84f516 PO |
113 | [`RFB.focus()`](#rfbfocus) |
114 | - Move keyboard focus to the remote session. | |
115 | ||
116 | [`RFB.blur()`](#rfbblur) | |
117 | - Remove keyboard focus from the remote session. | |
118 | ||
4f90c1d3 PO |
119 | [`RFB.machineShutdown()`](#rfbmachineshutdown) |
120 | - Request a shutdown of the remote machine. | |
121 | ||
122 | [`RFB.machineReboot()`](#rfbmachinereboot) | |
123 | - Request a reboot of the remote machine. | |
124 | ||
125 | [`RFB.machineReset()`](#rfbmachinereset) | |
126 | - Request a reset of the remote machine. | |
127 | ||
128 | [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom) | |
129 | - Send clipboard contents to server. | |
130 | ||
4f90c1d3 PO |
131 | ### Details |
132 | ||
133 | #### RFB() | |
134 | ||
2f4516f2 PO |
135 | The `RFB()` constructor returns a new `RFB` object and initiates a new |
136 | connection to a specified VNC server. | |
4f90c1d3 PO |
137 | |
138 | ##### Syntax | |
139 | ||
2f4516f2 | 140 | var rfb = new RFB( target, url [, options] ); |
4f90c1d3 PO |
141 | |
142 | ###### Parameters | |
143 | ||
144 | **`target`** | |
9b84f516 PO |
145 | - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) |
146 | that specifies where the `RFB` object should attach itself. The | |
147 | existing contents of the `HTMLElement` will be untouched, but new | |
148 | elements will be added during the lifetime of the `RFB` object. | |
4f90c1d3 | 149 | |
2f4516f2 PO |
150 | **`url`** |
151 | - A `DOMString` specifying the VNC server to connect to. This must be | |
152 | a valid WebSocket URL. | |
153 | ||
154 | **`options`** *Optional* | |
155 | - An `Object` specifying extra details about how the connection | |
156 | should be made. | |
157 | ||
158 | Possible options: | |
159 | ||
160 | `shared` | |
161 | - A `boolean` indicating if the remote server should be shared or | |
162 | if any other connected clients should be disconnected. Enabled | |
163 | by default. | |
164 | ||
165 | `credentials` | |
166 | - An `Object` specifying the credentials to provide to the server | |
167 | when authenticating. The following credentials are possible: | |
168 | ||
169 | | name | type | description | |
170 | | ------------ | ----------- | ----------- | |
171 | | `"username"` | `DOMString` | The user that authenticates | |
172 | | `"password"` | `DOMString` | Password for the user | |
173 | | `"target"` | `DOMString` | Target machine or session | |
174 | ||
175 | `repeaterID` | |
176 | - A `DOMString` specifying the ID to provide to any VNC repeater | |
177 | encountered. | |
178 | ||
ee5cae9f | 179 | #### connect |
4f90c1d3 | 180 | |
ee5cae9f SM |
181 | The `connect` event is fired after all the handshaking with the server |
182 | is completed and the connection is fully established. After this event | |
183 | the `RFB` object is ready to recieve graphics updates and to send input. | |
4f90c1d3 | 184 | |
e89eef94 | 185 | #### disconnect |
4f90c1d3 | 186 | |
e89eef94 | 187 | The `disconnect` event is fired when the connection has been |
d472f3f1 SM |
188 | terminated. The `detail` property is an `Object` that contains the |
189 | property `clean`. `clean` is a `boolean` indicating if the termination | |
190 | was clean or not. In the event of an unexpected termination or an error | |
191 | `clean` will be set to false. | |
4f90c1d3 | 192 | |
e89eef94 | 193 | #### credentialsrequired |
4f90c1d3 | 194 | |
e89eef94 PO |
195 | The `credentialsrequired` event is fired when the server requests more |
196 | credentials than were specified to [`RFB()`](#rfb-1). The `detail` | |
197 | property is an `Object` containing the property `types` which is an | |
198 | `Array` of `DOMString` listing the credentials that are required. | |
4f90c1d3 | 199 | |
d472f3f1 SM |
200 | #### securityfailure |
201 | ||
202 | The `securityfailure` event is fired when the handshaking process with | |
203 | the server fails during the security negotiation step. The `detail` | |
204 | property is an `Object` containing the following properties: | |
205 | ||
206 | | Property | Type | Description | |
207 | | -------- | ----------- | ----------- | |
208 | | `status` | `long` | The failure status code | |
209 | | `reason` | `DOMString` | The **optional** reason for the failure | |
210 | ||
211 | The property `status` corresponds to the | |
212 | [SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult) | |
213 | status code in cases of failure. A status of zero will not be sent in | |
214 | this event since that indicates a successful security handshaking | |
215 | process. The optional property `reason` is provided by the server and | |
216 | thus the language of the string is not known. However most servers will | |
217 | probably send English strings. The server can choose to not send a | |
218 | reason and in these cases the `reason` property will be omitted. | |
219 | ||
e89eef94 | 220 | #### clipboard |
4f90c1d3 | 221 | |
e89eef94 PO |
222 | The `clipboard` event is fired when the server has sent clipboard data. |
223 | The `detail` property is an `Object` containing the property `text` | |
224 | which is a `DOMString` with the clipboard data. | |
4f90c1d3 | 225 | |
e89eef94 | 226 | #### bell |
4f90c1d3 | 227 | |
e89eef94 PO |
228 | The `bell` event is fired when the server has requested an audible |
229 | bell. | |
4f90c1d3 | 230 | |
e89eef94 | 231 | #### desktopname |
4f90c1d3 | 232 | |
e89eef94 PO |
233 | The `desktopname` event is fired when the name of the remote desktop |
234 | changes. The `detail` property is an `Object` with the property `name` | |
235 | which is a `DOMString` specifying the new name. | |
4f90c1d3 | 236 | |
e89eef94 | 237 | #### capabilities |
4f90c1d3 | 238 | |
e89eef94 PO |
239 | The `capabilities` event is fired whenever an entry is added or removed |
240 | from `RFB.capabilities`. The `detail` property is an `Object` with the | |
241 | property `capabilities` containing the new value of `RFB.capabilities`. | |
4f90c1d3 | 242 | |
4f90c1d3 PO |
243 | #### RFB.disconnect() |
244 | ||
245 | The `RFB.disconnect()` method is used to disconnect from the currently | |
246 | connected server. | |
247 | ||
248 | ##### Syntax | |
249 | ||
250 | RFB.disconnect( ); | |
251 | ||
252 | #### RFB.sendCredentials() | |
253 | ||
254 | The `RFB.sendCredentials()` method is used to provide the missing | |
e89eef94 | 255 | credentials after a `credentialsrequired` event has been fired. |
4f90c1d3 PO |
256 | |
257 | ##### Syntax | |
258 | ||
259 | RFB.sendCredentials( credentials ); | |
260 | ||
261 | ###### Parameters | |
262 | ||
263 | **`credentials`** | |
264 | - An `Object` specifying the credentials to provide to the server | |
2f4516f2 | 265 | when authenticating. See [`RFB()`](#rfb-1) for details. |
4f90c1d3 PO |
266 | |
267 | #### RFB.sendKey() | |
268 | ||
269 | The `RFB.sendKey()` method is used to send a key event to the server. | |
270 | ||
271 | ##### Syntax | |
272 | ||
273 | RFB.sendKey( keysym, code [, down] ); | |
274 | ||
275 | ###### Parameters | |
276 | ||
277 | **`keysym`** | |
278 | - A `long` specifying the RFB keysym to send. Can be `0` if a valid | |
279 | **`code`** is specified. | |
280 | ||
281 | **`code`** | |
282 | - A `DOMString` specifying the physical key to send. Valid values are | |
283 | those that can be specified to | |
284 | [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code). | |
285 | If the physical key cannot be determined then `null` shall be | |
286 | specified. | |
287 | ||
288 | **`down`** *Optional* | |
289 | - A `boolean` specifying if a press or a release event should be | |
290 | sent. If omitted then both a press and release event are sent. | |
291 | ||
292 | #### RFB.sendCtrlAltDel() | |
293 | ||
294 | The `RFB.sendCtrlAltDel()` method is used to send the key sequence | |
295 | *left Control*, *left Alt*, *Delete*. This is a convenience wrapper | |
296 | around [`RFB.sendKey()`](#rfbsendkey). | |
297 | ||
298 | ##### Syntax | |
299 | ||
300 | RFB.sendCtrlAltDel( ); | |
301 | ||
9b84f516 PO |
302 | #### RFB.focus() |
303 | ||
304 | The `RFB.focus()` method sets the keyboard focus on the remote session. | |
305 | Keyboard events will be sent to the remote server after this point. | |
306 | ||
307 | ##### Syntax | |
308 | ||
309 | RFB.focus( ); | |
310 | ||
311 | #### RFB.blur() | |
312 | ||
313 | The `RFB.blur()` method remove keyboard focus on the remote session. | |
314 | Keyboard events will no longer be sent to the remote server after this | |
315 | point. | |
316 | ||
317 | ##### Syntax | |
318 | ||
319 | RFB.blur( ); | |
320 | ||
4f90c1d3 PO |
321 | #### RFB.machineShutdown() |
322 | ||
323 | The `RFB.machineShutdown()` method is used to request to shut down the | |
324 | remote machine. The capability `power` must be set for this method to | |
325 | have any effect. | |
326 | ||
327 | ##### Syntax | |
328 | ||
329 | RFB.machineShutdown( ); | |
330 | ||
331 | #### RFB.machineReboot() | |
332 | ||
333 | The `RFB.machineReboot()` method is used to request a clean reboot of | |
334 | the remote machine. The capability `power` must be set for this method | |
335 | to have any effect. | |
336 | ||
337 | ##### Syntax | |
338 | ||
339 | RFB.machineReboot( ); | |
340 | ||
341 | #### RFB.machineReset() | |
342 | ||
343 | The `RFB.machineReset()` method is used to request a forced reset of | |
344 | the remote machine. The capability `power` must be set for this method | |
345 | to have any effect. | |
346 | ||
347 | ##### Syntax | |
348 | ||
349 | RFB.machineReset( ); | |
350 | ||
351 | #### RFB.clipboardPasteFrom() | |
352 | ||
353 | The `RFB.clipboardPasteFrom()` method is used to send clipboard data | |
354 | to the remote server. | |
355 | ||
356 | ##### Syntax | |
357 | ||
358 | RFB.clipboardPasteFrom( text ); | |
359 | ||
360 | ###### Parameters | |
361 | ||
362 | **`text`** | |
363 | - A `DOMString` specifying the clipboard data to send. Currently only | |
364 | characters from ISO 8859-1 are supported. |