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 | name              | type  | mode | default    | description
  10 | ----------------- | ----- | ---- | ---------- | ------------
  11 | localCursor       | bool  | RW   | false      | Request locally rendered cursor
  12 | viewOnly          | bool  | RW   | false      | Disable client mouse/keyboard
  13 | touchButton       | int   | RW   | 1          | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  14 | scale             | float | RW   | 1.0        | Display area scale factor
  15 | viewport          | bool  | RW   | false      | Use viewport clipping
  16 | disconnectTimeout | int   | RW   | 3          | Time (in seconds) to wait for disconnection
  17 | viewportDrag      | bool  | RW   | false      | Move the viewport on mouse drags
  18 | capabilities      | arr   | RO   | []         | Supported capabilities (can include: 'power', 'resize')
  19
  20
  21 ## 2 Methods
  22
  23 | name               | parameters                      | description
  24 | ------------------ | ------------------------------- | ------------
  25 | connect            | (url, options)                  | Connect to the given URL
  26 | disconnect         | ()                              | Disconnect
  27 | sendCredentials    | (credentials)                   | Send credentials after onCredentialsRequired callback
  28 | sendCtrlAltDel     | ()                              | Send Ctrl-Alt-Del key sequence
  29 | machineShutdown    | ()                              | Request a shutdown of the remote machine.
  30 | machineReboot      | ()                              | Request a reboot of the remote machine.
  31 | machineReset       | ()                              | Request a reset of the remote machine.
  32 | sendKey            | (keysym, code, down)            | Send a key press event. If down not specified, send a down and up event.
  33 | clipboardPasteFrom | (text)                          | Send a clipboard paste event
  34 | autoscale          | (width, height, downscaleOnly)  | Scale the display
  35 | clippingDisplay    | ()                              | Check if the remote display is larger than the client display
  36 | requestDesktopSize | (width, height)                 | Send a request to change the remote desktop size.
  37 | viewportChangeSize | (width, height)                 | Change size of the viewport
  38
  39 __connect() details__
  40
  41 The connect() call supports the following options:
  42
  43 | name              | type  | default    | description
  44 | ----------------- | ----- | ---------- | ------------
  45 | shared            | bool  | true       | Request shared VNC mode
  46 | credentials       | obj   | {}         | Credentials to use when authenticating
  47 | repeaterID        | str   | ''         | UltraVNC RepeaterID to connect to
  48
  49
  50 ## 3 Callbacks
  51
  52 The RFB object has certain events that can be hooked with callback
  53 functions.
  54
  55 | name                  | parameters                 | description
  56 | --------------------- | -------------------------- | ------------
  57 | onupdatestate         | (rfb, state, oldstate)     | Connection state change (see details below)
  58 | onnotification        | (rfb, msg, level, options) | Notification for the UI (optional options)
  59 | ondisconnected        | (rfb, reason)              | Disconnection finished with an optional reason. No reason specified means normal disconnect.
  60 | oncredentialsrequired | (rfb, types)               | VNC credentials are required (use sendCredentials)
  61 | onclipboard           | (rfb, text)                | RFB clipboard contents received
  62 | onbell                | (rfb)                      | RFB Bell message received
  63 | onfbresize            | (rfb, width, height)       | Frame buffer (remote desktop) size changed
  64 | ondesktopname         | (rfb, name)                | VNC desktop name recieved
  65 | oncapabilities        | (rfb, capabilities)        | The supported capabilities has changed
  66
  67
  68 __RFB onUpdateState callback details__
  69
  70 The RFB module has an 'onUpdateState' callback that is invoked after
  71 the noVNC connection state changes. Here is a list of the states that
  72 are reported. Note that the RFB module can not transition from the
  73 disconnected state in any way, a new instance of the object has to be
  74 created for new connections.
  75
  76 | connection state | description
  77 | ---------------- | ------------
  78 | connecting       | starting to connect
  79 | connected        | connected normally
  80 | disconnecting    | starting to disconnect
  81 | disconnected     | disconnected - permanent end-state for this RFB object
  82
  83 __RFB onCredentialsRequired callback details__
  84
  85 The onCredentialsRequired callback is called when the server requests more
  86 credentials than was specified to connect(). The types argument is a list
  87 of all the credentials that are required. Currently the following are
  88 defined:
  89
  90 | name     | description
  91 | -------- | ------------
  92 | username | User that authenticates
  93 | password | Password for user
  94 | target   | String specifying target machine or session