]>
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 | |
26 | moved to the canvas when a `mousedown` or `touchstart` event is | |
27 | 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 | `viewportScale` |
4f90c1d3 PO |
36 | - Is a `double` indicating how the framebuffer contents should be |
37 | scaled before being rendered on to the canvas. See also | |
38 | [`RFB.autoscale()`](#rfbautoscale). Is set to `1.0` by default. | |
5ce91550 | 39 | |
0460e5fd | 40 | `clipViewport` |
4f90c1d3 PO |
41 | - Is a `boolean` indicating if the canvas should be clipped to its |
42 | container. When disabled the container must be able to handle the | |
43 | resulting overflow. Disabled by default. | |
5ce91550 | 44 | |
0460e5fd | 45 | `dragViewport` |
4f90c1d3 | 46 | - Is a `boolean` indicating if mouse events should control the |
0460e5fd PO |
47 | relative position of a clipped canvas. Only relevant if |
48 | `clipViewport` is enabled. Disabled by default. | |
5ce91550 | 49 | |
a80aa416 PO |
50 | `isClipped` *Read only* |
51 | - Is a `boolean` indicating if the framebuffer is larger than the | |
52 | current canvas, i.e. it is being clipped. | |
5ce91550 | 53 | |
4f90c1d3 PO |
54 | `capabilities` *Read only* |
55 | - Is an `Object` indicating which optional extensions are available | |
56 | on the server. Some methods may only be called if the corresponding | |
57 | capability is set. The following capabilities are defined: | |
5ce91550 | 58 | |
4f90c1d3 PO |
59 | | name | type | description |
60 | | -------- | --------- | ----------- | |
61 | | `power` | `boolean` | Machine power control is available | |
62 | | `resize` | `boolean` | The framebuffer can be resized | |
5ce91550 | 63 | |
e89eef94 | 64 | ### Events |
5ce91550 | 65 | |
e89eef94 PO |
66 | [`updatestate`](#updatestate) |
67 | - The `updatestate` event is fired when the connection state of the | |
68 | `RFB` object changes. | |
5ce91550 | 69 | |
e89eef94 PO |
70 | [`disconnect`](#disconnected) |
71 | - The `disconnect` event is fired when the `RFB` object disconnects. | |
5ce91550 | 72 | |
e89eef94 PO |
73 | [`credentialsrequired`](#credentialsrequired) |
74 | - The `credentialsrequired` event is fired when more credentials must | |
75 | be given to continue. | |
5ce91550 | 76 | |
e89eef94 PO |
77 | [`clipboard`](#clipboard) |
78 | - The `clipboard` event is fired when clipboard data is received from | |
79 | the server. | |
5ce91550 | 80 | |
e89eef94 PO |
81 | [`bell`](#bell) |
82 | - The `bell` event is fired when a audible bell request is received | |
4f90c1d3 | 83 | from the server. |
f5d40c6a | 84 | |
e89eef94 PO |
85 | [`fbresize`](#fbresize) |
86 | - The `fbresize` event is fired when the framebuffer size is changed. | |
f5d40c6a | 87 | |
e89eef94 PO |
88 | [`desktopname`](#desktopname) |
89 | - The `desktopname` event is fired when the remote desktop name | |
90 | changes. | |
f5d40c6a | 91 | |
e89eef94 PO |
92 | [`capabilities`](#capabilities) |
93 | - The `capabilities` event is fired when `RFB.capabilities` is | |
94 | updated. | |
f5d40c6a | 95 | |
4f90c1d3 | 96 | ### Methods |
f5d40c6a | 97 | |
4f90c1d3 PO |
98 | [`RFB.disconnect()`](#rfbdisconnect) |
99 | - Disconnect from the server. | |
5ce91550 | 100 | |
4f90c1d3 | 101 | [`RFB.sendCredentials()`](#rfbsendcredentials) |
e89eef94 PO |
102 | - Send credentials to server. Should be called after the |
103 | [`credentialsrequired`](#credentialsrequired) event has fired. | |
5ce91550 | 104 | |
4f90c1d3 PO |
105 | [`RFB.sendKey()`](#rfbsendKey) |
106 | - Send a key event. | |
5ce91550 | 107 | |
4f90c1d3 PO |
108 | [`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel) |
109 | - Send Ctrl-Alt-Del key sequence. | |
110 | ||
111 | [`RFB.machineShutdown()`](#rfbmachineshutdown) | |
112 | - Request a shutdown of the remote machine. | |
113 | ||
114 | [`RFB.machineReboot()`](#rfbmachinereboot) | |
115 | - Request a reboot of the remote machine. | |
116 | ||
117 | [`RFB.machineReset()`](#rfbmachinereset) | |
118 | - Request a reset of the remote machine. | |
119 | ||
120 | [`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom) | |
121 | - Send clipboard contents to server. | |
122 | ||
123 | [`RFB.autoscale()`](#rfbautoscale) | |
0460e5fd PO |
124 | - Set `RFB.viewportScale` so that the framebuffer fits a specified |
125 | container. | |
4f90c1d3 | 126 | |
4f90c1d3 PO |
127 | [`RFB.requestDesktopSize()`](#rfbrequestDesktopSize) |
128 | - Send a request to change the remote desktop size. | |
129 | ||
130 | [`RFB.viewportChangeSize()`](#rfbviewportChangeSize) | |
131 | - Change size of the viewport. | |
132 | ||
133 | ### Details | |
134 | ||
135 | #### RFB() | |
136 | ||
2f4516f2 PO |
137 | The `RFB()` constructor returns a new `RFB` object and initiates a new |
138 | connection to a specified VNC server. | |
4f90c1d3 PO |
139 | |
140 | ##### Syntax | |
141 | ||
2f4516f2 | 142 | var rfb = new RFB( target, url [, options] ); |
4f90c1d3 PO |
143 | |
144 | ###### Parameters | |
145 | ||
146 | **`target`** | |
147 | - A [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | |
148 | that specifies where graphics should be rendered and input events | |
149 | should be monitored. | |
150 | ||
2f4516f2 PO |
151 | **`url`** |
152 | - A `DOMString` specifying the VNC server to connect to. This must be | |
153 | a valid WebSocket URL. | |
154 | ||
155 | **`options`** *Optional* | |
156 | - An `Object` specifying extra details about how the connection | |
157 | should be made. | |
158 | ||
159 | Possible options: | |
160 | ||
161 | `shared` | |
162 | - A `boolean` indicating if the remote server should be shared or | |
163 | if any other connected clients should be disconnected. Enabled | |
164 | by default. | |
165 | ||
166 | `credentials` | |
167 | - An `Object` specifying the credentials to provide to the server | |
168 | when authenticating. The following credentials are possible: | |
169 | ||
170 | | name | type | description | |
171 | | ------------ | ----------- | ----------- | |
172 | | `"username"` | `DOMString` | The user that authenticates | |
173 | | `"password"` | `DOMString` | Password for the user | |
174 | | `"target"` | `DOMString` | Target machine or session | |
175 | ||
176 | `repeaterID` | |
177 | - A `DOMString` specifying the ID to provide to any VNC repeater | |
178 | encountered. | |
179 | ||
e89eef94 | 180 | #### updatestate |
4f90c1d3 | 181 | |
e89eef94 PO |
182 | The `updatestate` event is fired after the noVNC connection state |
183 | changes. The `detail` property is an `Object` containg the property | |
184 | `state` with the new connection state. | |
185 | ||
186 | Here is a list of the states that are reported: | |
4f90c1d3 PO |
187 | |
188 | | connection state | description | |
189 | | ----------------- | ------------ | |
190 | | `"connecting"` | starting to connect | |
191 | | `"connected"` | connected normally | |
192 | | `"disconnecting"` | starting to disconnect | |
193 | | `"disconnected"` | disconnected | |
194 | ||
195 | Note that a `RFB` objects can not transition from the disconnected | |
196 | state in any way, a new instance of the object has to be created for | |
197 | new connections. | |
198 | ||
e89eef94 | 199 | #### disconnect |
4f90c1d3 | 200 | |
e89eef94 PO |
201 | The `disconnect` event is fired when the connection has been |
202 | terminated. The `detail` property is an `Object` the optionally | |
203 | contains the property `reason`. `reason` is a `DOMString` specifying | |
204 | the reason in the event of an unexpected termination. `reason` will be | |
205 | omitted for a clean termination. | |
4f90c1d3 | 206 | |
e89eef94 | 207 | #### credentialsrequired |
4f90c1d3 | 208 | |
e89eef94 PO |
209 | The `credentialsrequired` event is fired when the server requests more |
210 | credentials than were specified to [`RFB()`](#rfb-1). The `detail` | |
211 | property is an `Object` containing the property `types` which is an | |
212 | `Array` of `DOMString` listing the credentials that are required. | |
4f90c1d3 | 213 | |
e89eef94 | 214 | #### clipboard |
4f90c1d3 | 215 | |
e89eef94 PO |
216 | The `clipboard` event is fired when the server has sent clipboard data. |
217 | The `detail` property is an `Object` containing the property `text` | |
218 | which is a `DOMString` with the clipboard data. | |
4f90c1d3 | 219 | |
e89eef94 | 220 | #### bell |
4f90c1d3 | 221 | |
e89eef94 PO |
222 | The `bell` event is fired when the server has requested an audible |
223 | bell. | |
4f90c1d3 | 224 | |
e89eef94 | 225 | #### fbresize |
4f90c1d3 | 226 | |
e89eef94 PO |
227 | The `fbresize` event is fired when the framebuffer has changed |
228 | dimensions. The `detail` property is an `Object` with the properties | |
229 | `width` and `height` specifying the new dimensions. | |
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 | ||
302 | #### RFB.machineShutdown() | |
303 | ||
304 | The `RFB.machineShutdown()` method is used to request to shut down the | |
305 | remote machine. The capability `power` must be set for this method to | |
306 | have any effect. | |
307 | ||
308 | ##### Syntax | |
309 | ||
310 | RFB.machineShutdown( ); | |
311 | ||
312 | #### RFB.machineReboot() | |
313 | ||
314 | The `RFB.machineReboot()` method is used to request a clean reboot of | |
315 | the remote machine. The capability `power` must be set for this method | |
316 | to have any effect. | |
317 | ||
318 | ##### Syntax | |
319 | ||
320 | RFB.machineReboot( ); | |
321 | ||
322 | #### RFB.machineReset() | |
323 | ||
324 | The `RFB.machineReset()` method is used to request a forced reset of | |
325 | the remote machine. The capability `power` must be set for this method | |
326 | to have any effect. | |
327 | ||
328 | ##### Syntax | |
329 | ||
330 | RFB.machineReset( ); | |
331 | ||
332 | #### RFB.clipboardPasteFrom() | |
333 | ||
334 | The `RFB.clipboardPasteFrom()` method is used to send clipboard data | |
335 | to the remote server. | |
336 | ||
337 | ##### Syntax | |
338 | ||
339 | RFB.clipboardPasteFrom( text ); | |
340 | ||
341 | ###### Parameters | |
342 | ||
343 | **`text`** | |
344 | - A `DOMString` specifying the clipboard data to send. Currently only | |
345 | characters from ISO 8859-1 are supported. | |
346 | ||
347 | #### RFB.autoscale() | |
348 | ||
349 | The `RFB.autoscale()` method is used to automatically adjust | |
0460e5fd | 350 | `RFB.viewportScale` to fit given dimensions. |
4f90c1d3 PO |
351 | |
352 | ##### Syntax | |
353 | ||
002907d2 | 354 | RFB.autoscale( width, height ); |
4f90c1d3 PO |
355 | |
356 | ###### Parameters | |
357 | ||
358 | **`width`** | |
359 | - A `long` specifying the maximum width of the canvas in CSS pixels. | |
360 | ||
361 | **`height`** | |
362 | - A `long` specifying the maximum height of the canvas in CSS pixels. | |
363 | ||
4f90c1d3 PO |
364 | #### RFB.requestDesktopSize() |
365 | ||
366 | The `RFB.requestDesktopSize()` method is used to request a change of | |
367 | the framebuffer. The capability `resize` must be set for this method to | |
368 | have any effect. | |
369 | ||
370 | Note that this is merely a request and the server may deny it. | |
e89eef94 | 371 | The [`fbresize`](#fbresize) event will be fired when the framebuffer |
4f90c1d3 PO |
372 | actually changes dimensions. |
373 | ||
374 | ##### Syntax | |
375 | ||
376 | RFB.requestDesktopSize( width, height ); | |
377 | ||
378 | ###### Parameters | |
379 | ||
380 | **`width`** | |
381 | - A `long` specifying the new requested width in CSS pixels. | |
382 | ||
383 | **`height`** | |
384 | - A `long` specifying the new requested height in CSS pixels. | |
385 | ||
386 | #### RFB.viewportChangeSize() | |
387 | ||
388 | The `RFB.viewportChangeSize()` method is used to change the size of the | |
389 | canvas rather than the underlying framebuffer. | |
390 | ||
0460e5fd | 391 | This method has no effect if `RFB.clipViewport` is set to `false`. |
4f90c1d3 PO |
392 | |
393 | ##### Syntax | |
394 | ||
395 | RFB.viewportChangeSize( width, height ); | |
396 | ||
397 | ###### Parameters | |
398 | ||
399 | **`width`** | |
400 | - A `long` specifying the new width in CSS pixels. | |
401 | ||
402 | **`height`** | |
403 | - A `long` specifying the new height in CSS pixels. |