1 of 100

Thinfinity® VirtualUI 3.0

Thinfinity VirtualUI 3.0

Introduction

Thinfinity® VirtualUI™ is a software solution that enables developers to add user interface web remoting to their Windows applications. Typically, by adding one line of code to the application's project, you can transform your Windows Application into a cross-platform one, enabling it to run as usual on Windows or as a Web application when installed under a Thinfinity VirtualUI Server environment.

Why Thinfinity VirtualUI?

1. It enables you to effortlessly create dual-platform Windows/HTML5 Apps.

2. It expands applications availability by delivering them instantly to users anywhere on any device.

3. It dramatically reduces the Total Cost of Ownership (TCO), by slashing IT costs and simplifying administration avoiding costly virtualization/remoting solutions such as Citrix XenApp® or Microsoft® RemoteApp.

Architecture

Thinfinity VirtualUI is composed of:

· Thinfinity VirtualUI Javascript Client, running on an HTML5-capable web browser

· Thinfinity VirtualUI Server, running as a Windows Service

· Thinfinity VirtualUI SDK dlls and/or source code files libraries referenced and/or included in your Windows application

· Thinfinity VirtualUI Gateway, optional scaling and load balancing components.

Requirements:

Development Machine

· Operating Systems:

- Microsoft Windows 8 32bit / 64bit

- Microsoft Windows 10

- Microsoft Windows Server 2012

- Microsoft Windows Server 2016

- Microsoft Windows Server 2019

· A development environment:

- Microsoft Visual Studio

- Delphi 5 to 10.1 Berlin

- C++ Builder

- Microsoft Visual Basic (including VB 6.0)

- PowerBuilder

- other

· The application can use .NET WPF, GDI, GDI+ and limited DirectX calls.

Server and Gateway Machine

· Windows 10

· Windows Server 2012 and 2012 R2

· Windows Server 2016

. Windows Server 2019

End-User Machine

· Any operating system and/or device with an HTML5-compliant web browser.

· Any modern web browser (HTML5-compliant) such as IE10/11, Chrome, Safari, Firefox, Opera, Edge, etc.

Getting Started Section

Getting Started

This section covers the basics of Thinfinity VirtualUI as follows:

1. Installing Thinfinity VirtualUI

2. Compiling and testing your WinForms, Delphi or C++ application

3. Registering the application in Thinfinity VirtualUI Server

4. Accessing the application from the Web

Find a more comprehensive reference here:

Development Server Manager

Advanced Programming with jsRO

Server Manager

Installing Thinfinity VirtualUI

1. Download the installer from the download page in the Cybele Software site:

http://www.cybelesoft.com/downloads/

2. Execute the installer on the target machine.

3. Select the environments to be installed:

Thinfinity VirtualUI Server

Thinfinity VirtualUI Server is an HTTPS/WebSocket Server that maintains the communication between your app and the web browser. Installing this environment will enable you to configure and run your adapted Windows apps. This is not needed for development purposes but its installation is recommended for testing purposes.

in this installation mode, the Thinfinity VirtualUI Server will be installed as a Windows Service.

Development Environment

This environment is meant to be installed on the developer machine. This mode installs the Thinfinity VirtualUI SDK files that you will need to include or reference in your application's project. It includes also one Thinfinity VirtualUI Server that will execute in 'development' mode, to quickly test your application from a web browser.

4. If you are installing the Server Environment, you will be presented with the following options:

All Components

This is the default option. Choose this for a stand-alone installation, Thinfinity VirtualUI Server will centralize all the connections.

Broker, Web Services and Virtualization Services

Choose this option to install the Broker components if you wish to distribute the connection's load between several installations. Read more about Scaling and Load Balancing.

Reverse Gateway

Choose this option to install the Gateway component if you wish to distribute the connection's load between several installations. Read more about Scaling and Load Balancing.

5. Press Next and wait for the installation process to finish. When it is done, press the 'Finish' button.

Simple UI Remoting

UI Remoting is made simple with Thinfinity VirtualUI. All it takes is adding one or two lines of code in your applications, compiling and, then configuring VirtualUI Server to show it.

o Compiling and Testing a Delphi Application

o Compiling and Testing a C++ Application

o Registering the Application in Thinfinity VirtualUI Server

o Accessing the App from the Web

o Application Execution Behavior

Compiling and Testing a WinForms Application

Follow these steps to integrate a .NET WinForms application with Thinfinity VirtualUI:

1. Open Microsoft Visual Studio.

2. Open the application's project you want to integrate with.

3. Right-click on the project name in the 'Solution Explorer' panel and then select 'Add' - 'Existing Item'. Look for the Thinfinity.VirtualUI.cs file, which is typically located in c:\Program Files\Thinfinity\VirtualUI\Dev\dotNet\.

4. In the program.cs file add a line as follows:

5. Compile your program and run it in debug mode.

You will see this message:

If you press the 'Start Web Browser' button, a web browser will open pointing to the application. The application will also open in desktop mode.

6. Alternatively, choose to not show the message and observe on the Windows Tray Bar that the Thinfinity VirtualUI Development Server icon will appear.

You can right-click on the icon, and after that click on the 'Open Web Browser' menu.

A Web browser window will open and your application will be running inside.

Read more:

Compiling and Testing a Delphi Application

Follow these steps to integrate a Delphi VCL application with Thinfinity VirtualUI:

1. Open Delphi.

2. Open the application's project.

3. Add the VirtualUI_AutoRun unit to the 'Uses' clause of the project source file. This unit will typically be located in the C:\Program Files (x86)\Thinfinity\VirtualUI\dev\Delphi folder.

program MyApp;
uses
 Windows,
 Forms,
 VirtualUI_AutoRun,
 MyApp.Main in MyApp.Main.pas' {Form1};
{$R *.res}
begin
 Application.Initialize;
 Application.CreateForm(TForm1, Form1);
 Application.Run;
end.

4. Compile the program and run it in debug mode.

You will see this message:

If you press the 'Start Web Browser' button, a web browser will open pointing to the application. The application will also open in desktop mode.

5. Alternatively, choose to not show the message and observe on the Windows tray bar that the Thinfinity VirtualUI Development Server icon will appear.

6. Right-click on the icon, and after that click on the 'Open Web Browser' menu.

A Web browser window will open and your application will be running inside.

Note:

When you run your application under an IDE, it automatically starts in web mode. To access the application, open your web browser and point to http://127.0.0.1:6080

7. Click on the 'Server Manager' menu to access the Development Server Manager.

o Compiling and Testing a C++ Application

o Registering the Application in Thinfinity VirtualUI Server

o Accessing the App from the Web

o Application Execution Behavior

Compiling and Testing a C++ Application

Follow these steps to integrate a C++ application with Thinfinity VirtualUI:

1. Open Visual Studio.

2. Open the application's project.

3. Add the path to the VirtualUI library in the 'Include Directories' field, which can be found in the main menu under Project - Properties - Configuration Properties - VC++ Directories).

4. Add Thinfinity.VirtualUI.cpp to the Source Files.

5. Add Thinfinity.VirtualUI.h to the Header Files.

6. Include Thinfinity.VirtualUI.h in the application`s cpp:

#include "Thinfinity.VirtualUI.h"

7. Create a VirtualUI instance of the program and start it.

BOOL CMFCTestApp::InitInstance()
{
 INITCOMMONCONTROLSEX InitCtrls;
 InitCtrls.dwSize = sizeof(InitCtrls);
 InitCtrls.dwICC = ICC_WIN95_CLASSES;
 InitCommonControlsEx(&InitCtrls);
 CWinAppEx::InitInstance();
 if (!AfxOleInit())
 {
 AfxMessageBox(IDP_OLE_INIT_FAILED);
 return FALSE;
 }
 // Initialize VirtualUI
 VirtualUI vui;
 vui.Start();
 …
 ...
}

8. Compile the program and run it in debug mode.

You will see this message:

If you press the 'Start Web Browser' button, a web browser will open pointing to the application. The application will also open in desktop mode.

9. Alternatively, choose to not show the message and observe on the Windows Tray Bar that the Thinfinity VirtualUI Development Server icon will appear.

10. Right-click on the icon, and after that click on the 'Open Web Browser' menu.

A Web browser window will open and your application will be running inside.

Note:

When you run your application under an IDE, it automatically starts in web mode. To access the application, open your web browser and point to http://127.0.0.1:6080

11. Click on the 'Server Manager' menu to access the Development Server Manager.

o Compiling and Testing a Delphi Application

o Registering the Application in Thinfinity VirtualUI Server

o Accessing the App from the Web

o Application Execution Behavior

Registering the Application in Thinfinity VirtualUI Server

Now the application needs to be registered on Thinfinity VirtualUI Server. By doing this, the application will get published on the web server and will be available to be run from the web.

To create an application profile, follow these steps:

3. Click on the 'Add' button.

4. Name the application and inform the application path and file name.

5. You can check the 'Default Application' option to bypass the Thinfinity VirtualUI landing page and go directly to the selected profile. You can access the rest of the profiles through their virtual path urls.

6. Press 'OK' and 'Apply' on the Server Manager screen.

Now the application is ready to be reached on the Web.

Read more:

Accessing the App from the Web

Follow the next steps to access registered applications using the web browser:

1. Open your preferred web browser.

2. Type in the application URL. This URL is composed of the server URL plus the Virtual Path configured for the application, i.e. http://your-machine:6580/MyApp/

Alternatively, leave the Virtual Path as the root path using just http://your-machine:6580/. In this case, a page with the list of applications will show up, unless you have set a profile to be the default application, in which case you will be connected to the Default Application.

a. Check the 'Open in a new browser window' option if you want the application to be opened in another tab.

b. Click on the corresponding icon of the application you want to access.

3. Authenticated users can log out with the 'Logout' button in the top right corner of the web interface.

Read more:

· Application Execution Behavior

Application Execution Behavior

The application execution behavior will depend on how the application is run.

· Windows Shell

When the application is executed from the Windows Shell, it will behave as a standard Windows application.

· Development Environment

When the application is executed under a Development Environment (such as Microsoft Visual Studio or Embarcadero Delphi), an instance of VirtualUI Server running in development mode will be started, and the application will be seen both as an standard Windows application and as a Web application.

· VirtualUI Sever's Web Page:

If the application is launched from a VirtualUI Server's page, it will run as a web application.

List of available demos for download

Below you'll find a list for all the available demos for Thinfinity VirtualUI :

· Microsoft Access

· Windows Presentation Foundation

· Delphi Demos :

.OnUploadEnd Event Demo

.ShellExecute Demo

.LibConfig Create Profile Demo

· Lazarus

· C++ Demos:

.C++ Builder Demo

.Google Maps Demo

· C#:

.Basic Demo

.LibConfig Create Profile Demo

.External Auth Provider Demo

· Microsoft Foundation Class Library

Adapting the Application

Thinfinity VirtualUI not only exposes the original application on the web browser, it also allows you to integrate, extend it and customize its look using web resources.

Read more:

· Customizing the Web Page

· Programming VirtualUI

Customizing the Web Page

By default, the applications are loaded in the app.html page, located in the VirtualUI web directory. However, if you need to change the look and feel, add a new functionality, etc., you can achieve this by loading the application in a different web page with the use of a virtual path.

Read more:

· Preparing the Web Page

· Create a Virtual Path for the Application

Preparing the Web Page

Create a new directory and the web page where the application will run. You can use app.html as a template. In order for the application to work in the browser, the page must have, at least:

1. A reference to the thinfinity.virtualui.css stylesheet.

2. A reference to the virtualui.sdk.min.js javascript library.

3. A div named 'virtualui' that will work as 'desktop' for the application.

4. The necessary code to create an instance of the Thinfinity.VirtualUI class, with a call to the connect() method.

For example:

<!DOCTYPE html>
<html>
<head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
 <meta name="apple-mobile-web-app-capable" content="yes" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densityDpi=device-dpi"/>
 <title>Thinfinity VirtualUI - Basic Page</title>
 <link rel="stylesheet" type="text/css" href="css/thinfinity.virtualui.css" />
 <script src="virtualui.sdk.min.js" type="text/javascript"></script>
</head>
<body>
 <script type="text/javascript">
 $(document).ready(function () {
 var virtualUI = new Thinfinity.VirtualUI();
 virtualUI.connect();
 });
 </script>
 <div id="virtualui" style="position:absolute;display:none;"></div>
</body>
</html>

Starting from this basic page, you can change the windows' style, add new html content and interact programmatically with the executed application.

Thinfinity VirtualUI Server Page Load Acheme

In the previous example page you can see references to Thinfinity VirtualUI files (a stylesheet and a Javascript file). It's not necessary for those common files to be replicated in each virtual path folder.

The server will handle each http request from a virtual path in the following order:

1) Search for the page locally, in the folder assigned to the application's virtual path.

2) Search for the page starting in the Thinfinity VirtualUI root directory.

Read more:

· Customizing Settings

Customizing Settings

After creating the directory and the web page, inform Thinfinity VirtualUI of their location by defining a virtual path for the application and indicating which page will be loaded by default.

In order to set a virtual path for the application:

2. Go to the 'Applications' tab.

3. Add the new application or select it from the list.

4. Click on the 'Edit' button.

5. Set the Home Page. Press the 'Open' button and search for the location of your customized home page.

6. You can modify the virtual path name.

7. Press 'OK' and 'Apply'.

When the application is loaded —through the icon in the index page or typing the url to the full virtual path—, Thinfinity VirtualUI will open the page that was specified in the 'Home Page' field of the application profile, and it will show the application.

Read more:

Programming VirtualUI

The virtualui.sdk.min.js javascript library has everything that you need to connect to your application and interact from it from the web page, extending and integrating with your execution environment as much as you wish.

The library has the following classes:

· The Thinfinity.VirtualUI class

· The Thinfinity.JsRO class

Thinfinity.VirtualUI class

This class is necessary and mandatory, because it's the one handling the communication between the browser and Thinfinity VirtualUI Server.

Properties

devMode

Methods

connect

Events

onClose

onError

onLoading

onShow

Read more:

· Handling VirtualUI Events

Handling VirtualUI Events

The following example shows how to assign handlers to events available in the VirtualUI object (they can be seen in the javascript console or shown as alerts in the case of errors or disconnections)

<!DOCTYPE html>
<html>
<head>
 <title>Thinfinity VirtualUI - Basic Page</title>
 <link rel="stylesheet" type="text/css" href="css/thinfinity.virtualui.css" />
 <script src="virtualui.sdk.min.js" type="text/javascript"></script>
</head>
<body>
 <script type="text/javascript">
 $(document).ready(function () {
 var virtualUI = new Thinfinity.VirtualUI();
 virtualUI.onError = function (errorMsg) {
 if (errorMsg == null) { errorMsg = ""; }
 alert("Application load failed: " + errorMsg);
 };
 virtualUI.onLoading = function () {
 console.log("Loading...");
 };
 virtualUI.onShow = function () {
 console.log("Application loaded.");
 };
 virtualUI.onClose = function () {
 alert("Application closed.");
 window.close();
 };
 virtualUI.connect();
 });
 </script>
 <div id="virtualui" style="position:absolute;display:none;"></div>
</body>
</html>

Thinfinity.jsRO Class

The Thinfinity.jsRO class helps create interaction between the application and the web that's much more fluid than any other methodology or standard technology available.

This class interacts with the executable file and accesses the data models that are exposed from the application and the properties, methods and events that have been written for each of these models.

In the next chapter we will see how to work with jsRO (Javascript Remote Objects).

Read more:

· Advanced Programming with jsRO

Using ClientSettings from Javascript

ClientSettings is an additional interface available in the Thinfinity VirtualUI Library that allows developers to programmatically configure some browser environment layout and behavior settings from their applications (e.g., the mouse movement type).

This interface is available both in the application (C++, C#, Delphi, etc.) and in the browser side, where it was extended to manage some web interface elements (the DockMenu widget, for the moment). ClientSettings is available in Javascript as a Thinfinity.VirtualUI attribute:

var vui = new Thinfinity.VirtualUI();
var clientSettings = vui.ClientSettings;

All ClientSettings attributes have a default value that determines the typical behavior in each case. Developers can change it by setting new values to these attributes, which override the defaults before the connection starts.

To hide the mouse pointer and remove the “Error Reporting” icon from the DockMenu, just do the following:

var vui = new Thinfinity.VirtualUI();
var clientSettings = vui.ClientSettings;

clientSettings.CursorVisible = false;
clientSettings.DockMenu.ErrorReporting = false;

ClientSettings Applying Order

As most of the ClientSettings values can be applied both in the browser side and the application, we need to define an applying order:

· A value set in the application overrides the default value.

· Any value set in the browser side always overrides any other value.

Read more about how to change browser behavior using ClientSettings.

Advanced Programming Section

Advanced Programming

Thinfinity VirtualUI offers a rich API that allows for a tight integration with external web resources.

JavaScript Remote Objects (jsRO) makes possible to define remote objects and expose properties, methods and events that are synchronized in both ends, the application and the web browser.

Web Components specialized methods let you embed HTML and Javascript components that can enhance your application with web browser content.

Read more:

· JavaScript Remote Objects (jsRO)

· Web Components

Javascript Remote Objects

JavaScript Remote Objects (jsRO) allows you to increase your application's power, extending it to the web environment. This is made possible by the publishing of data models defined programmatically from the application that expose properties, methods and events, easing the dialog between the web and the original application.

To make the development of applications with jsRO easy, Thinfinity VirtualUI provides a web environment that allows you to interact with the application during the development and test its functionality: the Development Lab.

Read more:

The Development Lab

Thinfinity VirtualUI includes an html test environment called Development Lab. You can test your customized application and access the available programming resources through the objects.

The Development Lab will load when you execute an application in Dev mode from your development environment by calling the URL where Thinfinity VirtualUI is running (i.e. http://127.0.0.1:6080/).

The environment consists of five panels:

· The Address bar. Load here the web page address that you want to open. If you call the root address ("/"), app.html will load; if you enter an application's virtual path, it will load the address that was specified as Home Page for this application in the Thinfinity VirtualUI Server Manager, and if the Home Page wasn't defined it will load app.html.

· The Model Inspector. The Model Inspector's function is to show the available properties, methods and events for each data model. In its upper part there's a combobox that shows the published models; by selecting an item you will see its attributes. From this panel, you can change the properties value, provided that they are not read-only.

· The Log pane. The log pane shows a log of the interaction between the jsRO object and the application. The newer entrances will show on top.

· The Console pane. In the console pane, you can assign a new value to a property or call a method.

· The Browser pane. This is the most important panel. The selected application will load there and it will show just like it would in the browser independently.

Read more:

· Life Cycle of jsRO Objects

· Creating jsRO Objects

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

Life cycle of the jsRO Objects

jsRO objects are always defined inside the application and propagated to the browser. New properties, methods or events can't be added From Javascript, but events that are produced can be handled, the property values can be retrieved and modified, and the object's methods can be invoked.

There are four pre-defined Javascript events that are related to the life cycle of a jsRO object, associated to its creation, updating and destruction,

Starting from the first ApplyModel produced in the application, jsRO will create the object, propagate it to the browser and trigger there the event related to this creation:

on(“model:object”, “created”)

also, for the properties that are created with an assigned value, jsRO will replicate their initial values in the browser and fire the corresponding events:

on(“model:object.property”, “changed”)

and from that moment on, it will keep the state of the properties synchronized in the application and the browser.

If the model needs to be updated by the addition of new attributes (properties, events or method) a new ApplyModel must be made, which will, in turn, with the model already created, fire a changed event on the model:

on(“model:object”, “changed”)

Finally, if the object is destroyed in the application, the deleted event will be triggered and the object will be destroyed in Javascript too.

on(“model:object”, “deleted”)

This last event will also be triggered when closing the application.

Read more:

· Creating jsRO Objects

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

Creating jsRO Objects

As stated previously, the sjRO models are created in the application and then propagated to the browser, where they can be consumed from Javascript through a Thinfinity.sjRO class instance.

Let's see a complete example of this sequence:

Both examples create a 'ro' object, which has a 'text' property with the value: 'Hello!'.

Using Delphi, in the Create method of the form:

// Creates the remote object and its property
 ro := TJSObject.Create('ro');
 ro.Properties.Add('text');
 ro.ApplyModel;

Using C# (.Net Winform application)

// Creates the remote object and its property
 ro = new JSObject("ro");
 ro.Properties.Add("text");
 ro.ApplyModel();

Let's see how to work with this object from Javascript:

$(document).ready(function () {

 ...
 ...
 var jsro = new Thinfinity.JsRO();
 var ro = null;
 ...
 ...
 jsro.on('model:ro', 'created', function () {
 ro = jsro.model.ro;
 });
 });

Sequence diagram for the creation of an object:

Read more:

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

Updating Properties

jsRO will keep each property synchronized in the browser and in the application. Each time a property is updated in the server side, this change triggers an event to the browser, where it can be handled by the corresponding on(“model:object.property”, “change”, …) event, if this event was declared. Similarly, when a property is updated in the browser, this change travels to the application and triggers the object.OnPropertyChange and property.OnSet events.

Sequence diagram for the assignation of a property value from the application and from the browser:

· jsRO Remote Calls

OnPropertyChange(), OnSet() y OnGet() Events

When publishing a model, jsRO will keep the state of the created object synchronized in the application side and in the browser. Each time a property is updated in the server side, this change is propagated to the browser, where besides updating the value it can be handled by the corresponding .on(“model:object.property”, “change”, …) event, if this event was declared.

When a property is updated on the browser side, this change is sent in the opposite direction (from the web to the application) and triggers an OnPropertyChange event in the instantiated JSObject object. This is a good place to do things like propagating the change of a property value to some other element of the application, update a group of values in a database, etc.

jsRO can also handle changes in the properties of its object through the declaration of the OnSet and OnGet property events.

By invoking the ApplyChanges method on a JSObject object, the collection of the properties added to the object is traversed and if any of these properties has an OnGet event declared, it's triggered.

The OnSet event, however, is executed when it receives a change from a particular property from the browser.

The way to add the OnSet and OnGet event handlers to a property is based on their definition, you can do so when of adding the property or afterwards, always remember to fire an ApplyModel so that the model is propagated to the browser.

The next example shows how the browser can retrieve the application form background color in a #RRGGBB format, and also how to change the background color using a value sent from the browser. Since the desktop application doesn't interpret colors like the web does, we need a conversion that works both ways:

Delphi Definition:

// Creates the remote object
 FRo := TJSObject.Create('ro');
 // Property definition
 FRo.Properties.Add('backgroundColor')
 .OnGet(TJSBinding.Create(
 procedure(const Parent: IJSObject; const Prop: IJSproperty)
 begin
 Prop.AsString := '#'
 + IntToHex(GetRValue(ColorToRGB(Form1.Color)), 2)
 + IntToHex(GetGValue(ColorToRGB(Form1.Color)), 2)
 + IntToHex(GetBValue(ColorToRGB(Form1.Color)), 2);
 end))
 .OnSet(TJSBinding.Create(
 procedure(const Parent: IJSObject; const Prop: IJSproperty)
 var
 value: string;
 begin
 value := LowerCase(Prop.AsString);
 if ((Length(value) = 7) and (copy(value, 1, 1) = '#')) then
 begin
 try
 Form1.Color := RGB(
 StrToInt('$' + Copy(value, 2, 2)),
 StrToInt('$' + Copy(value, 4, 2)),
 StrToInt('$' + Copy(value, 6, 2))
 );
 except
 end;
 end;
 end));

.Net definition:

// Creates the remote object
 ro = new JSObject("ro");
 // Property definition
 ro.Properties.Add("backgroundColor")
 .OnGet(new JSBinding(
 // This anonymous procedure do the actual get
 delegate(IJSObject Parent, IJSProperty Prop)
 {
 Prop.AsString = "#"
 + this.BackColor.R.ToString("X2")
 + this.BackColor.G.ToString("X2")
 + this.BackColor.B.ToString("X2");
 }))
 .OnSet(new JSBinding(
 // This anonymous procedure do the actual set
 delegate(IJSObject Parent, IJSProperty Prop)
 {
 string value = Prop.AsString.ToLower();
 Regex reColor = new Regex(@"^#([0-9,a-f]{6})$");
 Match match = reColor.Match(value);
 if (match.Success)
 {
 string color = match.Groups[1].Value;
 this.BackColor = Color.FromArgb(
 int.Parse(color.Substring(0, 2), NumberStyles.AllowHexSpecifier),
 int.Parse(color.Substring(2, 2), NumberStyles.AllowHexSpecifier),
 int.Parse(color.Substring(4, 2), NumberStyles.AllowHexSpecifier)
 );
 }
 }));

Assigning the property value in Javascript:

ro.backgroundColor = “#FF0000”;

jsRO Remote Calls

In order to achieve more interaction between the remote application and the browser, the object model provided by jsRO allows the creation of remote methods and events defined in the application by the developer. Both the methods and the events are created and added to a model. While the methods can be invoked from the browser to remotely execute the application's own actions, the events are fired from the application to the browser, where they can be handled by the corresponding callback.

Read more:

· Remote Methods

· Custom Events

Remote Methods

The remote jsRO methods allow you to make the application's own actions available to be invoked from Javascript.

When the invokation of a method arrives to the application from the browser, two events are fired: the first is OnMethodExecuted, at the level of the JSObject object, which receives all the methods calls from the browser; the second is OnCall, and it happens at the level of the remote method.

If the invoked method is a function (if it returns a value), the value will be returned and propagated to the browser, where it will be handled asynchronously by a callback defined as the last argument in the call to the method.

The following examples show how to add a method to an object and how it can be called from Javascript. In this case, we create a method called multiply, which will receive two integer type arguments as parameters and will return the result of the product between them. This result will be shown in the callback to the method call.

Method definition in Delphi:

// Creates the remote object
 FRo := TJSObject.Create('ro');
 // Adds the method
 FRo.Methods.Add('multiply') // Returns a IJSMethod
 .AddArgument('a', JSDT_FLOAT) // First value to multiply
 .AddArgument('b', JSDT_FLOAT) // Second value to multiply
 .OnCall(TJSCallback.Create( // Adds the callback
 procedure(const Parent: IJSObject; const Method: IJSMethod)
 var
 a, b: int;
 begin
 a := Method.Arguments['a'].AsFloat;
 b := Method.Arguments['b'].AsFloat;
 Method.ReturnValue.AsFloat := a * b;
 end))
 .ReturnValue.DataType := JSDT_FLOAT; // Sets the return type
 FRo.ApplyModel;

Method definition in .Net:

// Creates the remote object
 ro = new JSObject("ro");
 // Adds the method
 ro.Methods.Add("multiply") // Returns a JSMethod
 .AddArgument("a", IJSDataType.JSDT_FLOAT) // First number to multiply
 .AddArgument("b", IJSDataType.JSDT_FLOAT) // Second number to multiply
 .OnCall(new JSCallback( // Adds the callback
 delegate(IJSObject parent, IJSMethod Method)
 {
 float a, b;
 a = Method.Arguments["a"].AsFloat;
 b = Method.Arguments["b"].AsFloat;
 Method.ReturnValue.AsFloat = a * b;
 })).ReturnValue.DataType = IJSDataType.JSDT_FLOAT;
 ro.ApplyModel();

Method definition in C#:

// Creates the remote object
ro = new JSObject("ro");
// Adds the method
ro.Methods.Add("multiply") // Returns a JSMethod
 .AddArgument("a", IJSDataType.JSDT_FLOAT) // 1st number to multiply
 .AddArgument("b", IJSDataType.JSDT_FLOAT) // 2nd number to multiply
 .OnCall(new JSCallback( // Adds the callback
 delegate(IJSObject parent, IJSMethod Method)
 {
 float a, b;
 a = Method.Arguments["a"].AsFloat;
 b = Method.Arguments["b"].AsFloat;
 Method.ReturnValue.AsFloat = a * b;
 }))
 .ReturnValue.DataType = IJSDataType.JSDT_FLOAT;
ro.ApplyModel();

Invoke the method in order to run it from Javascript. Use a callback in case the result needs to be retrieved (like in this case):

 ro.multiply(3, 4, function (result) {
 alert("Result is " + result);
 });

Read more:

· Custom Events

Custom Events

On top of the events detailed in Life Cycle of jsRO Objects, events can be created in the application that are defined by the programmer and when fired will be propagated from the application to the browser.

The following example shows how to add a personalized event to an object and how this can be handled from Javascript. In this case we'll expose, as a JSON, the mouse coordinates.

Definition and use of an event in Delphi:

// Creates the remote object
 FRo := TJSObject.Create('ro');
 // Adds the event
 FRo.Events.Add('mousePositionChanged')
 .AddArgument('coords', JSDT_JSON); // Adds the mouse position as JSON
 FRo.ApplyModel;
 procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState;
 X, Y: Integer);
 begin
 FRo.Events['mousePositionChanged']
 .ArgumentAsJSON('coords', '{"x": ' + X + ', "y": ' + Y + '}')
 .Fire;
 end;

Definition and use of an event in .Net:

// Creates the remote object
 ro = new JSObject("ro");
 // Adds the event
 ro.Events.Add("mousePositionChanged")
 .AddArgument("coords", IJSDataType.JSDT_JSON) // Adds the mouse position as JSON
 ro.ApplyModel();
 ...
 ...
 private void Form1_MouseMove(object sender, MouseEventArgs e)
 {
 ro.Events["mousePositionChanged"]
 .ArgumentAsJSON("coords",
 "{ \"x\": " + MousePosition.X + ", \"y\": " + MousePosition.Y + "}")
 .Fire();
 }

Definition and use of an event in C#:

// Creates the remote object
ro = new JSObject("ro");
// Adds the eventro.Events.Add("mousePositionChanged")
.AddArgument("coords", IJSDataType.JSDT_JSON) //the mouse position as JSON
ro.ApplyModel();
...
...
private void Form1_MouseMove(object sender, MouseEventArgs e)
{ ro.Events["mousePositionChanged"]
 .ArgumentAsJSON("coords", "{ \"x\": " + MousePosition.X + ", \"y\": " + MousePosition.Y + "}")
 .Fire();
}

To handle the event in Javascript, please note that the Javascript syntax for the personalized events differs slightly from the syntax for the model events, since it's declared directly associated to the name of the jsRO (without the "model"):

 jsro.on('ro', 'mousePositionChanged', function (coords) {
 console.log('mouse moved to [' + coords.x + ', ' + coords.y + ']');
 });

Available demos for Javascript Remote Objects

Other interesting demos are HTMLDOC-Dojo and HTMLDOC-jQuery , which will show you how to modify HTML elements of the browser using Dojo and jQuery , from the application side . These are available for C# and VB6 .

Link to our GitHub repository:

Adding Web Content

We took VirtualUI integration tools one step further and created the HTMLDoc Object to enhance the integration of Windows app resources to the web.

This object handles web elements from the server side, sparing the developer the need to learn javascript to include interactive web content in their application. This makes the web enabling process much more straightforward in terms of time and organization and empowers developers to easily enhance their VirtualUI web enabled application with reusable widgets and components in web documents and web applications.

This API allows your to take advantage of Web Components and can also be used to include and run Javascript files that do not follow the HTML5 Web Component specification.

The HTMLDoc Object

VirtualUI provides a specialized application-side object called HTMLDoc, with methods that allow you to add web content without changing the original HTML or javascript files.

· Load and run Javascript files from the Windows app.

· Import HTML files from the Windows app.

· Securely access files not located in the web tree (needed to deploy web or media files along with your application).

· Create an HTML5 Web Component defined in an imported HTML file.

Loading Scripts

Thinfinity VirtualUI allows you to load and run Javascript files from the Windows app. In order to load a new javascript file, you can use the LoadScript method of the HTMLDoc component:

VirtualUI.HTMLDoc.LoadScript(URL, [Filename])

· The "URL" parameter is the Uniform Resource Locator pointing to the Javascript file location in the net.

· "Filename" is an optional parameter that, when specified, points to the actual Javascript file in the local file system. In this case the "URL" parameter will be virtual, and will resolve to this local "filename".

Importing HTML files

Thinfinity VirtualUI allows you to insert HTML content into the current web page. You can do this from your Windows app by calling the ImportHTML method of the HTMLDoc component:

VirtualUI.HTMLDoc.ImportHTML(URL, [Filename])

· The "URL" parameter is the Uniform Resource Locator pointing to the HTML file location in the net.

· "Filename" is an optional parameter that, when specified, points to the actual HTML file in the local file system. In this case, the "URL" parameter will be virtual, and will translate to this local "filename".

Accessing local files

With the purpose of providing secure urls to files that are not located in the application's web tree, we included two methods:

VirtualUI.HTMLDoc.CreateSessionURL(URL, LocalPath)

This method allows you to create a virtual URL valid during the session's lifetime.

· The "URL" parameter is the virtual URL to access the Filename or Directory specified in LocalPath.

· "LocalPath" can be a file name or a directory. If it is a file name, the URL parameter resolves to that filename; if it is a directory, the URL parameter is a virtual path that can be used to access any file under this local directory.

URL = VirtualUI.HTMLDoc.GetSafeURL(Filename, lifetime)

This method allows you to create a unique virtual URL for a specific file, valid during the time specified in minutes in the Lifetime parameter.

· The "Filename" parameter points to the local filename we want to create an unique URL for.

· "Lifetime" is the time during which the returned URL will be valid.

Creating Web Component instances

To create a Web Component instance, we added a specific method that will allow you to embed the component in the web page, tied or untied to a Windows control.

When the Web Component is tied to a Windows control, it will look like it is "embedded" in the form, replacing the Windows control area, following its position and size when it changes. When untied, it will be embedded into the web page, but its position and size will not be attached to any control area.

VirtualUI.HTMLDoc.CreateComponent(Id, TagOrHTML, ReplaceWnd)

· "Id" parameter is the HTML element ID.

· "TagOrHTML" can be a tagname or a valid HTML string.

· "ReplaceWnd" is the handle to the window control to be "replaced".

Examples:

1. Adding a tied Web Component by the tagname:

VirtualUI.HTMLDoc.CreateComponent("video1", "vui-video", panel1.Handle)

In this example, the HTML "<vui-video></vui-video>" will be inserted, and dynamically positioned according to panel1's position and size.

2. Adding tied HTML content from a valid HTML string:

VirtualUI.HTMLDoc.CreateComponent("hworld", "<div><span>hello world</span></div>", panel1.Handle)

In this example, the HTML "<div><span>hello world</span></div>" will be inserted, and dynamically positioned according to panel1's position and size.

3. Adding an untied Web Component by the tagname:

VirtualUI.HTMLDoc.CreateComponent("qzprinter1", "qzprinter")

In this example, the Web Component will be inserted, but not positioned according to any visible control.

Web Components

Web Components are a new and exciting technology that takes the well known "reusable software components" concept to the web. With this HTML5 specification you can build HTML+javascript pieces and use them as a custom HTML element.

In Thinfinity VirtualUI you can easily embed Web Components in your Windows application. Some Web Components examples are: a native video streaming component, a raw printing component, a QR component, a signature component, a Google Maps component, and so on.

With the purpose of embedding a Web Component in a Windows application, we provide a specialized object that allows you to:

· Load and run Web Component Javascript files from the Windows app.

· Import Web Component HTML files from the Windows app

· Securely access local resources that are not in the application's web tree (needed to deploy web or media files in your application)

Loading Web Component Scripts

Let's suppose that you are about to include some new functionality and logic which may need some Javascript library that is currently not loaded.

In order to load this new javascript library you can use the LoadScript method of the HTMLDoc component.

Importing Web Component HTML files

Web Components are defined in HTML files. In order to be able to create a Web Component, you need to import that file into the HTML DOM. With VirtualUI you can do this from your Windows app by calling the ImportHTML method of the HTMLDoc component.

Accessing local resources from the Web Component

Let's suppose we include a web component that needs to display a signature, and the signature image file is somewhere in the file system. Complying with standard web server specifications, Thinfinity VirtualUI forbids the access to files that are not in the root web tree. This means that to access that image file, you would be forced to first place it in the application's web tree. This wouldn't be neat!

With the purpose of providing secure urls to files that are not within the web tree root, we included the CreateSessionURL and GetUniqueURL methods. These methods help you create virtual URLs for the application session's lifetime, or for a specific file and valid only during a specified lifetime, in minutes.

Advanced Features Section

Advanced Features

Take a look at the Thinfinity VirtualUI advanced features:

· Enhanced Browser and DPI Support

· End-User Authentication

· One-Time URL

· Passing Command Line Arguments to VirtualUI Apps

· Recording and Playing Sessions

· Scaling and Load Balancing

· Printing

· Virtualization

· OEM Licensing

5.6. Recover Browser Information with BrowserInfo

When using VirtualUI, it is often necessary to be aware of some features and capabilities of the device from which end users are accessing our application.

The VirtualUI class has a property called BrowserInfo, which contains data about the browser being used. This information can assist us in delivering the best possible user experience.

In the list below we will find a detailed reference of the information that BrowserInfo will deliver:

Attribute

Description

Username

Returns the logged-on username.

IPAddress

Returns the client's ip address.

Location

Returns the URL of the current application.

UniqueBrowserId

Identifies an instance of a browser. Each time an end-user opens the application from a different browser window, this identifier will be have a different value.

UserAgent

Returns the browser's User Agent string. This value is very important to identify which browser type is used, if the remote device is a mobile, etc.

An important value to consider is the UserAgent property. When establishing a connection, the browser sends VirtualUI a data string indicating its brand and version, which OS it is running on, and the brand and model of the device that is being used. This value is known as the userAgent. Using this value we can infer, for example, if the user is connecting from a mobile device and then modify some specific feature, layout or functionality of our application to better suit that device.

Information relative to the available screen space:

Attribute

Description

BrowserWidth

Returns the width of the HTML element containing the VirtualUI viewer, in pixels.

BrowserHeigth

Returns the height of the HTML element containing the VirtualUI viewer, in pixels.

ScreenWidth

Returns the width of the end-user's device screen, in pixels.

ScreenHeight

Returns the height of the end-user's device screen, in pixels.

ScreenResolution

Returns the application screen resolution defined in the application profile.

ViewWidth

Returns the width of the VirtualUI viewer, in pixels.

ViewHeight

Returns the height of the VirtualUI viewer, in pixels.

Orientation

Returns the browser's orientation.

It is also worth mentioning that when using VirtualUI, the desktop size is dynamic. This means that the space available to display the application is correlated to the available space in the browser screen and it is not limited to a fixed desktop size space —as it would happen, for example, in an RDP connection, where the desktop size is defined when the connection is established.

The following C# example shows how to center a window of our application on this virtual desktop as needed, previously controlling its size if it exceeds the available space:

using Cybele.Thinfinity;...

...

private VirtualUI vui;

public Form1()

{

InitializeComponent();

vui = new VirtualUI();}

private void CenterThisWindow(object sender, EventArgs e)

{

this.WindowState = FormWindowState.Normal;

if (vui.BrowserInfo.ViewHeight < (this.Height + 20)) {

this.Height = vui.BrowserInfo.ViewHeight - 20;

}

if (vui.BrowserInfo.ViewWidth < (this.Width + 20))

{

this.Width = vui.BrowserInfo.ViewWidth - 20;

}

this.Top = (vui.BrowserInfo.ViewHeight - this.Height) / 2;

this.Left = (vui.BrowserInfo.ViewWidth - this.Width) / 2;

}

5.7. Change Browser Behavior Using ClientSettings

ClientSettings is an additional interface available in the Thinfinity VirtualUI Library that allows developers to remotely and programmatically configure particular browser settings. These settings are related to the cursor visibility and some specific touch action behaviors.

There is also a Javascript Clientsettings object version. Learn how to use it.

The table below shows a detailed reference of the ClientSettings interface current properties:

Property

Use

CursorVisible

Used to set the mouse pointer to 'show' or 'hide'.

Type: Boolean

Default value: True

Available in all Library Versions.

MouseMoveGestureStyle

Defines whether the mouse movement is read as relative or absolute in touch devices.

Type: Enum

Values:

MM_STYLE_RELATIVE = 0

MM_STYLE_ABSOLUTE = 1

Default value: MM_STYLE_RELATIVE

Available in all Library Versions.

MouseMoveGestureAction

Indicates if the dragging should be interpreted as scrolling or turning of the mouse wheel, affecting only the component on which the action is triggered.

Type: Enum

Values:

MM_ACTION_MOVE = 0,

MM_ACTION_WHEEL = 1

Default value: MM_ACTION_MOVE

Available in all Library Versions.

UseViewportSize

Indicates which measure values will be used to define the application's screen size.

Type: Boolean

Values:

True: use the viewport size

False: use a window screen based size.

Default value: False

Available only in Javascript.

DockMenu

Manages the visibility of the bottom menu and its options.

Available only in Javascript

Enabled

Boolean. Enables/disables the complete Dock Menu.

Type: Boolean

Default value: True

Pinned

Indicates when the DockMenu is pinned (visible, fixed) or unpinned (with autohide)

Type: Boolean

Default value: False

Items

Name/value pairs item collection.

WindowList

Enables/disables the "Windows list" option.

Type: Boolean

Default value: True

ErrorReporting

Enables/disables the "Error Reporting" option.

Type: Boolean

Default value: True

Keyboard

Enables/disables the "Keyboard" option (mobile only).

Type: Boolean

Default value: True

FullScreen

Enables/disables the "Full Screen" option (mobile only, if supported).

Type: Boolean

Default value: True

As mentioned previously, these properties were created to provide a better end-user experience when using touch devices.

When using a touch device, it is unusual for a mouse pointer to be displayed. Instead, finger gestures are interpreted by the device as different commands, acting on the element or elements that are located where the gesture is made.

But this is not always the best way, especially when the applications were not designed for these gestures. Most of the times, the best solution to this issue is to show the pointer and simulate the mouse actions using the captured gestures.

The properties that we have presented above will help us define the ideal settings to enjoy the best possible and intuitive user experience for our application.

The following example shows how to recognize a touch or mobile device, and to change the pointer behavior when it's detected. Warning: The detection list is not complete:

vui = new VirtualUI();

userAgent = vui.BrowserInfo.UserAgent.ToLower();

if ((userAgent.IndexOf("touch") != -1) || (userAgent.IndexOf("mobile") != -1) ||

(userAgent.IndexOf("iphone") != -1) || (userAgent.IndexOf("ipod") != -1) ||

(userAgent.IndexOf("ipad") != -1) || (userAgent.IndexOf("android") != -1) ||

(userAgent.IndexOf(" cros ") != -1)) {

vui.ClientSettings.MouseMoveGestureStyle = MouseMoveGestureStyle.MM_STYLE_ABSOLUTE;

vui.ClientSettings.MouseMoveGestureAction = MouseMoveGestureAction.MM_ACTION_WHEEL;

}

Read more about using ClientSettings from Javascript.

5.8. End-User Authentication

Thinfinity VirtualUI allows you to protect the published applications by applying Active Directory (AD) objects to each one of them. In order to be able to see and execute an application in the Thinfinity VirtualUI environment, either the application must have anonymous access or the end-user must provide credentials that satisfy the AD objects assigned to that application.

Thinfinity VirtualUI lets you activate one or more authentication methods, allowing for the mapping of credentials to AD objects, which in turn will grant access to the applications that had the same AD objects applied. Also, the end-user identification is passed on to the application in order to allow a Single Sign-On.

Read the following sections to learn how to implement the available authentication methods in VirtualUI web-enabled applications.

Read more:

· Entering Credentials

· Processing End-User Credentials

· Authentication Methods

5.8.1. Entering Credentials

Thinfinity VirtualUI allows you to enable one or more authentication methods at a time. There are two possible ways to ask for credentials:

· Using the standard Web Browser authentication dialog

· Showing a log-in page

The Standard Web Browser Authentication (aka Basic Authentication) is, in the context of an HTTP/HTTPS transaction, a method for the HTTP User Agent (the Web Browser) to provide end-user credentials when a request is started. The standard Web Browser authentication dialog is provided by each Web Browser and it looks like this:

This dialog is available when you use only one of the authentication access methods that require user and password: Windows Logon, RADIUS or External DLL.

Also, you can use a login page. The login page provided (login.html) was created to dynamically show all configured authentication methods in your Thinfinity VirtualUI Server. Every login option will be present only if the proper authentication method is configured.

For example, if only the 'Windows Logon' method is configured, the page will look like this:

But if you enable all predefined methods, your login will show something like this:

You can modify this page to adapt it to your branding and/or integration needs. Check out the login.html section to learn how.

Read more:

· Processing End-User Credentials

· Authentication Methods

· login.html

5.8.2. Processing End-user Credentials

Each published application without anonymous access requires the assignment of one or more Active Directory objects which define the users that can see and execute it.

Thinfinity VirtualUI implements a mapping mechanism to transform end-user credentials to AD objects. Only applications that match these AD objects will be granted access to the end-user.

When you enable an authentication method, you must add the mapping rules that will allow you to link the user ID with an AD object. This is done by specifying an external user ID mask and its linked AD objects.

Depending on the selected authentication method, Thinfinity VirtualUI uses the identification provided provided by the user to scan the mapping rule list and obtains the associated AD objects. If the matching process returns one or more AD objects, all applications with the same AD object are enabled to be seen and accessed by the end-user.

Read more:

· Entering Credentials

· Authentication Methods

5.8.3. Authentication Methods

Thinfinity VirtualUI allows you to use the following authentication methods.

Windows Logon

This option enables Active Directory credentials. This method is enabled by default.

RADIUS

Remote Authentication Dial-In User Service (RADIUS) is a networking protocol and software that provides centralized Authentication, Authorization, and Accounting (AAA) management for users who remotely connect to a network service, in this case the Thinfinity VirtualUI Server.

OAuth 2.0

OAuth 2.0 (or OAuth/2) is an open standard for authorization and authentication, commonly used as a way for Internet users to log into third party websites using their social network (Facebook, Google, LinkedIn, etc.) account without exposing their password.

External DLL

A custom authentication method implemented by you or a third party with our authentication API and referenced in the Thinfinity VirtualUI server.

Anonymous Authentication

You can also allow users to access applications anonymously. When this access is combined with other authentication methods, the anonymous access applications will be shown along with a 'Sign in' link for users to enter credentials.

All these methods will be enabled and configured in the Thinfinity VirtualUI Server Manager: choose the methods in the 'Authentication' tab and configure the mapping in the 'Mappings' subtab.

Read more:

· Windows Logon

· RADIUS

· OAuth 2.0

· External DLL

· Entering Credentials

· Processing End-User Credentials

5.8.3.1. Windows Logon

Windows Logon means that the end-user will have to enter Windows Activate Directory credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

The profiles matching the credentials provided in their the 'Permissions' tab will be the profiles shown to the authenticated user, along with those with the 'Allow Anonymous Access' option checked in their 'Permissions' tab

Windows Logon is enabled by default in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

Read more:

· RADIUS

· OAuth 2.0

· External DLL

5.8.3.2. RADIUS

RADIUS as an authentication method means that the user will have to enter their RADIUS credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

RADIUS can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add RADIUS as an authentication method you will be required to provide the RADIUS account relevant information.

The user definition is completed through the mapping between the user ID returned by RADIUS and a user registered for this Authentication ID Mask. The RADIUS credentials are mapped to Active Directory Objects in the 'Mappings' tab. Those Active Directory objects should satisfy the permission access rules of the applications that they are expected to get access to.

Read more:

· Windows Logon

· OAuth 2.0

· External DLL

5.8.3.3. OAuth 2.0

OAuth 2.0 is a standard authentication method used mostly in social web sites. The user will have to enter their OAuth 2.0 (Facebook, Dropbox, LinkedIn, Google or other) credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

An OAuth 2.0 authentication method can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle their availability as an authentication method by checking or unchecking them.

When you add an OAuth 2.0 method you will be required to provide the relevant information. Check the complete reference in the OAuth 2.0 Authentication Method Settings. This information is also reflected in the OAuth2Models.ini file, distributed with the installation.

The user definition is completed through the mapping between the user ID returned by the selected OAuth 2.0 method (in the examples mentioned it's always the email) and a user registered for this Authentication ID Mask. The OAuth 2.0 method's credentials are mapped to Active Directory Objects in the 'Mappings' tab. Those Active Directory objects should satisfy the permission access rules of the applications that they are expected to get access to.

Read more:

· OAuth2Models.ini

· CSS for SSO options

5.8.3.3.1. OAuth2Models.ini

OAuth2Models.ini is a file is distributed with the Thinfinity VirtualUI installation that has all the information of the default available logins:

[Google]

ClientID =

ClientSecret =

AuthorizationParameters = scope=https://www.googleapis.com/auth/userinfo.email&approval_prompt=auto

AuthorizationURL = https://accounts.google.com/o/oauth2/auth

TokenValidationURL = https://accounts.google.com/o/oauth2/token

ProfileValidationURL = https://www.googleapis.com/oauth2/v1/userinfo

UsernameField = email

[Facebook]

ClientID =

ClientSecret =

AuthorizationParameters = scope=email

AuthorizationURL = https://www.facebook.com/dialog/oauth

TokenValidationURL = https://graph.facebook.com/oauth/access_token

ProfileValidationURL = https://graph.facebook.com/me?

UsernameField = email

[LinkedIn]

ClientID =

ClientSecret =

AuthorizationURL = https://www.linkedin.com/uas/oauth2/authorization

AuthorizationParameters = state=HIJK98sDT88jnS23S&scope=r_emailaddress

TokenValidationURL = https://www.linkedin.com/uas/oauth2/accessToken

ProfileValidationURL = https://api.linkedin.com/v1/people/~:(emailAddress)?format=json

UsernameField = emailAddress

[Dropbox]

ClientID =

ClientSecret =

AuthorizationURL = https://www.dropbox.com/1/oauth2/authorize

AuthorizationParameters =

TokenValidationURL = https://api.dropboxapi.com/1/oauth2/token

ProfileValidationURL = https://api.dropboxapi.com/1/account/info

UsernameField = email

Use this file as a template and edit it in order to add new authentication methods or ask your authentication provider for different data.

Read more:

· OAuth 2.0

5.8.3.3.2. CSS for SSO Options

In the login.css file, included in the 'web\css' folder of the Thinfinity VirtualUI installation, you will find the style for the login buttons.

#google { background-color:#4285F4; }

#google .imgbtn { background-image: url(../images/sso/google.png); }

#facebook { background-color:#2f4e9e; }

#facebook .imgbtn { background-image: url(../images/sso/facebook.png); }

#yahoo { background-color:#6839af; }

#yahoo .imgbtn { background-image: url(../images/sso/yahoo.png); background-size: 30px; }

#linkedin { background-color:#00A0DC; }

#linkedin .imgbtn { background-image: url(../images/sso/linkedin.png); }

#dropbox { background-color:#007ee6; }

#dropbox .imgbtn { background-image: url(../images/sso/dropbox.png); background-size: 30px; }

You can change the logo and/or background color of the login buttons for the Oauth 2.0 authentication methods.

Each pair of entries corresponds to one authentication method. The ID (#google, #facebook) must match the Virtual Path established in the Oauth 2.0 Authentication Method Settings. With the installation, these parameters are matching by default, but make sure to change it in both places if you do.

The first line of each pair defines the button color, and the second one the button image.

Read more:

· Entering Credentials

· Processing End-User Credentials

· Authentication Methods

· Windows Logon

· RADIUS

· OAuth 2.0

· OAuth2Models.ini

· External DLL

· Authentication API

5.8.3.4. External DLL

Thinfinity VirtualUI allows you to integrate your own custom authentication method. In order to do this, use the Thinfinity VirtualUI Authentication API.

The External DLL authentication method can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add an External DLL authentication method you will be required to reference the .dll in the 'External DLL' option. Check the complete reference in the External DLL Authentication Method Settings.

The user definition is completed through the mapping between the user ID returned by the external DLL and an Active Directory Objects mapped for this Authentication ID Mask.

Read more:

· Authentication API

5.8.3.4.1. Authentication API

Thinfinity VirtualUI provides you with an API that you can use to develop your own authentication method and integrate it with VirtualUI.

Choose the code sample of your language of preference and add it to your implementation:

Delphi:

function ValidateUser(

const UserName, Password, Metadata: PWideChar;

SecurityRole, WinUser, WinPass, CustomData: PWideChar;

var Handled: Boolean): Cardinal; stdcall;

Input:

Username & Password

The credentials that you are trying to validate with the external authentication

Metadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

SecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

WinUser, WinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

CustomData

(optional) Data for passing on to the application

Handled

Returns whether the login could be handled by the DLL.

C++:

THINFINITY_API DWORD __stdcall ValidateUser(LPWSTR lpUserName, LPWSTR lpPassword, LPWSTR lpMetadata, LPWSTR lpSecurityRole, LPWSTR lpWinUser, LPWSTR lpWinPass, LPWSTR lpCustomData,

PBOOLEAN pHandled)

Input:

lpUserName & lpPassword

The credentials that you are trying to validate with the external authentication

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

C#:

[DllExport("ValidateUser", CallingConvention = CallingConvention.StdCall)] [return: MarshalAs(UnmanagedType.I4)] public static Int32 ValidateUser( [In, MarshalAs(UnmanagedType.LPWStr)] string lpUserName, [In, MarshalAs(UnmanagedType.LPWStr)] string lpPassword, [In, MarshalAs(UnmanagedType.LPWStr)] string lpMetadata,

[In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpSecurityRole, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpWinUser, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpWinPass, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpCustomData, [Out] bool pHandled);

Input:

lpUserName & lpPassword

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

The authenticated username

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

Read more:

· External DLL

5.9. Virtualization

In Thinfinity VirtualUI, each application instance may run under a unique Windows User ID or under a shared one. In the first case, the application may access private folders and private registry entries but, as most applications provide their own credential system (usually based on a database), it is a common practice to run the application instance under a single shared Windows User ID. In this case, all application instances share the same user profile’s folders and the same “current user” key in the registry.

Additionally, in both cases, all users may have access to shared folders that it might be desirable to hide from them.

Thinfinity VirtualUI addresses these potential drawbacks by providing the File System and Registry Virtualization feature.

The main purposes of the Registry and File System virtualization are:

· To show only relevant folders.

· To provide private folders based on the application's credential system.

· To provide registry keys based on the application's credential system.

Read more:

· File System Virtualization

· Registry Virtualization

· Implementing Virtualization in Your Application

5.9.1. File System Virtualization

File System Virtualization helps developers publish only relevant shared folders and provide authentication-based private folders. Additionally, shared folders can be redirected to safer places in the disk and/or be write protected.

Virtualization involves two steps. The first one is the File System mapping design, when the developer creates the relationship between real paths and the redirected path tree that the end-user will see and access. The second one, the inclusion of the created mapping definition into the application program.

The file system mapping definition is a set of one to one redirection rules that link a real folder to the redirected folder path.

There are two types of redirection:

· Shared: for all connected users. It can be defined as readonly.

· Private: for a single identified user.

The configuration is done through the The File System Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

· Creating File System Redirections

· The .vidr Files

· Testing the File System Virtualization

· Registry Virtualization

· Implementing Virtualization in Your Application

5.9.1.1. Creating File System Redirections

In order to add a path in the Virtualization Editor, right click on the main area of the screen and choose 'New Path...'.

This will bring up the 'Edit Directory' dialog.

Field

Description

Mode

Choose 'Shared' if you want this mapping to apply to all users.

Choose 'Private' if you only want this mapping to apply to a single user.

Read Only

Only available for Shared Mode. Check this option to make the mapped directory read only for the user.

5.9.1.2. The .vdir Files

Once you are done adding, editing and/or deleting paths, save this configuration by selecting 'File' - 'Save' in the main menu of the Filesystem Virtualization Editor. This configuration will be stored in a vdir file. The Filesystem Virtualization Editor allows you to create different vdir files to be used in your application.

Read more:

· Creating File System Redirections

· Testing the File System Virtualization

· Implementing Virtualization in Your Application

5.9.1.3. Testing the File System Virtualization

You can test the Filesystem virtualization outside VirtualUI (the virtualization service must be running, though). In order to test the Filesystem virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the files stored for each user are isolated.

Program

Choose a program with which to test the Filesystem virtualization. It has to be a program capable of opening files.

After selecting a user and a program to test, press the 'Launch' button. When you access the Windows file system through this application, you should only be seeing the mapped directories, by their original names.

Read more:

· Creating File System Redirections

· The .vidr Files

· Implementing Virtualization in Your Application

5.9.2. Registry Virtualization

Registry Virtualization allows developers to store end-user information in the Windows Registry in a secure and isolated way and to provide authentication-based registry entries.

Additionally, shared registry entries can be redirected to safer places in the Windows Registry.

Similarly to File System Virtualization, Registry Virtualization also involves two steps. The first one is the mapping definition, when the developer creates the relationship between an original registry entry and a redirected registry entry. The second one, the inclusion of the created mapping definition into the application program.

The registry mapping definition is a set of one to one redirection rules that link a real entry to the redirected entry.

There are two types of redirection:

· Shared: for all connected users.

· Private: for a single identified user.

Private redirection entries include the identified user ID appended to the redirected entry.

The configuration is done through the Registry Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

· Creating Registry Redirections

· The .vreg Files

· Testing Registry Virtualization

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.1. Creating Registry Redirections

In order to add a registry redirection, right click on one of the Server trees and choose 'Add Redirection'.

This will bring up the 'Edit Key Redirection' dialog:

Field

Description

Mode

Choose 'Shared' if you want this key redirection to apply to all users.

Choose 'Private' if you only want this key redirection to apply to a single user.

Source

Choose the source registry key you want to redirect.

Destination

Choose a registry destination key.

Editing Redirections

In order to edit a key redirection, right click on it and choose 'Edit Redirection'.

You will then be able to edit the redirection in the 'Edit Key Redirection' dialog.

Deleting Redirections

In order to delete a redirection, right click on it and choose 'Delete Redirection'.

Read more:

· Testing Registry Virtualization

· The .vreg Files

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.2. The .vreg Files

Once you are done adding, editing and/or deleting redirections, save this configuration by selecting 'File' - 'Save' in the main menu of the Registry Virtualization Editor. This configuration will be stored in a vreg file. The Registry Virtualization Editor allows you to create different vreg files to be used with the product.

Read more:

· Creating Registry Redirections

· Testing Registry Virtualization

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.3. Testing Registry Virtualization

In order to test the registry virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the registry changes stored for each user are isolated.

Program

Choose a program with which to test the registry virtualization. It has to be a program that uses the registry.

After selecting a user and a program from the test, press the 'Launch' button. This will open the selected application and create a unique key for the user in the redirected key. All the activity of this application in the registry for the source key will be reflected in the redirected key.

Read more:

· Creating Registry Redirections

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.3. Implementing Virtualization in Your Application

In order to apply the virtualization filters created with the Filesystem Virtualization Editor or the Registry Virtualization Editor, you have to add some code to your application.

After virtualui.Start(), load and apply the created filters with the current user credentials

Delphi:

virtualui.RegistryFilter.User := 'user identification';

virtualui.RegistryFilter.CfgFile := 'file.vreg';

virtualui.RegistryFilter.Active := true;

virtualui.FilesystemFilter.User := 'user identification';

virtualui.FilesystemFilter.CfgFile := 'file.vdir';

virtualui.FilesystemFilter.Active := true;

C#:

virtualui.Start();

virtualui.RegistryFilter().User = “user identification”;

virtualui.RegistryFilter().CfgFile = “file.vreg”;

virtualui.RegistryFilter().Active = True;

virtualui.FilesystemFilter().User = “user identification”;

virtualui.FilesystemFilter().CfgFile = “file.vdir”;

virtualui.FilesystemFilter().Active = True;

C++:

virtualui->Start();

virtualui->RegistryFilter()->User = “user identification”;

virtualui->RegistryFilter()->CfgFile = “file.vreg”;

virtualui->RegistryFilter()->Active = True;

virtualui->FilesystemFilter()->User = “user identification”;

virtualui->FilesystemFilter()->CfgFile = “file.vdir”;

virtualui->FilesystemFilter()->Active = True;

In order to disable registry or filesystem filtering, set the Active property to false.

Read more:

· File System Virtualization

· Registry Virtualization

5.10. OEM Licensing

If your product qualifies for OEM licensing, we will provide you with a Thinfinity VirtualUI OEM Licensing Library that enables OEM-licensed Companies to create and revoke end-user Thinfinity VirtualUI licenses.

There are two prerequisites:

· The application that uses the OEM Licensing Library (Thinfinity.VirtualUI.OEM.dll) must be digitally signed.

· You must have a valid OEM key.

To get an OEM key, you must provide Cybele Software with a digital certificate's thumbprint. On each licensing request, three parameters will be used to validate the requestor:

· The OEM-licensed Company's e-mail.

· The provided OEM key.

· The digital certificate's fingerprint, taken from the digital certificate that signs the executable making the OEM library call.

The generated OEM key and the digital certificate's thumbprint, along with your customer identification (e-mail), will be used to securely validate the licensing requests your application will make.

Read more:

· How to Create and Revoke Licenses

· Creating Licenses

· Revoking Licenses

5.10.1. How to Create and Revoke Licenses

visThe OEM library provides two functions to create a license and two functions to revoke a license:

· CreateLicenseW (Unicode version) and CreateLicenseA (ANSI version).

· RevokeLicenseW (Unicode version) and RevokeLicenseA (ANSI version).

In order to test the license creation and activation process, you can enable the SandboxMode in the OEM.ini file.

[LICENSE]

SandboxMode = True

The OEM.ini file should be placed in both the bin32 and bin64 paths under the Thinfinity VirtualUI installation folder and in the user's application executable file folder.

The software will first look for the file in the executable's directory (either the application's or any server's). If it doesn't find it there, there are two alternatives: - For the virtualizer, which is in ibin, it will search in bin64 and, afterwards, in bin32 - For the rest of the cases. it searches for it in the parent directory. That is, if something runs in bin32 or bin64 it can use an oem.ini from their parent directory.

Adding External Methods

In a Delphi program we must first declare the external functions in their ANSI or Unicode version.

ANSI:

function CreateLicenseA(const email, oemkey, customerid: PAnsiChar;

units: DWORD; serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseA(const email, oemkey, serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

Unicode:

function CreateLicenseW(const email, oemkey, customerid: PWideChar;

units: DWORD; serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseW(const email, oemkey, serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

In order to access external library functions in a C# program, please declare:

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int CreateLicenseW(string email, string oemkey,

string customerid, int units, StringBuilder serial);

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int RevokeLicenseW(string email, string oemkey, string serial);

Read more:

· Creating Licenses

· Revoking Licenses

5.10.1.1. Creating Licenses

In order to create a new Thinfinity VirtualUI license you must use the corresponding CreateLicense method with the following parameters:

Email

OEM-licensed Company´s e-mail

OEMKey

OEM Key.

CustomerID

Arbitrary customer identification for the new license. This can be an e-mail address, a serial number or any other customer identification.

Units

Number of units to enable in this license. Each unit contains a predefined number of concurrent users. If your OEM license has 5 users per unit, and you assign 2 units to the product license, the customer will have 10 concurrent users in total.

Serial

out

Serial number of the successfully generated license.

A call to the CreateLicense function will return one of the following error codes:

No error. The "Serial" parameter will contain the generated serial number.

-1

General error in license server.

-2

Incorrect Email or OEM Key.

-3

No more units available.

-4

OEM License expired.

-5

General error. Cannot create license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

The following example shows how to create a license using Delphi. Please note that you must replace CreateLicenseW by CreateLicenseA when using ANSI chars.

procedure CreateLicense;

var

result: Integer;

serial: WideString;

begin

serial := StringOfChar(' ', 128);

result := CreateLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'),

PChar('CUSTOMER_ID'), UNIT_COUNT, PWideChar(serial)); // Check result

end;

And this is how you create it using C#:

private void CreateLicense()

{

StringBuilder sn = new StringBuilder(128);

int result = CreateLicenseW("OEM_EMAIL", "OEM_KEY",

"CUSTOMER_ID", UNIT_COUNT), sn);

string serial = "";

// Check result

if (result == 0)

{

serial = sn.ToString().Trim();

}

else

{

// Error

}

Note: In all these examples, please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration, 'CUSTOMER_ID' with the Customer identification and 'UNIT_COUNT' with the desired value.

Read more:

· How to Create and Revoke Licenses

· Revoking Licenses

5.10.1.2. Revoking Licenses

The RevokeLicense function is used to revoke a previously generated license. These are its parameters:

Email

OEM-licensed Company's e-mail

OEMKey

OEM License Key.

Serial

Serial number to revoke.

This function will return one of the following error codes:

No error. The license was revoked.

-1

General error in license server.

-2

Incorrect Email or OEMKey.

-3

Incorrect Serial number.

-4

Incorrect Serial number.

-5

General error. Cannot revoke license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-50

Error in HTTP request.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

Here's how to revoke a license using Delphi:

procedure RevokeLicense;

var result: Integer;

begin

result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER'); // Check result

end;

And here's how to revoke a license using C#:

private void RevokeLicense() {

int result = RevokeLicenseW("OEM_EMAIL", "OEM_KEY", "SERIAL_NUMBER"); // Check result

}

Note: Please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration information, and replace 'SERIAL_NUMBER' with the Serial to revoke.

Read more:

· How to Create and Revoke Licenses

· Creating Licenses

5.11. Silent Install Options

The VirtulalUI installation can be run in 'silent' mode, that is, without the need for user interaction. This can be useful if you are a system administrator and you want to automate the VirtualUI installation or if you are deploying it over your local network. Also, if you have an OEM Licensing model you will probably use a silent install.

Thinfinity VirtualUI Line Switches

In order to perform a silent installation, use this command line:

c:\Thinfinity_VirtualUI_Setup_x64.exe /s /v/qn

These are additional command line switches that you can pass on to the setup file:

Variable

Description

Default value

VFMX_SERVER_MODE

Determines whether the server components will be installed

TRUE

VFMX_DEV_MODE

Determines whether the development components will be installed

TRUE

VIRTUALIZATION

Determines whether the Virtualization components will be installed. In order for this option to be enabled, VFMX_SERVER_MODE cannot be FALSE.

FALSE

STDLBMODE

Values:

- LBMODE: Load balancing mode

- STDMODE: Standard mode.

STDMODE

SM_TYPE

Values:

- SM_Complete : Installs Server and Gateway components

- SM_Broker: Installs only Server components

- SM_Gateway: Installs only Gateway components.

Note: In order for this option to be enabled, STDLBMODE has to be set to LBMODE.

EMAIL

Complete this variable with your registration email. Also make sure to include the SERIAL parameter in order for the registration to work.

SERIAL

Complete this variable with your registration serial. Also make sure to include the EMAIL parameter in order for the registration to work.

The VFMX_SERVER_MODE, VFMX_DEV_MODE and VIRTUALIZATION parameters correspond to these installation wizard options:

The STDLBMODE and SM_TYPE parameters correspond to these installation wizard options:

The default installation will install Thinfinity VirtualUI Server in standard mode and the development components, but not the virtualization components.

Examples

· Installing Thinfinity VirtualUI in Standard Mode with Virtualization Components and without Development Environment:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VIRTUALIZATION=\"TRUE\" VFMX_DEV_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI Development environment only:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VFMX_SERVER_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI in Load Balancing mode using Gateway and Server roles and including licensing:

C:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn EMAIL=\"myemail@mydomain.com\" SERIAL=\"45EI-09IJ-OOA6-3GH5-IT5E-E4ER-KIP9-A669\" STDLBMODE=\"LBMODE\" SM_TYPE=\"SM_Complete\""

Scaling and Load Balancing

Scaling and load balancing come into play when one machine is not capable of managing all the required resources. Too many concurrent connections or virtualized application that handle a lot of graphics, sound or other elements that require a great availability of resources may cause an overload.

Thinfinity VirtualUI provides components that allow you to distribute the workload across multiple Windows sessions, as well as multiple servers. You can scale the application availability in terms of applications instances —and user accesses— and failover scenarios in order to achieve optimal resource utilization and avoid overload.

Some of the benefits of load balancing:

· Avoids the overload by distributing the connections among different servers

· Minimizes response time

· More reliability (redundancy)

· Failover control

· Installing Components

· Enabling Multiple RDS Accounts

· Configuring Load Balancing

Scaling and Load Balancing Configurations

If you arrive to the conclusion that your Thinfinity VirtualUI environment would benefit from using Load Balancing, you can choose between different scenarios. This decision is an essential step in planning the hardware scheme and configuring the system to work in a distributed way.

Scenario 1: Multiple RDS accounts

This architecture involves only one computer. Each RDS session creates a Server instance which can, in turn, handle application instances separately. The VirtualUI Broker administrates the server instances: checks up on them to see if they are functional, and works together with the Gateway to distribute the connections.

Scenario 2: Multiple Servers with Load Balancing

In this simple scenario, a single Gateway distributes the connection load between a number of Servers.

Scenario 3: Multiple Gateways and Servers with Load Balancing

This example combines a external load balancing DNS Server with multiple Gateways. The scheme is composed by multiple Servers, multiple Gateways and the DNS Server, its domain name associated to all the available Gateways' IPs.

Scenario 4: Multiple RDS accounts and multiple Servers with Load Balancing

Combine load balancing with multiple RDS sessions to get the most out of your architecture.

Read more:

· Installing Components

· Enabling Multiple RDS Accounts

· Configuring Load Balancing

Installing components

In this section you will learn how to set up Thinfinity VirtualUI's components in a load-balancing network configuration.

Choose the Load Balancing mode in the Server Installation Options screen:

Two or more servers will participate in the load balancing/fault-tolerance scenario. These are the two possible roles for an installation:

Reverse Gateway Role: Under this role, VirtualUI responds to all web-page requests and, when a connection is solicited, it selects the appropriate Brokerto forward that request to.

In case any established connection fails, or a Broker falls down, the Gateway will be able to reconnect to the Broker that has the highest availability at the moment.

All the system settings and profiles are centralized and shared between the Servers.

Broker, Web Services and Virtualization Services Role: Under this role, VirtualUI only processes forwarded connections. The Broker is responsible for establishing and processing the connections assigned by the Gateway. A Broker Role installation also includes the option to enable multiple RDS accounts.

Before configuring a distributed environment, you should go over some steps:

1. Choose out of the possible Scaling and Load Balancing Configurations the one that best fits your needs.

2. Plan which machines will work under the Broker Role, and which under the Gateway Role and DNS Servers.

3. Make sure all the Gateway Roles IP addresses are public to the web browsers that will access Thinfinity VirtualUI.

Read more:

· Enabling Multiple RDS Accounts

· Configuring Load Balancing

Enabling Multiple RDS Accounts

In order to enable multiple RDS accounts, go to the 'Sessions' tab and and select the "One Browser per Windows session: option:

One Browser per Session options

Options

Description

Allow running third-party applications

Check this option to enable Thinfinity VirtualUI to run directly under a Windows Interactive session.

Use these credentials

Check this option to enable Thinfinity VirtualUI to run under a specific Windows account.

User name

Enter the username for the Remote Desktop Services session you want Thinfinity VirtualUI to run applications under.

Password

Enter the password for the Remote Desktop Services session you want Thinfinity VirtualUI to run applications under.

Test

Test the credentials entered to verify that the username and password are correct and can access RDS.

Use VirtualUI's logged-in credentials

Check this option to enable Thinfinity VirtualUI to run under the logged in User's credentials.

The accounts must have administrator permissions or should have access to the following folders :

* FileSystem:

- C:\ProgramData\Cybele Software\Thinfinity\VirtualUI

- C:\Users\Public\Documents\Cybele Software\Thinfinity\VirtualUI

* RDP Access to the Machine is also required for the configured accounts to properly work.

Starting from 2.5.30.0, VirtualUI includes two different types of session handling modes. These options are only availble if you select the "Run under this account" option.

Note: In order to use this feature, Thinfinity VirtualUI must be installed in a Windows Server where the Remote Desktop Session Host (RD Session Host) role service is installed.

Read more:

· Scaling and Load Balancing

Configuring Load Balancing

In order to configure a load balancing scenario, you need at least one Gateway installation and two Server installations.

Configuring the Gateway Roles

Under this role, VirtualUI responds to all web-page requests and, when a connection is solicited, it selects the appropriate Server to forward that request to.

To configure the Gateway, open the Gateway Manager. Set the IP and port where the Gateway will run. If you only have one gateway, this is where the users will connect to. If you use more than one Gateway in your architecture, you will use this IP in the DNS server you set up to distribute the connection between the Gateways.

Also, set the Network ID. All the Gateway and Server installations involved in a Load Balancing architecture share the same network ID.

Configuring the Server Roles

Under this role, VirtualUI only processes forwarded connections. The Broker is responsible for establishing and processing the connections assigned by the Gateway.

To configure the Broker, open the Server Manager and go the 'Broker' tab. Press the 'Add' button to add a gateway to the Gateway List.

This means that now this server's resources can be accessed through the listed gateways.

· Make sure that the Network ID is the same for all the gateways and servers involved in this load balancing architecture.

Then, go to the 'Applications' tab:

Set the 'Database Path' field in a network location that you can access from the other Server role installations.

Once you share the database path, all the information in the 'Applications' tab will be shared with other VirtualUI installations. Make sure you modify the Applications information from one installation at a time, as all changes will be reflected in the other installations.

Also, make sure all the Gateways' IPs are public to the locations that will access Thinfinity VirtualUI through a web browser.

· Configuring the 'General' tab

· Configuring the 'Sessions' tab

· Configuring the 'Applications' tab

· Configuring the 'Licenses' tab

Sharing your License

Now that all your instances are working in Load Balancing , it's time to share your license over multiple servers.

The License Server Manager lets you register your licenses remotely, and you can use it to share your licenses over multiple servers across multiple installations .

Read more:

· Installing the License Server Manager

· Add a License

· Sharing your License over multiple Severs

Installing the License Server Manager

In order to install the License Server Manager, please , follow these steps :

1.Download the installer from this link:

http://www.cybelesoft.com/downloads

2. Execute the installer on the target machine.

3. The InstallShield Wizard will be displayed. Click on "Next".

4. Select "I accept the terms in the license agreement", and click on "Next".

5. Click on "Install".

6. Once the installation is complete, you will be given the option to start the License Server Manager .

Read more:

· Add a License

· Sharing your License over multiple Severs

Add a Licence

Pressing the 'Add' button and the appropriate product will open the Product Registration Wizard. In this case , we are going to chose "Thinfinity VirtualUI 2.5":

Select this option to receive a 30 day trial serial.

Select this option to register your Cybele Software, Inc product.

Select this option to register a license offline.

Get a new Trial Serial Number

This option will allow you to request a 30 day trial license with unlimited access. You will be prompt to enter a valid name and e-mail address.

Once you filled this information hit 'Next' and check your in-box for the serial key.

Read more:

· Activate a Serial Number Online

· Activate a Serial Number Offline

Activate a Serial Number Online

This is how the "Activate a Serial Number Online" windows looks:

E-mail

Enter the e-mail address you've registered with.

Serial

Enter the serial information we provided you.

Licensing Server URL

If you installed the License Server administrator, enter the License Server URL. Otherwise leave this blank.

If the license information is incorrect, you will see this warning: "The license information is invalid". In this case, please verify the following:

- That you are entering the exact email and Serial number sent to you. The best practice to do this correctly is to copy - paste it, being careful not to include any space after or before.

- That you have a working internet connection. If you intend to install it in a machine with no internet connection, you can try the Offline activation. If you have internet restrictions because of a proxy, please verify the license server manager has the proxy's information configured in the Communications tab.

If you need additional help, contact us.

If the license information is correct, the License Manager will let you know that "The new license has been installed successfully" and its information will be show in the License Manager.

Read more:

· Get a new Trial Serial Number

· Activate a Serial Number Offline

Activate a Serial Number Offline

Manual Activation is an activation option only for those cases when you want to activate your product in a machine that has no internet connection, or an internet connection restricted by heavy security policies that block a regular activation.

· If your internet restrictions are caused by a proxy, you will need to add the proxy information in the Communications tab

Once you've selected Activate a Serial Number Offline. You will see the following pop up:

Read more:

Sharing your License over multiple Severs

Now that we have added a license to the License Server Manager, we need to bind that License to all the Brokers that are Load Balanced.

· In order to do this, you need to open the Thinfinity VirtualUI Server manager, navigate to the "Licenses" tab , and click on the "Manage" button.

· Click on the "Add" button :

· Select "Activate a Serial Number online" and press "Next" :

· Type in your license information ( E-mail + Serial ) , and add the License Server URL and Port number in the "Licensing Server URL" field :

· If the License Server is available and has that Serial number registered, then the license will be registered successfully :

· Repeat the proccess for all the Brokers you want to share the same license.

Read more:

· Installing the License Server Manager

· Add a License

Enhanced Browser and DPI Support

Among the wide range of valid resolutions that Thinfinity VirtualUI offers, the most commonly used —for its flexibility and simplicity— is “Fit to Browser”. This configuration allows you to adjust the remote application to fit the available browser size. However, when it comes to accessing a desktop from different devices, the sometimes huge differences between screen sizes and pixel resolutions (i.e. iPhone 4 vs a 27 inch iMac Retina Display) make it impossible to have a simple rule to determine the best remote desktop size. Even when the application is adjusting properly to the available size, the screen rendered might still look tiny or disproportionate, making the user experience not as satisfactory as expected.

Tailoring "Fit to Browser"

Now, using a new configurable browser detection ruleset, we can tailor the way we want to see of the remote desktop/application on every device. This ruleset allows you to specify rules that will detect the web browser, device and display characteristics, and set parameters that adjust the remote desktop/application resolution according to your own taste.

The main characteristics that need to be taken into account are:

· The browser User Agent, that tells about the web browser and device

· The device pixel ratio, that tells about the real display resolution

· The device display size

· The display orientation (landscape or portrait)

The browser detection ruleset is stored in a file with entries that contain specifications (rules) that match general or specific devices. Each entry (model) can inherit matching parameters (properties) from a more general model. For example, you can define an iOS model and an iPhone4 can inherit the iOS model properties.

A default ruleset file named BrowserRules.ini is installed in the Thinfinity VirtualUI program folder. Then, if it doesn’t exist there yet, it is copied to "\programData\Cybele Software\Thinfinity\VirtualUI\" and renamed as Thinfinity.VirtualUI.BrowserRules.ini. You can safely customize this file as it won’t be overridden with a program update.

The structure of this file is as follow:

[default]
min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 1
[mobile]
parent-model = default
match-mobile = true
max-device-pixel-ratio = 2

Note: for these settings to apply, the connection’s ‘Resolution’ property must be set to ‘Fit to browser’, and the BrowserRules.ini file must be pointed in the application profile.

Configure this setting in for your application in the 'General' tab of the Application Profile, or the 'General' tab of the Application Profile in the development server.

Read more:

· Model Inheritance

· Property Reference

· The Calculation Process

· Examples

Model Inheritance

A section defines a model, and each model contains a set of properties divided in two groups: matching properties and applying properties.

Models are organized in an inheritance tree. The relationship between models is defined by a special property rule called parent-model, present in all models except in the [default] model, which is the tree's root node and includes some basic properties.

Every other model must directly or indirectly inherit from the [default] model. Also, each model contains its own rules that match general or specific devices, and inherits all specifications (including matching parameters) from its ancestors.

When more than one criteria is met for a device, a scoring system is used to resolve this conflict.

This is the in-the-box models tree:

Read more:

Property Reference

Properties can be divided in two groups: matching properties and applying properties.

Matching properties are those used to test the browser and device properties (such as the browser user agent, the device pixel ratio, the display orientation width and height, etc.) in order to choose the best model for each case.

match-device-pixel-ratio

Matches any device with a specific pixel ratio.

match-mobile

Matches any mobile device.

match-orientation

Matches any device with the specified orientation: landscape or portrait.

match-screen-height-range

Matches any device with a screen height in the specified range. This range is expressed as From-To (for example, 900-1200).

match-screen-width-range

Matches any device with a screen width in the specified range. This range is expressed as From-To (for example, 400-600).

match-screen-height

Matches any device with a specified screen height.

match-screen-width

Matches any device with a specified screen width.

match-user-agent

Matches devices by comparing the device browser user agent to the string value supplied. This string is a regular expression.

Applying properties are those used to determine the final size and resolution.

Use the parent-model property to set the parent model:

parent-model

Establish the parent model for this model.

The following properties deal with the display resolution:

device-pixel-ratio

Overrides the original device pixel ratio, scaling the content accordingly.

max-device-pixel-ratio

This property determines the maximum device pixel ratio accepted. The lesser of the device’s device pixel ratio and this value is applied to scale the display.

The following properties deal with the screen size of the remote desktop, in pixels. You can determine it by setting the actual height and width, or by establishing maximum and minimum values for these properties.

height

Remote desktop height.

width

Remote desktop width.

max-height

Remote desktop maximum height.

max-width

Remote desktop maximum width.

min-height

Remote desktop minimum height.

min-width

Remote desktop minimum width.

The following properties allow you to specify device screen areas that will never be used for displaying the remote connection, such as when a browser or device bar cannot be hidden and uses up screen space. These margins will be excluded for screen size calculations.

margin-left

Width of an area at the left of the device screen that will not be used for displaying the remote desktop.

margin-bottom

Width of an area at the bottom of the device screen that will not be used for displaying the connection.

margin-right

Width of an area at the right of the device screen that will not be used for displaying the connection.

margin-top

Width of an area at the top of the device screen that will not be used for displaying the connection.

Miscellaneous properties:

use-full-screen

For mobile only. If the device’s browser supports the full-screen mode, this property indicates the remote desktop size should be calculated to occupy the whole screen. When not in full screen, the content will be scaled.

Read more:

· The Calculation Process

· Examples

The Calculation Process

In order to choose a model from the ruleset, Thinfinity uses the client device type, dimensions, resolution, orientation and browser:

1. If match-mobile exists, it tests if device is a mobile.

2. If match-user-agent exists, it tests the browser’s User Agent.

3. If match-device-pixel-ratio exists, it tests the device’s pixel ratio.

4. If match-orientation exists, it tests the device’s orientation.

5. If match-screen-width-range or match-screen-height-range exist, it tests to see if the screen size is in range.

6. If match-screen-width or match-screen-height exist, it tests the exact screen size.

Once the model is selected, the parameters are applied in this way:

1. If the width and height properties exist, then it applies them.

2. If the browser width is less than the min-width, it applies min-width.

3. If the browser height is less than the min-height, it applies min-height.

4. If the browser width is greater than the max-width, it applies max-width.

5. If the browser height is greater than the max-height, it applies max-height.

6. If a specific device-pixel-ratio was specified, it applies it.

7. If a max-device-ratio was specified, it takes the minimum of the real device pixel ratio and max-device-ratio property and applies it.

Read more:

Examples

This example shows a possible ruleset and how it will affect different devices:

[default]
min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 1
[mobile]
parent-model = default
match-mobile = true
max-device-pixel-ratio = 2
[ipad]
parent-model = mobile
match-user-agent = ipad
[iphone4]
parent-model = mobile
match-user-agent = iphone
match-screen-width = 480
match-screen-height = 320
device-pixel-ratio = 1.5

In this case, when connecting with an ipad, the following models will be matched:

[default]: This model applies to all devices.

[mobile]: The ipad will match the match-mobile property.

[ipad]: The ipad will match the user agent keyword ‘ipad’ specified in the match-user-agent property.

The resulting properties for this device will be:

min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 2

Using the same ruleset, when connecting with an iphone4, the following models will be matched:

[default]: This model applies to all devices.

[mobile]: The iphone will match the match-mobile property.

[iphone4]: The ipad will match the user agent keyword ‘iphone’ specified in the match-user-agent property, together with the match-screen-width and match-screen-height properties. An iphone6, with a screen width of 667px, and a screen height of 375px, would match the ‘iphone’ user agent keyword, but not the size.

The resulting properties for this device will be:

min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 2
device-pixel-ratio = 1.5

One-Time URL

Thinfinity VirtualUI offers a special access method called “One-Time URL”. This mechanism was designed to create a temporary, unique url to provide one-time access to a specific application. This temporary url is disposed as soon as it is used or after a specified period of time has elapsed.

These are the main scenarios where the One-Time URL access method is most useful:

· External authentication methods.

· One-time invitations to run a program (i.e. application demos/presentations).

Read more:

· How it Works

· Creating a One-Time URL

How it Works

The One-Time URL is a unique, disposable URL leading to a specific VirtualUI application. What makes it useful is that it allows for passing credentials and/or custom data to the application through an independent secure channel, hidden to the end user.

A usual scenario involves a backend service (ie. a web server), where the user’s credentials are validated. This backend service communicates with a VirtualUI Server to request the creation of a One-Time URL, passing information about the application to run, credentials and custom data. This information is stored temporarily and indexed by a unique access key. Also a random passcode is created and used to encrypt the stored information. This access key and passcode are returned to the backend service to build the final One-Time URL.

Once the user is directed to the provided URL (automatically or by clicking on a link), VirtualUI validates the access key and passcode and starts the application passing the associated data. Finally, this key and associated data are removed from memory and therefore the URL becomes invalid. The same happens if the URL was not used for the amount of time specified in the creation request.

Read more:

· Creating a One-Time URL

Creating a One-Time URL

The VirtualUI Server processes a One-Time URL creation request in the form of an http(s) request, as follows:

serverurl + "/ws/oturl/get?apikey=" + apikey + "&accesskey=" + accesskey +

"&virtualpath=" + virtualpath

"&userid=" + userid + "&password=" + password +

"&customdata=" + customData +

"&plen=" + passlen + "&expires=" + expires

"&arguments=" + arguments ,

where:

If the request is unsuccessful, the following HTTP codes can be received:

400: Invalid parameters

401: Userid/password invalid

If the request is successful, the HTTP call returns a 200 HTTP status code, and a JSON consisting of two fields:

With this information, the backend can build the final URL, following this format:

Here's an example that uses the JSON shown above:

Passing Command Line Arguments to VirtualUI Apps

An application can accept command line arguments when invoked. This allows the user to send additional information to the application when it is executed.

When an application is launched, the OS passes the command line arguments to the application as a collection of string values, using a white-space as separator.

Applications receive external arguments on a regular basis: when you open a document by clicking on its icon, the OS selects the associated executable program and calls it, sending the full document filename to the program as an argument.

Thinfinity VirtualUI allows you to send external arguments to applications in a transparent way, which works exactly like sending arguments from the command line.

Read more:

Setting Command Line Arguments in the Application Profile

bt - current position

Thinfinity VirtualUI enables external argument definition from the VirtualUI Server Manager. When you create an application profile, you can specify the execution arguments in the General tab panel of the Application Profiles editor.

These arguments will be received by the application as a list of string values, using the white-space character as argument delimiter.

In Delphi you can get command line arguments using the System.ParamCount and System.ParamStr methods. ParamCount returns the number of arguments, and ParamStr(index) returns each argument, with ParamStr(0) always being the path and name of the invoked program. Here is a way you can show the received arguments list:

In C++, both the argument counter and the argument list will be received in the two main() function arguments. Like in Delphi, the first argument in the string array is the path and name of the program itself:

You can also write the main function header in this way:

Unlike Delphi and C++, C# excludes the name and path of the program from the arguments collection. Also, C# offers two ways to get the arguments, by using a traditional for:

or by using the foreach:

Read more:

Sending Command Line Arguments in the VirtualUI URL

VirtualUI allows you to send external arguments in the url. Instead of passing static arguments from the application profile definition, using this feature you can send dynamic application arguments in a simple way. The only requirement to be met is that the arguments must be url encoded.

To build the url you need:

· The communication protocol (http or https).

· The Thinfinity VirtualUI server domain or IP address, and port.

· The application virtual path.

Build the url like this:

protocol://server.address:port/virtualpath/?arguments

As an example, we will send the "one", "two" and "three" argument values to the TestArguments program:

http://192.168.0.229:6580/TestArguments/?one%20two%20three

The following image shows the submit result:

Read more:

Building the URL in Javascript

When necessary, modern browsers encode URLs automatically, but it is convenient to do it by code. The Javascript lines below show how to build the URL used in the previous example:

var buildURL = function(server, virtualpath, arguments) {

return server + "/" + virtualpath + "/" + encodeURIComponent(arguments.join(' '));

}

var baseURL = "http://192.168.0.229:6580/";

var applicationPath = "TestArguments";

var arguments = ["one", "two", "three"];

var url = buildURL(baseURL, applicationPath, arguments);

Read more:

Combining Application Profile and URL Command Line Arguments

If you have defined command line arguments in the application profile and need to send new arguments to the application by url, don't worry. Thinfinity VirtualUI merges both argument lists, first adding the application profile arguments, and then the arguments that were passed in the url.

Read more:

Advanced Features

Take a look at the Thinfinity VirtualUI advanced features:

· Enhanced Browser and DPI Support

· End-User Authentication

· One-Time URL

· Passing Command Line Arguments to VirtualUI Apps

· Recording and Playing Sessions

· Scaling and Load Balancing

· Printing

· Virtualization

· OEM Licensing

5.6. Recover Browser Information with BrowserInfo

When using VirtualUI, it is often necessary to be aware of some features and capabilities of the device from which end users are accessing our application.

The VirtualUI class has a property called BrowserInfo, which contains data about the browser being used. This information can assist us in delivering the best possible user experience.

In the list below we will find a detailed reference of the information that BrowserInfo will deliver:

Attribute

Description

Username

Returns the logged-on username.

IPAddress

Returns the client's ip address.

Location

Returns the URL of the current application.

UniqueBrowserId

Identifies an instance of a browser. Each time an end-user opens the application from a different browser window, this identifier will be have a different value.

UserAgent

Returns the browser's User Agent string. This value is very important to identify which browser type is used, if the remote device is a mobile, etc.

Information relative to the available screen space:

Attribute

Description

BrowserWidth

Returns the width of the HTML element containing the VirtualUI viewer, in pixels.

BrowserHeigth

Returns the height of the HTML element containing the VirtualUI viewer, in pixels.

ScreenWidth

Returns the width of the end-user's device screen, in pixels.

ScreenHeight

Returns the height of the end-user's device screen, in pixels.

ScreenResolution

Returns the application screen resolution defined in the application profile.

ViewWidth

Returns the width of the VirtualUI viewer, in pixels.

ViewHeight

Returns the height of the VirtualUI viewer, in pixels.

Orientation

Returns the browser's orientation.

The following C# example shows how to center a window of our application on this virtual desktop as needed, previously controlling its size if it exceeds the available space:

using Cybele.Thinfinity;...

...

private VirtualUI vui;

public Form1()

{

InitializeComponent();

vui = new VirtualUI();}

private void CenterThisWindow(object sender, EventArgs e)

{

this.WindowState = FormWindowState.Normal;

if (vui.BrowserInfo.ViewHeight < (this.Height + 20)) {

this.Height = vui.BrowserInfo.ViewHeight - 20;

}

if (vui.BrowserInfo.ViewWidth < (this.Width + 20))

{

this.Width = vui.BrowserInfo.ViewWidth - 20;

}

this.Top = (vui.BrowserInfo.ViewHeight - this.Height) / 2;

this.Left = (vui.BrowserInfo.ViewWidth - this.Width) / 2;

}

5.7. Change Browser Behavior Using ClientSettings

There is also a Javascript Clientsettings object version. Learn how to use it.

The table below shows a detailed reference of the ClientSettings interface current properties:

Property

Use

CursorVisible

Used to set the mouse pointer to 'show' or 'hide'.

Type: Boolean

Default value: True

Available in all Library Versions.

MouseMoveGestureStyle

Defines whether the mouse movement is read as relative or absolute in touch devices.

Type: Enum

Values:

MM_STYLE_RELATIVE = 0

MM_STYLE_ABSOLUTE = 1

Default value: MM_STYLE_RELATIVE

Available in all Library Versions.

MouseMoveGestureAction

Indicates if the dragging should be interpreted as scrolling or turning of the mouse wheel, affecting only the component on which the action is triggered.

Type: Enum

Values:

MM_ACTION_MOVE = 0,

MM_ACTION_WHEEL = 1

Default value: MM_ACTION_MOVE

Available in all Library Versions.

UseViewportSize

Indicates which measure values will be used to define the application's screen size.

Type: Boolean

Values:

True: use the viewport size

False: use a window screen based size.

Default value: False

Available only in Javascript.

DockMenu

Manages the visibility of the bottom menu and its options.

Available only in Javascript

Enabled

Boolean. Enables/disables the complete Dock Menu.

Type: Boolean

Default value: True

Pinned

Indicates when the DockMenu is pinned (visible, fixed) or unpinned (with autohide)

Type: Boolean

Default value: False

Items

Name/value pairs item collection.

WindowList

Enables/disables the "Windows list" option.

Type: Boolean

Default value: True

ErrorReporting

Enables/disables the "Error Reporting" option.

Type: Boolean

Default value: True

Keyboard

Enables/disables the "Keyboard" option (mobile only).

Type: Boolean

Default value: True

FullScreen

Enables/disables the "Full Screen" option (mobile only, if supported).

Type: Boolean

Default value: True

As mentioned previously, these properties were created to provide a better end-user experience when using touch devices.

The properties that we have presented above will help us define the ideal settings to enjoy the best possible and intuitive user experience for our application.

The following example shows how to recognize a touch or mobile device, and to change the pointer behavior when it's detected. Warning: The detection list is not complete:

vui = new VirtualUI();

userAgent = vui.BrowserInfo.UserAgent.ToLower();

if ((userAgent.IndexOf("touch") != -1) || (userAgent.IndexOf("mobile") != -1) ||

(userAgent.IndexOf("iphone") != -1) || (userAgent.IndexOf("ipod") != -1) ||

(userAgent.IndexOf("ipad") != -1) || (userAgent.IndexOf("android") != -1) ||

(userAgent.IndexOf(" cros ") != -1)) {

vui.ClientSettings.MouseMoveGestureStyle = MouseMoveGestureStyle.MM_STYLE_ABSOLUTE;

vui.ClientSettings.MouseMoveGestureAction = MouseMoveGestureAction.MM_ACTION_WHEEL;

}

Read more about using ClientSettings from Javascript.

5.8. End-User Authentication

Read the following sections to learn how to implement the available authentication methods in VirtualUI web-enabled applications.

Read more:

· Entering Credentials

· Processing End-User Credentials

· Authentication Methods

5.8.1. Entering Credentials

Thinfinity VirtualUI allows you to enable one or more authentication methods at a time. There are two possible ways to ask for credentials:

· Using the standard Web Browser authentication dialog

· Showing a log-in page

This dialog is available when you use only one of the authentication access methods that require user and password: Windows Logon, RADIUS or External DLL.

For example, if only the 'Windows Logon' method is configured, the page will look like this:

But if you enable all predefined methods, your login will show something like this:

You can modify this page to adapt it to your branding and/or integration needs. Check out the login.html section to learn how.

Read more:

· Processing End-User Credentials

· Authentication Methods

· login.html

5.8.2. Processing End-user Credentials

Each published application without anonymous access requires the assignment of one or more Active Directory objects which define the users that can see and execute it.

Thinfinity VirtualUI implements a mapping mechanism to transform end-user credentials to AD objects. Only applications that match these AD objects will be granted access to the end-user.

Read more:

· Entering Credentials

· Authentication Methods

5.8.3. Authentication Methods

Thinfinity VirtualUI allows you to use the following authentication methods.

Windows Logon

This option enables Active Directory credentials. This method is enabled by default.

RADIUS

OAuth 2.0

External DLL

A custom authentication method implemented by you or a third party with our authentication API and referenced in the Thinfinity VirtualUI server.

Anonymous Authentication

All these methods will be enabled and configured in the Thinfinity VirtualUI Server Manager: choose the methods in the 'Authentication' tab and configure the mapping in the 'Mappings' subtab.

Read more:

· Windows Logon

· RADIUS

· OAuth 2.0

· External DLL

· Entering Credentials

· Processing End-User Credentials

5.8.3.1. Windows Logon

Windows Logon means that the end-user will have to enter Windows Activate Directory credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

Windows Logon is enabled by default in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

Read more:

· RADIUS

· OAuth 2.0

· External DLL

5.8.3.2. RADIUS

RADIUS as an authentication method means that the user will have to enter their RADIUS credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

RADIUS can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add RADIUS as an authentication method you will be required to provide the RADIUS account relevant information.

Read more:

· Windows Logon

· OAuth 2.0

· External DLL

5.8.3.3. OAuth 2.0

Read more:

· OAuth2Models.ini

· CSS for SSO options

5.8.3.3.1. OAuth2Models.ini

OAuth2Models.ini is a file is distributed with the Thinfinity VirtualUI installation that has all the information of the default available logins:

[Google]

ClientID =

ClientSecret =

AuthorizationParameters = scope=https://www.googleapis.com/auth/userinfo.email&approval_prompt=auto

AuthorizationURL = https://accounts.google.com/o/oauth2/auth

TokenValidationURL = https://accounts.google.com/o/oauth2/token

ProfileValidationURL = https://www.googleapis.com/oauth2/v1/userinfo

UsernameField = email

[Facebook]

ClientID =

ClientSecret =

AuthorizationParameters = scope=email

AuthorizationURL = https://www.facebook.com/dialog/oauth

TokenValidationURL = https://graph.facebook.com/oauth/access_token

ProfileValidationURL = https://graph.facebook.com/me?

UsernameField = email

[LinkedIn]

ClientID =

ClientSecret =

AuthorizationURL = https://www.linkedin.com/uas/oauth2/authorization

AuthorizationParameters = state=HIJK98sDT88jnS23S&scope=r_emailaddress

TokenValidationURL = https://www.linkedin.com/uas/oauth2/accessToken

ProfileValidationURL = https://api.linkedin.com/v1/people/~:(emailAddress)?format=json

UsernameField = emailAddress

[Dropbox]

ClientID =

ClientSecret =

AuthorizationURL = https://www.dropbox.com/1/oauth2/authorize

AuthorizationParameters =

TokenValidationURL = https://api.dropboxapi.com/1/oauth2/token

ProfileValidationURL = https://api.dropboxapi.com/1/account/info

UsernameField = email

Use this file as a template and edit it in order to add new authentication methods or ask your authentication provider for different data.

Read more:

· OAuth 2.0

5.8.3.3.2. CSS for SSO Options

In the login.css file, included in the 'web\css' folder of the Thinfinity VirtualUI installation, you will find the style for the login buttons.

#google { background-color:#4285F4; }

#google .imgbtn { background-image: url(../images/sso/google.png); }

#facebook { background-color:#2f4e9e; }

#facebook .imgbtn { background-image: url(../images/sso/facebook.png); }

#yahoo { background-color:#6839af; }

#yahoo .imgbtn { background-image: url(../images/sso/yahoo.png); background-size: 30px; }

#linkedin { background-color:#00A0DC; }

#linkedin .imgbtn { background-image: url(../images/sso/linkedin.png); }

#dropbox { background-color:#007ee6; }

#dropbox .imgbtn { background-image: url(../images/sso/dropbox.png); background-size: 30px; }

You can change the logo and/or background color of the login buttons for the Oauth 2.0 authentication methods.

The first line of each pair defines the button color, and the second one the button image.

Read more:

· Entering Credentials

· Processing End-User Credentials

· Authentication Methods

· Windows Logon

· RADIUS

· OAuth 2.0

· OAuth2Models.ini

· External DLL

· Authentication API

5.8.3.4. External DLL

Thinfinity VirtualUI allows you to integrate your own custom authentication method. In order to do this, use the Thinfinity VirtualUI Authentication API.

The user definition is completed through the mapping between the user ID returned by the external DLL and an Active Directory Objects mapped for this Authentication ID Mask.

Read more:

· Authentication API

5.8.3.4.1. Authentication API

Thinfinity VirtualUI provides you with an API that you can use to develop your own authentication method and integrate it with VirtualUI.

Choose the code sample of your language of preference and add it to your implementation:

Delphi:

function ValidateUser(

const UserName, Password, Metadata: PWideChar;

SecurityRole, WinUser, WinPass, CustomData: PWideChar;

var Handled: Boolean): Cardinal; stdcall;

Input:

Username & Password

The credentials that you are trying to validate with the external authentication

Metadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

SecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

WinUser, WinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

CustomData

(optional) Data for passing on to the application

Handled

Returns whether the login could be handled by the DLL.

C++:

THINFINITY_API DWORD __stdcall ValidateUser(LPWSTR lpUserName, LPWSTR lpPassword, LPWSTR lpMetadata, LPWSTR lpSecurityRole, LPWSTR lpWinUser, LPWSTR lpWinPass, LPWSTR lpCustomData,

PBOOLEAN pHandled)

Input:

lpUserName & lpPassword

The credentials that you are trying to validate with the external authentication

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

C#:

Input:

lpUserName & lpPassword

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

The authenticated username

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

Read more:

· External DLL

5.9. Virtualization

Additionally, in both cases, all users may have access to shared folders that it might be desirable to hide from them.

Thinfinity VirtualUI addresses these potential drawbacks by providing the File System and Registry Virtualization feature.

The main purposes of the Registry and File System virtualization are:

· To show only relevant folders.

· To provide private folders based on the application's credential system.

· To provide registry keys based on the application's credential system.

Read more:

· File System Virtualization

· Registry Virtualization

· Implementing Virtualization in Your Application

5.9.1. File System Virtualization

The file system mapping definition is a set of one to one redirection rules that link a real folder to the redirected folder path.

There are two types of redirection:

· Shared: for all connected users. It can be defined as readonly.

· Private: for a single identified user.

The configuration is done through the The File System Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

· Creating File System Redirections

· The .vidr Files

· Testing the File System Virtualization

· Registry Virtualization

· Implementing Virtualization in Your Application

5.9.1.1. Creating File System Redirections

In order to add a path in the Virtualization Editor, right click on the main area of the screen and choose 'New Path...'.

This will bring up the 'Edit Directory' dialog.

Field

Description

Mode

Choose 'Shared' if you want this mapping to apply to all users.

Choose 'Private' if you only want this mapping to apply to a single user.

Read Only

Only available for Shared Mode. Check this option to make the mapped directory read only for the user.

5.9.1.2. The .vdir Files

Read more:

· Creating File System Redirections

· Testing the File System Virtualization

· Implementing Virtualization in Your Application

5.9.1.3. Testing the File System Virtualization

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the files stored for each user are isolated.

Program

Choose a program with which to test the Filesystem virtualization. It has to be a program capable of opening files.

Read more:

· Creating File System Redirections

· The .vidr Files

· Implementing Virtualization in Your Application

5.9.2. Registry Virtualization

Registry Virtualization allows developers to store end-user information in the Windows Registry in a secure and isolated way and to provide authentication-based registry entries.

Additionally, shared registry entries can be redirected to safer places in the Windows Registry.

The registry mapping definition is a set of one to one redirection rules that link a real entry to the redirected entry.

There are two types of redirection:

· Shared: for all connected users.

· Private: for a single identified user.

Private redirection entries include the identified user ID appended to the redirected entry.

The configuration is done through the Registry Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

· Creating Registry Redirections

· The .vreg Files

· Testing Registry Virtualization

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.1. Creating Registry Redirections

In order to add a registry redirection, right click on one of the Server trees and choose 'Add Redirection'.

This will bring up the 'Edit Key Redirection' dialog:

Field

Description

Mode

Choose 'Shared' if you want this key redirection to apply to all users.

Choose 'Private' if you only want this key redirection to apply to a single user.

Source

Choose the source registry key you want to redirect.

Destination

Choose a registry destination key.

Editing Redirections

In order to edit a key redirection, right click on it and choose 'Edit Redirection'.

You will then be able to edit the redirection in the 'Edit Key Redirection' dialog.

Deleting Redirections

In order to delete a redirection, right click on it and choose 'Delete Redirection'.

Read more:

· Testing Registry Virtualization

· The .vreg Files

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.2. The .vreg Files

Read more:

· Creating Registry Redirections

· Testing Registry Virtualization

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.2.3. Testing Registry Virtualization

In order to test the registry virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the registry changes stored for each user are isolated.

Program

Choose a program with which to test the registry virtualization. It has to be a program that uses the registry.

Read more:

· Creating Registry Redirections

· File System Virtualization

· Implementing Virtualization in Your Application

5.9.3. Implementing Virtualization in Your Application

In order to apply the virtualization filters created with the Filesystem Virtualization Editor or the Registry Virtualization Editor, you have to add some code to your application.

After virtualui.Start(), load and apply the created filters with the current user credentials

Delphi:

virtualui.RegistryFilter.User := 'user identification';

virtualui.RegistryFilter.CfgFile := 'file.vreg';

virtualui.RegistryFilter.Active := true;

virtualui.FilesystemFilter.User := 'user identification';

virtualui.FilesystemFilter.CfgFile := 'file.vdir';

virtualui.FilesystemFilter.Active := true;

C#:

virtualui.Start();

virtualui.RegistryFilter().User = “user identification”;

virtualui.RegistryFilter().CfgFile = “file.vreg”;

virtualui.RegistryFilter().Active = True;

virtualui.FilesystemFilter().User = “user identification”;

virtualui.FilesystemFilter().CfgFile = “file.vdir”;

virtualui.FilesystemFilter().Active = True;

C++:

virtualui->Start();

virtualui->RegistryFilter()->User = “user identification”;

virtualui->RegistryFilter()->CfgFile = “file.vreg”;

virtualui->RegistryFilter()->Active = True;

virtualui->FilesystemFilter()->User = “user identification”;

virtualui->FilesystemFilter()->CfgFile = “file.vdir”;

virtualui->FilesystemFilter()->Active = True;

In order to disable registry or filesystem filtering, set the Active property to false.

Read more:

· File System Virtualization

· Registry Virtualization

5.10. OEM Licensing

There are two prerequisites:

· The application that uses the OEM Licensing Library (Thinfinity.VirtualUI.OEM.dll) must be digitally signed.

· You must have a valid OEM key.

To get an OEM key, you must provide Cybele Software with a digital certificate's thumbprint. On each licensing request, three parameters will be used to validate the requestor:

· The OEM-licensed Company's e-mail.

· The provided OEM key.

· The digital certificate's fingerprint, taken from the digital certificate that signs the executable making the OEM library call.

The generated OEM key and the digital certificate's thumbprint, along with your customer identification (e-mail), will be used to securely validate the licensing requests your application will make.

Read more:

· How to Create and Revoke Licenses

· Creating Licenses

· Revoking Licenses

5.10.1. How to Create and Revoke Licenses

visThe OEM library provides two functions to create a license and two functions to revoke a license:

· CreateLicenseW (Unicode version) and CreateLicenseA (ANSI version).

· RevokeLicenseW (Unicode version) and RevokeLicenseA (ANSI version).

In order to test the license creation and activation process, you can enable the SandboxMode in the OEM.ini file.

[LICENSE]

SandboxMode = True

The OEM.ini file should be placed in both the bin32 and bin64 paths under the Thinfinity VirtualUI installation folder and in the user's application executable file folder.

Adding External Methods

In a Delphi program we must first declare the external functions in their ANSI or Unicode version.

ANSI:

function CreateLicenseA(const email, oemkey, customerid: PAnsiChar;

units: DWORD; serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseA(const email, oemkey, serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

Unicode:

function CreateLicenseW(const email, oemkey, customerid: PWideChar;

units: DWORD; serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseW(const email, oemkey, serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

In order to access external library functions in a C# program, please declare:

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int CreateLicenseW(string email, string oemkey,

string customerid, int units, StringBuilder serial);

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int RevokeLicenseW(string email, string oemkey, string serial);

Read more:

· Creating Licenses

· Revoking Licenses

5.10.1.1. Creating Licenses

In order to create a new Thinfinity VirtualUI license you must use the corresponding CreateLicense method with the following parameters:

Email

OEM-licensed Company´s e-mail

OEMKey

OEM Key.

CustomerID

Arbitrary customer identification for the new license. This can be an e-mail address, a serial number or any other customer identification.

Units

Serial

out

Serial number of the successfully generated license.

A call to the CreateLicense function will return one of the following error codes:

No error. The "Serial" parameter will contain the generated serial number.

-1

General error in license server.

-2

Incorrect Email or OEM Key.

-3

No more units available.

-4

OEM License expired.

-5

General error. Cannot create license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

The following example shows how to create a license using Delphi. Please note that you must replace CreateLicenseW by CreateLicenseA when using ANSI chars.

procedure CreateLicense;

var

result: Integer;

serial: WideString;

begin

serial := StringOfChar(' ', 128);

result := CreateLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'),

PChar('CUSTOMER_ID'), UNIT_COUNT, PWideChar(serial)); // Check result

end;

And this is how you create it using C#:

private void CreateLicense()

{

StringBuilder sn = new StringBuilder(128);

int result = CreateLicenseW("OEM_EMAIL", "OEM_KEY",

"CUSTOMER_ID", UNIT_COUNT), sn);

string serial = "";

// Check result

if (result == 0)

{

serial = sn.ToString().Trim();

}

else

{

// Error

}

Note: In all these examples, please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration, 'CUSTOMER_ID' with the Customer identification and 'UNIT_COUNT' with the desired value.

Read more:

· How to Create and Revoke Licenses

· Revoking Licenses

5.10.1.2. Revoking Licenses

The RevokeLicense function is used to revoke a previously generated license. These are its parameters:

Email

OEM-licensed Company's e-mail

OEMKey

OEM License Key.

Serial

Serial number to revoke.

This function will return one of the following error codes:

No error. The license was revoked.

-1

General error in license server.

-2

Incorrect Email or OEMKey.

-3

Incorrect Serial number.

-4

Incorrect Serial number.

-5

General error. Cannot revoke license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-50

Error in HTTP request.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

Here's how to revoke a license using Delphi:

procedure RevokeLicense;

var result: Integer;

begin

result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER'); // Check result

end;

And here's how to revoke a license using C#:

private void RevokeLicense() {

int result = RevokeLicenseW("OEM_EMAIL", "OEM_KEY", "SERIAL_NUMBER"); // Check result

}

Note: Please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration information, and replace 'SERIAL_NUMBER' with the Serial to revoke.

Read more:

· How to Create and Revoke Licenses

· Creating Licenses

5.11. Silent Install Options

Thinfinity VirtualUI Line Switches

In order to perform a silent installation, use this command line:

c:\Thinfinity_VirtualUI_Setup_x64.exe /s /v/qn

These are additional command line switches that you can pass on to the setup file:

Variable

Description

Default value

VFMX_SERVER_MODE

Determines whether the server components will be installed

TRUE

VFMX_DEV_MODE

Determines whether the development components will be installed

TRUE

VIRTUALIZATION

Determines whether the Virtualization components will be installed. In order for this option to be enabled, VFMX_SERVER_MODE cannot be FALSE.

FALSE

STDLBMODE

Values:

- LBMODE: Load balancing mode

- STDMODE: Standard mode.

STDMODE

SM_TYPE

Values:

- SM_Complete : Installs Server and Gateway components

- SM_Broker: Installs only Server components

- SM_Gateway: Installs only Gateway components.

Note: In order for this option to be enabled, STDLBMODE has to be set to LBMODE.

EMAIL

Complete this variable with your registration email. Also make sure to include the SERIAL parameter in order for the registration to work.

SERIAL

Complete this variable with your registration serial. Also make sure to include the EMAIL parameter in order for the registration to work.

The VFMX_SERVER_MODE, VFMX_DEV_MODE and VIRTUALIZATION parameters correspond to these installation wizard options:

The STDLBMODE and SM_TYPE parameters correspond to these installation wizard options:

The default installation will install Thinfinity VirtualUI Server in standard mode and the development components, but not the virtualization components.

Examples

· Installing Thinfinity VirtualUI in Standard Mode with Virtualization Components and without Development Environment:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VIRTUALIZATION=\"TRUE\" VFMX_DEV_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI Development environment only:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VFMX_SERVER_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI in Load Balancing mode using Gateway and Server roles and including licensing:

C:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn EMAIL=\"myemail@mydomain.com\" SERIAL=\"45EI-09IJ-OOA6-3GH5-IT5E-E4ER-KIP9-A669\" STDLBMODE=\"LBMODE\" SM_TYPE=\"SM_Complete\""