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