Managing licenses through the Thinfinity VirtualUI OEM Licensing API

 

To help bundling Thinfinity VirtualUI with their applications, companies applying for OEM licensing can take advantage of three new features: Server Configuration API, OEM Licensing API and White Labeling customization.
In this article we will cover the Thinfinity VirtualUI OEM Licensing API.

Thinfinity VirtualUI OEM Licensing API – How does it work?

If your product qualifies for OEM licensing, we will provide you with a Licensing Library, the Thinfinity VirtualUI OEM Licensing API that would enable OEM-licensed Companies to create and revoke end-user’s 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.

How to Create and Revoke Licenses?

The 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 SanboxMode in OEM.ini file.

[LICENSE]
SandboxMode = True

OEM.ini file should be placed in both bin32 and bin64 paths under Thinfinity VirtualUI installation 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 to external library functions in 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);

 

Creating licenses

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 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 calling 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 in 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;

To create a license in 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.

 

Revoking licenses

The RevokeLicense function is used to revoke a previously generated license. There 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.

To revoke a license in Delphi:

procedure RevokeLicense;
   var result: Integer;
begin
   result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER');
   // Check result
end;

And to revoke a license in 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 and replace SERIAL_NUMBER’ with the Serial to revoke.
Working with white labeled solutions?
Take a look to this other article to read more about VirtualUI White Labeling customization in details.