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/mouse.js): Mouse input event handler with
  12 limited touch support.
  13
  14 * __Keyboard__ (core/input/keyboard.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/novnc/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 | touchButton | int  | RW   | 1        | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  81
  82 ### 2.1.2 Methods
  83
  84 | name   | parameters | description
  85 | ------ | ---------- | ------------
  86 | grab   | ()         | Begin capturing mouse events
  87 | ungrab | ()         | Stop capturing mouse events
  88
  89 ### 2.1.2 Callbacks
  90
  91 | name          | parameters          | description
  92 | ------------- | ------------------- | ------------
  93 | onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
  94 | onMouseMove   | (x, y)              | Handler for mouse movement
  95
  96
  97 ## 2.2 Keyboard Module
  98
  99 ### 2.2.1 Configuration Attributes
 100
 101 | name    | type | mode | default  | description
 102 | ------- | ---- | ---- | -------- | ------------
 103 | target  | DOM  | WO   | document | DOM element that captures keyboard input
 104
 105 ### 2.2.2 Methods
 106
 107 | name   | parameters | description
 108 | ------ | ---------- | ------------
 109 | grab   | ()         | Begin capturing keyboard events
 110 | ungrab | ()         | Stop capturing keyboard events
 111
 112 ### 2.2.3 Callbacks
 113
 114 | name       | parameters           | description
 115 | ---------- | -------------------- | ------------
 116 | onKeyPress | (keysym, code, down) | Handler for key press/release
 117
 118
 119 ## 2.3 Display Module
 120
 121 ### 2.3.1 Configuration Attributes
 122
 123 | name        | type  | mode | default | description
 124 | ----------- | ----- | ---- | ------- | ------------
 125 | target      | DOM   | WO   |         | Canvas element for rendering
 126 | context     | raw   | RO   |         | Canvas 2D context for rendering
 127 | logo        | raw   | RW   |         | Logo to display when cleared: {"width": width, "height": height, "type": mime-type, "data": data}
 128 | scale       | float | RW   | 1.0     | Display area scale factor 0.0 - 1.0
 129 | viewport    | bool  | RW   | false   | Use viewport clipping
 130 | width       | int   | RO   |         | Display area width
 131 | height      | int   | RO   |         | Display area height
 132 | render_mode | str   | RO   | ''      | Canvas rendering mode
 133 | prefer_js   | str   | RW   |         | Prefer JavaScript over canvas methods
 134 | cursor_uri  | raw   | RW   |         | Can we render cursor using data URI
 135
 136 ### 2.3.2 Methods
 137
 138 | name               | parameters                                              | description
 139 | ------------------ | ------------------------------------------------------- | ------------
 140 | viewportChangePos  | (deltaX, deltaY)                                        | Move the viewport relative to the current location
 141 | viewportChangeSize | (width, height)                                         | Change size of the viewport
 142 | absX               | (x)                                                     | Return X relative to the remote display
 143 | absY               | (y)                                                     | Return Y relative to the remote display
 144 | resize             | (width, height)                                         | Set width and height
 145 | flip               | (from_queue)                                            | Update the visible canvas with the contents of the rendering canvas
 146 | clear              | ()                                                      | Clear the display (show logo if set)
 147 | pending            | ()                                                      | Check if there are waiting items in the render queue
 148 | flush              | ()                                                      | Resume processing the render queue unless it's empty
 149 | fillRect           | (x, y, width, height, color, from_queue)                | Draw a filled in rectangle
 150 | copyImage          | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
 151 | imageRect          | (x, y, mime, arr)                                       | Draw a rectangle with an image
 152 | startTile          | (x, y, width, height, color)                            | Begin updating a tile
 153 | subTile            | (tile, x, y, w, h, color)                               | Update a sub-rectangle within the given tile
 154 | finishTile         | ()                                                      | Draw the current tile to the display
 155 | blitImage          | (x, y, width, height, arr, offset, from_queue)          | Blit pixels (of R,G,B,A) to the display
 156 | blitRgbImage       | (x, y, width, height, arr, offset, from_queue)          | Blit RGB encoded image to display
 157 | blitRgbxImage      | (x, y, width, height, arr, offset, from_queue)          | Blit RGBX encoded image to display
 158 | drawImage          | (img, x, y)                                             | Draw image and track damage
 159 | changeCursor       | (pixels, mask, hotx, hoty, w, h)                        | Change cursor appearance
 160 | defaultCursor      | ()                                                      | Restore default cursor appearance
 161 | disableLocalCursor | ()                                                      | Disable local (client-side) cursor
 162 | clippingDisplay    | ()                                                      | Check if the remote display is larger than the client display
 163 | autoscale          | (containerWidth, containerHeight, downscaleOnly)        | Scale the display
 164
 165 ### 2.3.3 Callbacks
 166
 167 | name    | parameters | description
 168 | ------- | ---------- | ------------
 169 | onFlush | ()         | A display flush has been requested and we are now ready to resume FBU processing
 170
 171
 172 ## 2.4 RFB Module
 173
 174 ### 2.4.1 Configuration Attributes
 175
 176 | name              | type | mode | default    | description
 177 | ----------------- | ---- | ---- | ---------- | ------------
 178 | target            | DOM  | WO   | null       | Canvas element for rendering (passed to Display, Mouse and Keyboard)
 179 | encrypt           | bool | RW   | false      | Use TLS/SSL encryption
 180 | local_cursor      | bool | RW   | false      | Request locally rendered cursor
 181 | shared            | bool | RW   | true       | Request shared VNC mode
 182 | view_only         | bool | RW   | false      | Disable client mouse/keyboard
 183 | xvp_password_sep  | str  | RW   | '@'        | Separator for XVP password fields
 184 | disconnectTimeout | int  | RW   | 3          | Time (in seconds) to wait for disconnection
 185 | wsProtocols       | arr  | RW   | ['binary'] | Protocols to use in the WebSocket connection
 186 | repeaterID        | str  | RW   | ''         | UltraVNC RepeaterID to connect to
 187 | viewportDrag      | bool | RW   | false      | Move the viewport on mouse drags
 188
 189 ### 2.4.2 Methods
 190
 191 | name               | parameters                   | description
 192 | ------------------ | ---------------------------- | ------------
 193 | connect            | (host, port, password, path) | Connect to the given host:port/path. Optional password and path.
 194 | disconnect         | ()                           | Disconnect
 195 | sendPassword       | (passwd)                     | Send password after onPasswordRequired callback
 196 | sendCtrlAltDel     | ()                           | Send Ctrl-Alt-Del key sequence
 197 | xvpOp              | (ver, op)                    | Send a XVP operation (2=shutdown, 3=reboot, 4=reset)
 198 | xvpShutdown        | ()                           | Send XVP shutdown.
 199 | xvpReboot          | ()                           | Send XVP reboot.
 200 | xvpReset           | ()                           | Send XVP reset.
 201 | sendKey            | (keysym, code, down)         | Send a key press event. If down not specified, send a down and up event.
 202 | clipboardPasteFrom | (text)                       | Send a clipboard paste event
 203 | requestDesktopSize | (width, height)              | Send a request to change the remote desktop size.
 204
 205 ### 2.4.3 Callbacks
 206
 207 | name               | parameters                 | description
 208 | ------------------ | -------------------------- | ------------
 209 | onUpdateState      | (rfb, state, oldstate)     | Connection state change (see details below)
 210 | onNotification     | (rfb, msg, level, options) | Notification for the UI (optional options)
 211 | onDisconnected     | (rfb, reason)              | Disconnection finished with an optional reason. No reason specified means normal disconnect.
 212 | onPasswordRequired | (rfb, msg)                 | VNC password is required (use sendPassword), optionally comes with a message.
 213 | onClipboard        | (rfb, text)                | RFB clipboard contents received
 214 | onBell             | (rfb)                      | RFB Bell message received
 215 | onFBUReceive       | (rfb, fbu)                 | RFB FBU received but not yet processed (see details below)
 216 | onFBUComplete      | (rfb, fbu)                 | RFB FBU received and processed (see details below)
 217 | onFBResize         | (rfb, width, height)       | Frame buffer (remote desktop) size changed
 218 | onDesktopName      | (rfb, name)                | VNC desktop name recieved
 219 | onXvpInit          | (version)                  | XVP extensions active for this connection.
 220
 221
 222 __RFB onUpdateState callback details__
 223
 224 The RFB module has an 'onUpdateState' callback that is invoked after
 225 the noVNC connection state changes. Here is a list of the states that
 226 are reported. Note that the RFB module can not transition from the
 227 disconnected state in any way, a new instance of the object has to be
 228 created for new connections.
 229
 230 | connection state | description
 231 | ---------------- | ------------
 232 | connecting       | starting to connect
 233 | connected        | connected normally
 234 | disconnecting    | starting to disconnect
 235 | disconnected     | disconnected - permanent end-state for this RFB object
 236
 237 __RFB onFBUReceive and on FBUComplete callback details__
 238
 239 The onFBUReceive callback is invoked when a frame buffer update
 240 message has been received from the server but before the RFB class has
 241 done any additional handling. The onFBUComplete callback is invoked
 242 with the same information but after the RFB class has handled the
 243 message.
 244
 245 The 'fbu' parameter is an object with the following structure:
 246
 247     {
 248         x:            FBU_x_position,
 249         y:            FBU_y_position,
 250         width:        FBU_width,
 251         height:       FBU_height,
 252         encoding:     FBU_encoding_number,
 253         encodingName: FBU_encoding_string
 254     }