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.
Directory	Choose the directory you want to show.
Redirect to	Choose the physical path where the directory contents will be stored during the user session.

Paths can also be expressed using the environment variables defined in Windows:

%public%, %home%, %documents%, etc

For example, you can redirect %userprofile% to %userprofile%\users as a private redirection; "user1"’s files will therefore be stored in c:\users\username\users\user1

Or you can map c:\temp to %userprofiles%\temp as a shared redirection.

Editing Paths

In order to edit a path, right click on it and choose 'Edit Path'.

You will then be able to edit the path in the 'Edit Directory' dialog.

Deleting Paths

In order to delete a path, right click on it and choose 'Delete Path'.

Read more:

· The .vidr Files

· Testing the File System Virtualization

· Implementing Virtualization in Your Application

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	in	OEM-licensed Company´s e-mail
OEMKey	in	OEM Key.
CustomerID	in	Arbitrary customer identification for the new license. This can be an e-mail address, a serial number or any other customer identification.
Units	in	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:

0	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	in	OEM-licensed Company's e-mail
OEMKey	in	OEM License Key.
Serial	in	Serial number to revoke.

This function will return one of the following error codes:

0	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=\"[e-mail]\" SERIAL=\"45EI-09IJ-OOA6-3GH5-IT5E-E4ER-KIP9-A669\" STDLBMODE=\"LBMODE\" SM_TYPE=\"SM_Complete\""