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 'view_only' configuration option
  14 enabled, then confirms it was set, then disables it:
  15
  16     var rfb = new RFB(target, {'view_only': true});
  17     if (rfb.get_view_only()) {
  18         alert("View Only is set");
  19     }
  20     rfb.set_view_only(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 | local_cursor      | bool  | RW   | false      | Request locally rendered cursor
  33 | view_only         | bool  | RW   | false      | Disable client mouse/keyboard
  34 | touchButton       | int   | RW   | 1          | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  35 | scale             | float | RW   | 1.0        | Display area scale factor
  36 | viewport          | bool  | RW   | false      | Use viewport clipping
  37 | disconnectTimeout | int   | RW   | 3          | Time (in seconds) to wait for disconnection
  38 | viewportDrag      | bool  | RW   | false      | Move the viewport on mouse drags
  39 | capabilities      | arr   | RO   | []         | Supported capabilities (can include: 'power', 'resize')
  40
  41
  42 ## 2 Methods
  43
  44 In addition to the getter and setter methods to modify configuration
  45 attributes, the RFB object has other methods that are available in the
  46 object instance.
  47
  48 | name               | parameters                      | description
  49 | ------------------ | ------------------------------- | ------------
  50 | connect            | (url, options)                  | Connect to the given URL
  51 | disconnect         | ()                              | Disconnect
  52 | sendCredentials    | (credentials)                   | Send credentials after onCredentialsRequired callback
  53 | sendCtrlAltDel     | ()                              | Send Ctrl-Alt-Del key sequence
  54 | machineShutdown    | ()                              | Request a shutdown of the remote machine.
  55 | machineReboot      | ()                              | Request a reboot of the remote machine.
  56 | machineReset       | ()                              | Request a reset of the remote machine.
  57 | sendKey            | (keysym, code, down)            | Send a key press event. If down not specified, send a down and up event.
  58 | clipboardPasteFrom | (text)                          | Send a clipboard paste event
  59 | autoscale          | (width, height, downscaleOnly)  | Scale the display
  60 | clippingDisplay    | ()                              | Check if the remote display is larger than the client display
  61 | requestDesktopSize | (width, height)                 | Send a request to change the remote desktop size.
  62 | viewportChangeSize | (width, height)                 | Change size of the viewport
  63
  64 __connect() details__
  65
  66 The connect() call supports the following options:
  67
  68 | name              | type  | default    | description
  69 | ----------------- | ----- | ---------- | ------------
  70 | shared            | bool  | true       | Request shared VNC mode
  71 | credentials       | obj   | {}         | Credentials to use when authenticating
  72 | repeaterID        | str   | ''         | UltraVNC RepeaterID to connect to
  73
  74
  75 ## 3 Callbacks
  76
  77 The RFB object has certain events that can be hooked with callback
  78 functions.
  79
  80 | name                  | parameters                 | description
  81 | --------------------- | -------------------------- | ------------
  82 | onUpdateState         | (rfb, state, oldstate)     | Connection state change (see details below)
  83 | onNotification        | (rfb, msg, level, options) | Notification for the UI (optional options)
  84 | onDisconnected        | (rfb, reason)              | Disconnection finished with an optional reason. No reason specified means normal disconnect.
  85 | onCredentialsRequired | (rfb, types)               | VNC credentials are required (use sendCredentials)
  86 | onClipboard           | (rfb, text)                | RFB clipboard contents received
  87 | onBell                | (rfb)                      | RFB Bell message received
  88 | onFBResize            | (rfb, width, height)       | Frame buffer (remote desktop) size changed
  89 | onDesktopName         | (rfb, name)                | VNC desktop name recieved
  90 | onCapabilities        | (rfb, capabilities)        | The supported capabilities has changed
  91
  92
  93 __RFB onUpdateState callback details__
  94
  95 The RFB module has an 'onUpdateState' callback that is invoked after
  96 the noVNC connection state changes. Here is a list of the states that
  97 are reported. Note that the RFB module can not transition from the
  98 disconnected state in any way, a new instance of the object has to be
  99 created for new connections.
 100
 101 | connection state | description
 102 | ---------------- | ------------
 103 | connecting       | starting to connect
 104 | connected        | connected normally
 105 | disconnecting    | starting to disconnect
 106 | disconnected     | disconnected - permanent end-state for this RFB object
 107
 108 __RFB onCredentialsRequired callback details__
 109
 110 The onCredentialsRequired callback is called when the server requests more
 111 credentials than was specified to connect(). The types argument is a list
 112 of all the credentials that are required. Currently the following are
 113 defined:
 114
 115 | name     | description
 116 | -------- | ------------
 117 | username | User that authenticates
 118 | password | Password for user
 119 | target   | String specifying target machine or session