Download

JavaScript Framework Guide

Preface

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

History

Version Date Comments
1.1 2017-07-18 Reformatting
1.0 2015-09-17 First version

Introduction

This document describes the functionality and configuration of the Inuvika OVD JavaScript (JS) 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

Pre-Requisites

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. Please refer to the Inuvika Installation and Configuration Guide at https://archive.inuvika.com/ovd/latest/documentation for more information on installing an OVD server farm.

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, ovd-javascript-framework-<version>.zip, is available for download from the Inuvika archives located at https://archive.inuvika.com/ovd/latest (version 1.2.1 and higher), in the packages folder.

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 (4.1.6) and addCallback (4.1.7) 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:

  1. 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.
  2. 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:

  1. 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:

  1. 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:

  1. Type: the event that is fired
  2. Source: a reference to the calling context (ex: 'document')
  3. 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:

  1. Type: the event that is fired
  2. 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:

  1. Type: the event that is fired
  2. 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 (4.1.6) and picked up by callbacks (4.1.7, 4.1.8).

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

  1. ovd.session.error
  2. ovd.session.timeRestriction
  3. ovd.session.statusChanged
  4. ovd.session.serversConnected
  5. ovd.session.server.statusChanged
  6. ovd.session.starting
  7. ovd.session.started
  8. ovd.session.destroying
  9. ovd.session.destroyed
  10. ovd.httpProvider.sessionStart
  11. ovd.httpProvider.sessionEnd
  12. ovd.httpProvider.sessionSuspend
  13. ovd.httpProvider.sessionStatus
  14. ovd.rdpProvider.crash
  15. ovd.rdpProvider.desktopPanel
  16. ovd.rdpProvider.clipboard.in
  17. ovd.rdpProvider.clipboard.out
  18. ovd.rdpProvider.menu
  19. ovd.rdpProvider.menu.notify
  20. ovd.rdpProvider.menu.notify
  21. ovd.rdpProvider.seamless.in.windowCreate
  22. ovd.rdpProvider.seamless.in.windowDestroy
  23. ovd.rdpProvider.seamless.in.windowPropertyChanged
  24. ovd.rdpProvider.seamless.in.groupDestroy
  25. ovd.rdpProvider.seamless.in.cursor
  26. ovd.rdpProvider.seamless.out.windowDestroy
  27. ovd.rdpProvider.seamless.out.windowPropertyChanged
  28. ovd.rdpProvider.gesture.twofingers
  29. ovd.rdpProvider.gesture.threefingers
  30. ovd.rdpProvider.gesture.pinching
  31. ovd.rdpProvider.gesture.panning
  32. ovd.rdpProvider.disk.job
  33. ovd.rdpProvider.printing.job
  34. ovd.applicationsProvider.applicationStart
  35. ovd.applicationsProvider.applicationStartWithArgs
  36. ovd.applicationsProvider.applicationStop
  37. ovd.applicationsProvider.statusChanged
  38. 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>