Learn how to evaluate and integrate the VNC SDK
![We're here if you need help.](png/help-subhero.png)
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 tovncsdk.DataBuffer
. Each function operating on a C type is mapped to a method on the JavaScript class, such asDataBuffer.getData
forvnc_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
orNULL
, and the error condition can be found by callingvnc_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 avncsdk.VncException
, whoseerrorCode
member contains the strings described in the C API reference. Many methods can also throw standard JavaScript errors such asReferenceError
orTypeError
, 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);
});
}
});