JavaScript API¶

The VNC SDK provides JavaScript bindings, enabling you to create a VNC Viewer app that runs in an HTML5-enabled web browser. Creating a VNC Server app is not supported.

Note: Synchronous XMLHttpRequest functionality is not supported as this is deprecated by recent Web standards and support for this will be removed from browsers in the future.

How to use the module

The VNC SDK is loaded by adding it as a script to your page:

<script src="path/to/vncsdk.js"></script>

This exports the module window.vncsdk which provides the SDK.

Alternatively, the SDK supports use with an AMD-compatible JavaScript loader such as RequireJS.

The SDK is a single JavaScript file with no external dependencies.

How to use the documentation

The primary source for documentation on the VNC SDK is provided by the C API reference. Most methods provided through the JavaScript bindings are documented with a brief summary only, since the full behaviour and description of each method and argument is contained in the C API reference. This documentation for the JavaScript bindings fully describes only the behaviour which is unique to the JavaScript bindings.

Methods and their types are mapped into JavaScript as follows:

• Each structure in the C API is mapped to a corresponding JavaScript class. For example, vnc_DataBuffer corresponds to vncsdk.DataBuffer. Each function operating on a C type is mapped to a method on the JavaScript class, such as DataBuffer.getData for vnc_DataBuffer_getData. The constructors of JavaScript classes correspond to the “create” methods in the C API.
• Arguments are mapped to their native JavaScript types. Pass in a JavaScript string where the C API uses a const char*, JavaScript arrays for C-style arrays, and JavaScript numbers for C integers. The SDK coerces any arguments you pass in to the expected type. See below for more information on how to use callback and enumeration objects.
• Many functions in the VNC SDK return return an error if an unexpected condition occurred or the arguments were invalid. In the C API, this is indicated by functions returning vnc_failure or NULL, and the error condition can be found by calling vnc_getLastError. In the JavaScript bindings, this function is not available, as all errors are indicated by throwing exceptions. For all cases where C API returns an error, the JavaScript bindings throw a vncsdk.VncException, whose errorCode member contains the strings described in the C API reference. Many methods can also throw standard JavaScript errors such as ReferenceError or TypeError, if incorrect values are passed into the API.
• The vncsdk module contains global functions from the C API which are not associated with any particular class.

Memory management

Although JavaScript is a garbage-collected language, every object created by the VNC SDK must be explicitly destroyed by the user with its “destroy” method. The JavaScript garbage collector should not be relied on to clean up resources such as open network connections and UI components. Since most SDK objects hold references to shared long-running tasks such as network connections, it is not appropriate to expect the garbage collector to reclaim SDK objects: they must all be closed with their “destroy” method or network connections may not be cleanly closed.

How to use SDK callbacks

Each callback is represented by a class (interface) in the JavaScript API. In order to use the callback, create an object which implements the interface and pass that to any function which accepts a callback structure. Any JavaScript object containing the required function properties can be used as a callback; it is not strictly necessary to derive from the prototypes provided by the SDK.

// Example 1: Deriving from the SDK prototype
function MyLoggerCallback () {}
MyLoggerCallback.prototype = Object.create(vncsdk.Logger.Callback);
MyLoggerCallback.prototype.logMessage = function(level, message) {
  console.log('SDK message: ' + level + ', ' + message);
}
vncsdk.Logger.createCustomLogger(new MyLoggerCallback());

// Example 2: Using a direct object
vncsdk.Logger.createCustomLogger({
  'logMessage': function(level, message) {
    console.log('SDK message: ' + level + ', ' + message);
  }
});

How to use SDK enumerations

Enumerations are represented in the JavaScript API by an object with a field for each item. The items can be printed using toString() or their name member. Functions accepting an enum argument must be passed an instance of the required enum. Functions accepting a bitmask of enums take a JavaScript Set of enum items; for older browsers without support for ES6 Sets, vncsdk.Set provides a simple polyfill (note that if window.Set is available it will be used, so bear in mind that IE11’s implementation of Set lacks many methods provided by Chrome and Firefox). Callbacks returning an SDK enum always return the same item as the SDK exports, so you can test for equality using ==.

var viewer = new vncsdk.Viewer();

// Example: passing in an enum
viewer.sendScrollEvent(5,
    vncsdk.Viewer.MouseWheel.MOUSE_WHEEL_VERTICAL);

// Example: passing in a bitmask of enums
var buttons = new vncsdk.Set();
buttons.add(vncsdk.Viewer.MouseButton.MOUSE_BUTTON_LEFT);
viewer.sendPointerEvent(100, 100, buttons, false);

// Example: receiving an enum in a callback, printing items using
// name, and checking for specific enum values
viewer.setConnectionCallback({
  'connected': // ...
  'connecting': // ...
  'disconnected': function(viewer, reason, flags) {
    flags.forEach(function(flag) {
      if (flag == vncsdk.Viewer.DisconnectFlags.CAN_RECONNECT)
        console.log("Viewer disconnected, reconnecting...");
      else
        console.log("Viewer disconnected, got flag " + flag.name);
    });
  }
});