docs/API.md

   1 # 1. Modules / API
   2
   3 The noVNC client is a composed of several modular components that handle
   4 rendering, input, networking, etc. Each of the modules is designed to
   5 be cross-browser and be useful as a standalone library in other
   6 projects (see LICENSE.txt).
   7
   8
   9 ## 1.1 Module List
  10
  11 * __Mouse__ (core/input/devices.js): Mouse input event handler with
  12 limited touch support.
  13
  14 * __Keyboard__ (core/input/devices.js): Keyboard input event handler with
  15 non-US keyboard support. Translates keyDown and keyUp events to X11
  16 keysym values.
  17
  18 * __Display__ (core/display.js): Efficient 2D rendering abstraction
  19 layered on the HTML5 canvas element.
  20
  21 * __Websock__ (core/websock.js): Websock client from websockify
  22 with transparent binary data support.
  23 [Websock API](https://github.com/kanaka/websockify/wiki/websock.js) wiki page.
  24
  25 * __RFB__ (core/rfb.js): Main class that implements the RFB
  26 protocol and stitches the other classes together.
  27
  28
  29 ## 1.2 Configuration Attributes
  30
  31 The Mouse, Keyboard, Display and RFB classes have a similar API for
  32 configuration options. Each configuration option has a default value,
  33 which can be overridden by a a configuration object passed to the
  34 constructor. Configuration options can then be read and modified after
  35 initialization with "get_*" and "set_*" methods respectively. For
  36 example, the following initializes an RFB object with the 'encrypt'
  37 configuration option enabled, then confirms it was set, then disables
  38 it.
  39
  40     var rfb = new RFB({'encrypt': true});
  41     if (rfb.get_encrypt()) {
  42         alert("Encryption is set");
  43     }
  44     rfb.set_encrypt(false);
  45
  46 Some attributes are read-only and cannot be changed. For example, the
  47 Display 'render_mode' option will throw an exception if an attempt is
  48 made to set it. The attribute mode is one of the following:
  49
  50     RO - read only
  51     RW - read write
  52     WO - write once
  53
  54
  55 ## 1.3 Methods
  56
  57 In addition to the getter and setter methods to modify configuration
  58 attributes, each of the modules has other methods that are available
  59 in the object instance. For example, the Display module has method
  60 named 'blitImage' which takes an array of pixel data and draws it to
  61 the 2D canvas.
  62
  63 ## 1.4 Callbacks
  64
  65 Each of the modules has certain events that can be hooked with
  66 callback functions. For the Mouse, Keyboard, Display and RFB classes
  67 the callback functions are assigned to configuration attributes. The
  68 WebSock module has a method named 'on' that takes two parameters: the
  69 callback event name, and the callback function.
  70
  71 ## 2. Modules
  72
  73 ## 2.1 Mouse Module
  74
  75 ### 2.1.1 Configuration Attributes
  76
  77 | name        | type | mode | default  | description
  78 | ----------- | ---- | ---- | -------- | ------------
  79 | target      | DOM  | WO   | document | DOM element that captures mouse input
  80 | focused     | bool | RW   | true     | Capture and send mouse clicks/movement
  81 | touchButton | int  | RW   | 1        | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  82
  83 ### 2.1.2 Methods
  84
  85 | name   | parameters | description
  86 | ------ | ---------- | ------------
  87 | grab   | ()         | Begin capturing mouse events
  88 | ungrab | ()         | Stop capturing mouse events
  89
  90 ### 2.1.2 Callbacks
  91
  92 | name          | parameters          | description
  93 | ------------- | ------------------- | ------------
  94 | onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
  95 | onMouseMove   | (x, y)              | Handler for mouse movement
  96
  97
  98 ## 2.2 Keyboard Module
  99
 100 ### 2.2.1 Configuration Attributes
 101
 102 | name    | type | mode | default  | description
 103 | ------- | ---- | ---- | -------- | ------------
 104 | target  | DOM  | WO   | document | DOM element that captures keyboard input
 105 | focused | bool | RW   | true     | Capture and send key events
 106
 107 ### 2.2.2 Methods
 108
 109 | name   | parameters | description
 110 | ------ | ---------- | ------------
 111 | grab   | ()         | Begin capturing keyboard events
 112 | ungrab | ()         | Stop capturing keyboard events
 113
 114 ### 2.2.3 Callbacks
 115
 116 | name       | parameters           | description
 117 | ---------- | -------------------- | ------------
 118 | onKeyPress | (keysym, code, down) | Handler for key press/release
 119
 120
 121 ## 2.3 Display Module
 122
 123 ### 2.3.1 Configuration Attributes
 124
 125 | name        | type  | mode | default | description
 126 | ----------- | ----- | ---- | ------- | ------------
 127 | target      | DOM   | WO   |         | Canvas element for rendering
 128 | context     | raw   | RO   |         | Canvas 2D context for rendering
 129 | logo        | raw   | RW   |         | Logo to display when cleared: {"width": width, "height": height, "type": mime-type, "data": data}
 130 | scale       | float | RW   | 1.0     | Display area scale factor 0.0 - 1.0
 131 | viewport    | bool  | RW   | false   | Use viewport clipping
 132 | width       | int   | RO   |         | Display area width
 133 | height      | int   | RO   |         | Display area height
 134 | render_mode | str   | RO   | ''      | Canvas rendering mode
 135 | prefer_js   | str   | RW   |         | Prefer JavaScript over canvas methods
 136 | cursor_uri  | raw   | RW   |         | Can we render cursor using data URI
 137
 138 ### 2.3.2 Methods
 139
 140 | name               | parameters                                              | description
 141 | ------------------ | ------------------------------------------------------- | ------------
 142 | viewportChangePos  | (deltaX, deltaY)                                        | Move the viewport relative to the current location
 143 | viewportChangeSize | (width, height)                                         | Change size of the viewport
 144 | absX               | (x)                                                     | Return X relative to the remote display
 145 | absY               | (y)                                                     | Return Y relative to the remote display
 146 | resize             | (width, height)                                         | Set width and height
 147 | flip               | (from_queue)                                            | Update the visible canvas with the contents of the rendering canvas
 148 | clear              | ()                                                      | Clear the display (show logo if set)
 149 | pending            | ()                                                      | Check if there are waiting items in the render queue
 150 | flush              | ()                                                      | Resume processing the render queue unless it's empty
 151 | fillRect           | (x, y, width, height, color, from_queue)                | Draw a filled in rectangle
 152 | copyImage          | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
 153 | imageRect          | (x, y, mime, arr)                                       | Draw a rectangle with an image
 154 | startTile          | (x, y, width, height, color)                            | Begin updating a tile
 155 | subTile            | (tile, x, y, w, h, color)                               | Update a sub-rectangle within the given tile
 156 | finishTile         | ()                                                      | Draw the current tile to the display
 157 | blitImage          | (x, y, width, height, arr, offset, from_queue)          | Blit pixels (of R,G,B,A) to the display
 158 | blitRgbImage       | (x, y, width, height, arr, offset, from_queue)          | Blit RGB encoded image to display
 159 | blitRgbxImage      | (x, y, width, height, arr, offset, from_queue)          | Blit RGBX encoded image to display
 160 | drawImage          | (img, x, y)                                             | Draw image and track damage
 161 | changeCursor       | (pixels, mask, hotx, hoty, w, h)                        | Change cursor appearance
 162 | defaultCursor      | ()                                                      | Restore default cursor appearance
 163 | disableLocalCursor | ()                                                      | Disable local (client-side) cursor
 164 | clippingDisplay    | ()                                                      | Check if the remote display is larger than the client display
 165 | autoscale          | (containerWidth, containerHeight, downscaleOnly)        | Scale the display
 166
 167 ### 2.3.3 Callbacks
 168
 169 | name    | parameters | description
 170 | ------- | ---------- | ------------
 171 | onFlush | ()         | A display flush has been requested and we are now ready to resume FBU processing
 172
 173
 174 ## 2.4 RFB Module
 175
 176 ### 2.4.1 Configuration Attributes
 177
 178 | name              | type | mode | default    | description
 179 | ----------------- | ---- | ---- | ---------- | ------------
 180 | target            | DOM  | WO   | null       | Canvas element for rendering (passed to Display and Mouse)
 181 | focusContainer    | DOM  | WO   | document   | DOM element that captures keyboard input (passed to Keyboard)
 182 | encrypt           | bool | RW   | false      | Use TLS/SSL encryption
 183 | local_cursor      | bool | RW   | false      | Request locally rendered cursor
 184 | shared            | bool | RW   | true       | Request shared VNC mode
 185 | view_only         | bool | RW   | false      | Disable client mouse/keyboard
 186 | xvp_password_sep  | str  | RW   | '@'        | Separator for XVP password fields
 187 | disconnectTimeout | int  | RW   | 3          | Time (in seconds) to wait for disconnection
 188 | wsProtocols       | arr  | RW   | ['binary'] | Protocols to use in the WebSocket connection
 189 | repeaterID        | str  | RW   | ''         | UltraVNC RepeaterID to connect to
 190 | viewportDrag      | bool | RW   | false      | Move the viewport on mouse drags
 191
 192 ### 2.4.2 Methods
 193
 194 | name               | parameters                   | description
 195 | ------------------ | ---------------------------- | ------------
 196 | connect            | (host, port, password, path) | Connect to the given host:port/path. Optional password and path.
 197 | disconnect         | ()                           | Disconnect
 198 | sendPassword       | (passwd)                     | Send password after onPasswordRequired callback
 199 | sendCtrlAltDel     | ()                           | Send Ctrl-Alt-Del key sequence
 200 | xvpOp              | (ver, op)                    | Send a XVP operation (2=shutdown, 3=reboot, 4=reset)
 201 | xvpShutdown        | ()                           | Send XVP shutdown.
 202 | xvpReboot          | ()                           | Send XVP reboot.
 203 | xvpReset           | ()                           | Send XVP reset.
 204 | sendKey            | (keysym, down)               | Send a key press event. If down not specified, send a down and up event.
 205 | clipboardPasteFrom | (text)                       | Send a clipboard paste event
 206 | requestDesktopSize | (width, height)              | Send a request to change the remote desktop size.
 207
 208 ### 2.4.3 Callbacks
 209
 210 | name               | parameters                 | description
 211 | ------------------ | -------------------------- | ------------
 212 | onUpdateState      | (rfb, state, oldstate)     | Connection state change (see details below)
 213 | onNotification     | (rfb, msg, level, options) | Notification for the UI (optional options)
 214 | onDisconnected     | (rfb, reason)              | Disconnection finished with an optional reason. No reason specified means normal disconnect.
 215 | onPasswordRequired | (rfb, msg)                 | VNC password is required (use sendPassword), optionally comes with a message.
 216 | onClipboard        | (rfb, text)                | RFB clipboard contents received
 217 | onBell             | (rfb)                      | RFB Bell message received
 218 | onFBUReceive       | (rfb, fbu)                 | RFB FBU received but not yet processed (see details below)
 219 | onFBUComplete      | (rfb, fbu)                 | RFB FBU received and processed (see details below)
 220 | onFBResize         | (rfb, width, height)       | Frame buffer (remote desktop) size changed
 221 | onDesktopName      | (rfb, name)                | VNC desktop name recieved
 222 | onXvpInit          | (version)                  | XVP extensions active for this connection.
 223
 224
 225 __RFB onUpdateState callback details__
 226
 227 The RFB module has an 'onUpdateState' callback that is invoked after
 228 the noVNC connection state changes. Here is a list of the states that
 229 are reported.
 230
 231 | connection state | description
 232 | ---------------- | ------------
 233 | connecting       | starting to connect
 234 | connected        | connected normally
 235 | disconnecting    | starting to disconnect
 236 | disconnected     | disconnected - permanent end-state for this RFB object
 237
 238 __RFB onFBUReceive and on FBUComplete callback details__
 239
 240 The onFBUReceive callback is invoked when a frame buffer update
 241 message has been received from the server but before the RFB class has
 242 done any additional handling. The onFBUComplete callback is invoked
 243 with the same information but after the RFB class has handled the
 244 message.
 245
 246 The 'fbu' parameter is an object with the following structure:
 247
 248     {
 249         x:            FBU_x_position,
 250         y:            FBU_y_position,
 251         width:        FBU_width,
 252         height:       FBU_height,
 253         encoding:     FBU_encoding_number,
 254         encodingName: FBU_encoding_string
 255     }