JavaScript Framework Guide¶

Last updated on Apr 04 2024.

Preface¶

This document describes how to setup and use the OVD JavaScript Framework.

Overview¶

The JS Framework is used to implement and manage your own OVD client using JavaScript. It is a standalone component complete with an API that can be used to manage OVD sessions using an HTML5-based client. You can use clients created using this framework to run test examples on your Inuvika OVD farm or to integrate Inuvika OVD with your custom web application or portal.

Framework Components¶

There are four main components to this framework: SessionManagement, HTTP Provider, RDP Provider, and Applications Provider.

The SessionManagement object is the core of the framework, using the other components to communicate with the OVD Session Manager (OSM) and to serve up the session.

The HTTP Provider is an object that can send HTTP requests to the OSM. It is used as an intermediary between SessionManagement and the OSM, allowing them to communicate.

The RDP Provider is an object used to serve up the desktop and to communicate with the OAS. It receives all user inputs (mouse clicks, touch screen taps, window resizing, etc) and updates the desktop based on them (removes windows that have been closed, displays popup menus, etc). It communicates with the SessionManagement object to send and receive information to/from the OSM.

The Applications Provider is an object used to manage and run applications. It is used by the SessionManagement object to stop or start any applications that are available in a session.

Overview of JavaScript Framework components

Prerequisites¶

The JS Framework provides client side functionality in an OVD system. As OVD is a client/server solution, a functional OVD Farm is required to provide the server side of the functionality. An OVD Farm requires at a minimum, an OVD Session Manager (OSM) and an Application Server (ApS) to be installed and configured.

For more information on installing an OVD server farm, please refer to the Installation and Configuration Guide.

You will need a web server that has the inuvika-ovd-guacamole package installed. The framework will be installed on this system.

As this document is intended for developers, an understanding of how to develop web applications using JavaScript is also required.

Setup and Configuration¶

Package Download¶

The JS Framework package is available for download. Go to the Inuvika OVD supported versions page and click Download for the OVD version you are using. In the packages folder, you will find ovd-javascript-framework-<version>.zip.

Package Installation¶

In order to use this framework within your web application, unzip the package and publish the contents (excluding the examples) to a web-accessible directory on the web server from which you will run your web application. A commonly used directory is /var/www/html.

Warning

Web-accessible directories may depend on the web server that you are using. Please refer to the documentation for your server if you are unsure about the location of the web-accessible root directory.

Functionality¶

The JS Framework allows you to create and manage OVD sessions. It has four main components.

SessionManagement¶

A SessionManagement object must be used to create, destroy, and manage sessions.

Setup¶

Because SessionManagement uses an HTTP Provider to communicate with the OSM and an RDP Provider to serve up the desktop, those two components must be defined and set before SessionManagement can be used.

Example:

var session_management = new uovd.SessionManagement();
var http_provider = new uovd.provider.http.Proxy("proxy.php");
var rdp_provider = new uovd.provider.rdp.Html5();
session_management.setHttpProvider(http_provider);
session_management.setRdpProvider(rdp_provider);

Communication¶

Once the two providers are set, the SessionManagement object's fireEvent and addCallback can be used to interact with them.

Example 1: the SessionManagement object uses the HTTP Provider to communicate with the OSM and suspend a session. It does this by firing an HTTP Provider event:

session_management.fireEvent("ovd.httpProvider.sessionSuspend", self, {state: uovd.SUCCESS});

Example 2: the SessionManagement object adds a callback that picks up the ovd.rdpProvider.seamless.in.windowDestroy event when it's fired and executes a function that removes a window from the desktop screen:

session_management.addCallback("ovd.rdpProvider.seamless.in.windowDestroy", function(type, source, params) {
    var id = params["id"];
    console.log("Closing window : "+id);
    jQuery("#window_"+id).remove();
});

Example 3: the SessionManagement object uses the RDP Provider to remove a window and update the desktop screen to reflect the change. It does this by firing an RDP Provider event that is picked up by the callback set in Example 2:

session_management.fireEvent("ovd.rdpProvider.seamless.in.windowDestroy", this, params);

Functionality¶

A session can be started as follows:

Set the session options. Use the setParameters() function and pass an array with values for login, password, mode, sessionmanager address, height, and width as a parameter.
Start the session using the SessionManagement object's start() function.

Example:

var options = {
    login: jQuery("#login").val(),
    password: jQuery("#password").val(),
    mode: uovd.SESSION_MODE_APPLICATIONS,
    sessionmanager: jQuery("#sm").val(),
    width: jQuery(window).innerWidth(),
    height: jQuery(window).innerHeight()
};

session_management.setParameters(options);
session_management.start();

A session can by stopped using the SessionManagement object's stop() function.

Example:

session_management.stop();

HTTP Providers¶

An HTTP Provider is an object that can send HTTP requests to the OSM. It is a required component that the SessionManagement object will use to communicate with the OSM.

Direct¶

The default HTTP provider is named direct (class "Direct" in the API). This provider is designed to communicate directly to the OSM.

It is not possible to use the direct method in some cases because of Cross-Site Scripting (XSS) restrictions. So direct is only available in the following configurations:

The web component that implements the JS Framework is installed on the same server as the OSM and the client accesses it using HTTPS.
- As an alternative, the web component that implements the JS Framework can be installed on the same domain as the OSM (not the same IP but a domain like osw.test.demo & js.test.demo) and accessed using HTTPS
An OVD Enterprise Secure Gateway (ESG) is serving the Framework implementation

Proxy¶

The second HTTP provider is named proxy. It is mainly designed to provide HTTP communication with the OSM when direct is not possible. This provider requires a server side HTTP proxy web service that it will call using an Ajax request.

The HTML5 example in Example is configured to use this proxy provider targeting a web service named proxy.php (included in the framework package).

RDP Provider¶

The RDP Provider is responsible for communication with the Application Server and the session desktop.

HTML5¶

If you are using HTML5, you can use uovd.provider.rdp.Html5() to create the RDP Provider.

Applications Provider¶

The Applications Provider is responsible for the session applications when using HTML5. It manages the starting and stopping of all applications.

An application provider object does not need to be created, the SessionManagement object can fire events to use the application provider and its API:

session_management.fireEvent("ovd.applicationsProvider.applicationStart", document, {"id":appId});

Operations¶

This section outlines the JS Framework API operations and their parameters and responses.

SessionManagement¶

setHttpProvider¶

Set the http provider that the SessionManagement object will use to communicate with the OSM.

Parameters:

Http provider

Example:

var http_provider = new uovd.provider.http.Proxy("proxy.php");
session_management.setHttpProvider(http_provider);

setRdpProvider¶

Set the rdp provider that will be used to manage the session desktop.

Parameters:

Rdp provider

Example:

var rdp_provider = new uovd.provider.rdp.Html5();
session_management.setRdpProvider(rdp_provider);

start¶

Start the session.

Parameters:

None

Example:

session_management.start();

stop¶

Stop the session.

Parameters:

None

Example:

session_management.stop();

suspend¶

Suspend/disconnect the session.

Parameters:

None

Example:

session_management.suspend();

fireEvent¶

Fire an event for callbacks to pick up. See Events for a list of possible events.

Parameters:

Type: the event that is fired
Source: a reference to the calling context (ex: 'document')
Parameters: parameters for the callback function

Example:

session_management.fireEvent("ovd.applicationsProvider.applicationStart", document, {"id":appId});

addCallback¶

Registers a function to call when a specific event is fired. See Events for a list of possible events.

Parameters:

Type: the event that is fired
Function: the function to call when type is fired

Example:

session_management.addCallback("ovd.session.destroyed", function() {
    jQuery('#ovd_container').empty();
    jQuery('#ovd_launcher').empty();
    jQuery('#ovd_windows').empty();
    jQuery('#ovd_taskbar').empty();
});

removeCallback¶

Remove a registered callback.

Parameters:

Type: the event that is fired
Function: the function that is call when type is fired

Example:

session_management.removeCallback("ovd.session.destroyed", function() {
    jQuery('#ovd_container').empty();
    jQuery('#ovd_launcher').empty();
    jQuery('#ovd_windows').empty();
    jQuery('#ovd_taskbar').empty();
});

Events¶

This section outlines the possible event types that can be fired by fireEvent and picked up by callbacks.

The * can be used as a wildcard (ex: ovd.session.*) for when multiple events trigger the same callback.

ovd.session.error
ovd.session.timeRestriction
ovd.session.statusChanged
ovd.session.serversConnected
ovd.session.server.statusChanged
ovd.session.starting
ovd.session.started
ovd.session.destroying
ovd.session.destroyed
ovd.httpProvider.sessionStart
ovd.httpProvider.sessionEnd
ovd.httpProvider.sessionSuspend
ovd.httpProvider.sessionStatus
ovd.rdpProvider.crash
ovd.rdpProvider.desktopPanel
ovd.rdpProvider.clipboard.in
ovd.rdpProvider.clipboard.out
ovd.rdpProvider.menu
ovd.rdpProvider.menu.notify
ovd.rdpProvider.menu.notify
ovd.rdpProvider.seamless.in.windowCreate
ovd.rdpProvider.seamless.in.windowDestroy
ovd.rdpProvider.seamless.in.windowPropertyChanged
ovd.rdpProvider.seamless.in.groupDestroy
ovd.rdpProvider.seamless.in.cursor
ovd.rdpProvider.seamless.out.windowDestroy
ovd.rdpProvider.seamless.out.windowPropertyChanged
ovd.rdpProvider.gesture.twofingers
ovd.rdpProvider.gesture.threefingers
ovd.rdpProvider.gesture.pinching
ovd.rdpProvider.gesture.panning
ovd.rdpProvider.disk.job
ovd.rdpProvider.printing.job
ovd.applicationsProvider.applicationStart
ovd.applicationsProvider.applicationStartWithArgs
ovd.applicationsProvider.applicationStop
ovd.applicationsProvider.statusChanged
ovd.applicationsProvider.web.start

Example¶

This example will create a web page from which a user can login and start a session. Once authenticated, the applications will load on the same page and be ready to use.

A console will be visible to display all API calls as they are made.

<html>
    <head>
        <title>Test</title>
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
        <script type="text/javascript" src="jquery.js" charset="utf-8"></script>
        <script type="text/javascript" src="uovd.js" charset="utf-8"></script>
        <style type="text/css">
            .uovd_seamless_overlay_window {
                z-index: 200;
                position: fixed;
                border: 1px solid rgba(0,100,250,0.1);
                background: rgba(0,50,150,0.2);
            }

            .uovd_cursor_move               { cursor:move; }
            .uovd_cursor_resize_top         { cursor:n-resize; }
            .uovd_cursor_resize_bottom      { cursor:s-resize; }
            .uovd_cursor_resize_left        { cursor:w-resize; }
            .uovd_cursor_resize_right       { cursor:e-resize; }
            .uovd_cursor_resize_topleft     { cursor:nw-resize; }
            .uovd_cursor_resize_topright    { cursor:ne-resize; }
            .uovd_cursor_resize_bottomleft  { cursor:sw-resize; }
            .uovd_cursor_resize_bottomright { cursor:se-resize; }
        </style>
    </head>
    <body>
        <h1>Test OVD JS framework</h1>

        <form id="form">
            Login: <input id="login" value="dpaul" />
            Password: <input id="password" type="password" value="dpaul" />
            Session Manager: <input id="sm" value="sm.demo" />
            <input type="submit" value="Start!" />
        </form>
        <textarea id="log" rows="10" cols="98">== Logs ==
        </textarea>
        <div id="ovd_container" style="position: fixed; top:0; left:0; width:1px; height:1px; z-index: -1;"></div>
        <div id="ovd_windows" style="position: fixed; top:0; left:0; width:1px; height:1px;"></div>
        <div id="ovd_launcher"></div>
    </body>

    <script type="text/javascript">
        /* Globals - Main framework components */
        var session_management = new uovd.SessionManagement();
        var http_provider = new uovd.provider.http.Proxy("proxy.php");
        var rdp_provider = new uovd.provider.rdp.Html5();

        /* Window manager (for html5 seamless windows) */
        var wm = new uovd.provider.rdp.html5.SeamlessWindowManager(session_management, "#ovd_windows", new uovd.provider.rdp.html5.SeamlessWindowFactory());

        /* Framework events callbacks */

        /* Logs */
        session_management.addCallback("ovd.*", function(type, source, params) {
            var message = "Event : "+type + "\n";
            for(k in params) {
                message = message + "\t" + k + " = " + params[k] + "\n";
            }

            jQuery("#log").val(jQuery("#log").val()+"\n"+message);
            console.log(message);
        });

        /* Hidden session screen */
        session_management.addCallback("ovd.rdpProvider.desktopPanel", function(type, source, params) {
            jQuery('#ovd_container').append(params.node);
        });

        /* App launcher */
        session_management.addCallback("ovd.session.started", function() {
            var session = session_management.session;
            var servers = session.servers;
            var applications = {}; /* application id as index */

            /* Get application list */
            for(var i=0 ; i<servers.length ; ++i) {
                var server = servers[i];
                for(var j=0 ; j<server.applications.length ; ++j) {
                    applications[server.applications[j].id] = server.applications[j];
                }
            }

            for(var id in applications) {
                console.log("App ("+id+") "+applications[id].name);
                var node = jQuery("<a>");
                node.prop("id", "application_"+id);
                node.prop("href", "javascript:;");
                node.html(applications[id].name);
                node.click(function () {
                    var appId = jQuery(this).prop("id").split("_")[1];
                    console.log("Start App "+appId);


                    session_management.fireEvent("ovd.applicationsProvider.applicationStart", document, {"id":appId});
                });
                jQuery("#ovd_launcher").append(node).append(jQuery("<br>"));
            }
        });

        /* Cleaning */
        session_management.addCallback("ovd.session.destroyed", function() {
            jQuery('#ovd_container').empty();
            jQuery('#ovd_launcher').empty();
        });

        /* Submit form */
        jQuery("#form").submit(function(e) {
            e.preventDefault();

            var options = {
                login: jQuery("#login").val(),
                password: jQuery("#password").val(),
                mode: uovd.SESSION_MODE_APPLICATIONS,
                sessionmanager: jQuery("#sm").val(),
                width: jQuery(window).innerWidth(),
                height: jQuery(window).innerHeight()
            };


            session_management.setParameters(options);
            session_management.setHttpProvider(http_provider);
            session_management.setRdpProvider(rdp_provider);
            session_management.start();
            return false;
        });
    </script>
</html>