docs/API.md

   1 # API
   2
   3 The interface of the noVNC client consists of a single RFB object that
   4 is instantiated once per connection.
   5
   6
   7 ## 1 Configuration Attributes
   8
   9 Each configuration option has a default value, which can be overridden
  10 by a a configuration object passed to the constructor. Configuration
  11 options can then be read and modified after initialization with "get_*"
  12 and "set_*" methods respectively. For example, the following
  13 initializes an RFB object with the 'encrypt' configuration option
  14 enabled, then confirms it was set, then disables it:
  15
  16     var rfb = new RFB({'encrypt': true});
  17     if (rfb.get_encrypt()) {
  18         alert("Encryption is set");
  19     }
  20     rfb.set_encrypt(false);
  21
  22 Some attributes are read-only and cannot be changed. An exception will
  23 be thrown if an attempt is made to set one of these attributs. The
  24 attribute mode is one of the following:
  25
  26     RO - read only
  27     RW - read write
  28     WO - write once
  29
  30 | name              | type  | mode | default    | description
  31 | ----------------- | ----- | ---- | ---------- | ------------
  32 | target            | DOM   | WO   | null       | Canvas element for rendering (passed to Display, Mouse and Keyboard)
  33 | encrypt           | bool  | RW   | false      | Use TLS/SSL encryption
  34 | local_cursor      | bool  | RW   | false      | Request locally rendered cursor
  35 | shared            | bool  | RW   | true       | Request shared VNC mode
  36 | view_only         | bool  | RW   | false      | Disable client mouse/keyboard
  37 | touchButton       | int   | RW   | 1          | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  38 | scale             | float | RW   | 1.0        | Display area scale factor
  39 | viewport          | bool  | RW   | false      | Use viewport clipping
  40 | disconnectTimeout | int   | RW   | 3          | Time (in seconds) to wait for disconnection
  41 | wsProtocols       | arr   | RW   | ['binary'] | Protocols to use in the WebSocket connection
  42 | repeaterID        | str   | RW   | ''         | UltraVNC RepeaterID to connect to
  43 | viewportDrag      | bool  | RW   | false      | Move the viewport on mouse drags
  44 | capabilities      | arr   | RO   | []         | Supported capabilities (can include: 'power')
  45
  46
  47 ## 2 Methods
  48
  49 In addition to the getter and setter methods to modify configuration
  50 attributes, the RFB object has other methods that are available in the
  51 object instance.
  52
  53 | name               | parameters                      | description
  54 | ------------------ | ------------------------------- | ------------
  55 | connect            | (host, port, credentials, path) | Connect to the given host:port/path. Optional credentials and path.
  56 | disconnect         | ()                              | Disconnect
  57 | sendCredentials    | (credentials)                   | Send credentials after onCredentialsRequired callback
  58 | sendCtrlAltDel     | ()                              | Send Ctrl-Alt-Del key sequence
  59 | machineShutdown    | ()                              | Request a shutdown of the remote machine.
  60 | machineReboot      | ()                              | Request a reboot of the remote machine.
  61 | machineReset       | ()                              | Request a reset of the remote machine.
  62 | sendKey            | (keysym, code, down)            | Send a key press event. If down not specified, send a down and up event.
  63 | clipboardPasteFrom | (text)                          | Send a clipboard paste event
  64 | autoscale          | (width, height, downscaleOnly)  | Scale the display
  65 | clippingDisplay    | ()                              | Check if the remote display is larger than the client display
  66 | requestDesktopSize | (width, height)                 | Send a request to change the remote desktop size.
  67 | viewportChangeSize | (width, height)                 | Change size of the viewport
  68
  69
  70 ## 3 Callbacks
  71
  72 The RFB object has certain events that can be hooked with callback
  73 functions.
  74
  75 | name                  | parameters                 | description
  76 | --------------------- | -------------------------- | ------------
  77 | onUpdateState         | (rfb, state, oldstate)     | Connection state change (see details below)
  78 | onNotification        | (rfb, msg, level, options) | Notification for the UI (optional options)
  79 | onDisconnected        | (rfb, reason)              | Disconnection finished with an optional reason. No reason specified means normal disconnect.
  80 | onCredentialsRequired | (rfb, types)               | VNC credentials are required (use sendCredentials)
  81 | onClipboard           | (rfb, text)                | RFB clipboard contents received
  82 | onBell                | (rfb)                      | RFB Bell message received
  83 | onFBUReceive          | (rfb, fbu)                 | RFB FBU received but not yet processed (see details below)
  84 | onFBUComplete         | (rfb, fbu)                 | RFB FBU received and processed (see details below)
  85 | onFBResize            | (rfb, width, height)       | Frame buffer (remote desktop) size changed
  86 | onDesktopName         | (rfb, name)                | VNC desktop name recieved
  87 | onCapabilities        | (rfb, capabilities)        | The supported capabilities has changed
  88
  89
  90 __RFB onUpdateState callback details__
  91
  92 The RFB module has an 'onUpdateState' callback that is invoked after
  93 the noVNC connection state changes. Here is a list of the states that
  94 are reported. Note that the RFB module can not transition from the
  95 disconnected state in any way, a new instance of the object has to be
  96 created for new connections.
  97
  98 | connection state | description
  99 | ---------------- | ------------
 100 | connecting       | starting to connect
 101 | connected        | connected normally
 102 | disconnecting    | starting to disconnect
 103 | disconnected     | disconnected - permanent end-state for this RFB object
 104
 105 __RFB onCredentialsRequired callback details__
 106
 107 The onCredentialsRequired callback is called when the server requests more
 108 credentials than was specified to connect(). The types argument is a list
 109 of all the credentials that are required. Currently the following are
 110 defined:
 111
 112 | name     | description
 113 | -------- | ------------
 114 | username | User that authenticates
 115 | password | Password for user
 116 | target   | String specifying target machine or session
 117
 118
 119 __RFB onFBUReceive and on FBUComplete callback details__
 120
 121 The onFBUReceive callback is invoked when a frame buffer update
 122 message has been received from the server but before the RFB class has
 123 done any additional handling. The onFBUComplete callback is invoked
 124 with the same information but after the RFB class has handled the
 125 message.
 126
 127 The 'fbu' parameter is an object with the following structure:
 128
 129     {
 130         x:            FBU_x_position,
 131         y:            FBU_y_position,
 132         width:        FBU_width,
 133         height:       FBU_height,
 134         encoding:     FBU_encoding_number,
 135         encodingName: FBU_encoding_string
 136     }