ImageGear Licensing and Deployment Kit

ImageGear Licensing
and
Deployment Kit
For ImageGear Products
For DLL and ActiveX

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Licensing and Deployment Kit

This document guides you through the process of deploying your developed ImageGear application to end users.

There are two ImageGear deployment licensing models:

User

Not bound to hardware parameters. Therefore only one License Key is required per ImageGear-based application.
NOTE: The User licensing model was previously known as the "Platinum" model.

Server

Bound to hardware parameters. Therefore an individual node-locked License Key has to be generated for each system where the ImageGear-based solution is used. With this model, the Licensing Component running on the end user's machine can communicate directly to the Deployment Licensing Service but you also have the choice of setting up a Deployment Proxy Service at your site - in this case Licensing Component would communicate through this proxy service.
NOTE: The Server licensing model was previously known as the "Gold" model.

Read the appropriate section for the license model you have purchased from AccuSoft. After you complete the instructions in that section, refer to the "Deploying Your Product" section.

See Also:

User Licensing

Server Licensing

Deploying Your Product


User Licensing

With the User License (Platinum) deployment model, a single License Key is generated for each ImageGear-based solution and is used to initialize the ImageGear core component using the ImageGear product licensing API. No further actions are required to license your application on the end user's system. The User model includes both concurrent user and named user methods. Distribution is per AccuSoft's agreement for quarterly reporting (LDR).

Depending on the type of application you are deploying, you will use one of the following processes:

  • The Client Process
  • The Web Process


The Client Process

This section specifies the steps you need to follow to properly license and install your end product on the end users machine when deploying your product to a client machine.

With the User License model, no Licensing Component is required. AccuSoft will email the necessary parameters to you: Solution Name, Solution Key and License Key for the deployment of your application. Using these parameters, you can then modify the code of your application to specify the Solution Name, Solution Key, and License Key using the following ImageGear API:

  • To specify the Solution Name, you call
    • IG_lic_solution_name_set function for the DLL version
    • SolutionNameSet method for the Legacy ActiveX version
    • IGLicense.SetSolutionName method for the ActiveX version
    • ImGearLicense.SetSolutionName method for the .NET version
NOTE: When you are ready to deploy your ImageGear-based application, you need to replace the generic solution name that you have used with the ImageGear evaluation and development licenses with the unique solution name assigned to your application by AccuSoft.
  • To specify the Solution Key, you call
    • IG_lic_solution_key_set function for the DLL version
    • SolutionKeySet method for the Legacy ActiveX version
    • IGLicense.SetSolutionKey method for the ActiveX version
    • ImGearLicense.SetSolutionKey method for the .NET version
  • To specify the License Key for your application, you call
    • IG_lic_OEM_license_key_set function for the DLL version
    • OEMLicenseKeySet method for the Legacy ActiveX version
    • IGLicense.SetOEMLicenseKey method for the ActiveX version
    • ImGearLicense.SetOEMLicenseKey method for the .NET version

You also need to use the Deployment Packaging Wizard to package the ImageGear run time components required for your application.

See Also:

Deploying Your Product

ImageGear Licensing API Reference

Code Samples for User (Platinum) Model

DLL version:

VB:

'Licensing Functions Definitions
Declare Function IG_lic_solution_name_set Lib "igcore15d.dll"
(ByVal SolutionName As String) As Long
Declare Function IG_lic_solution_key_set Lib "igcore15d.dll"
(ByVal Key1 As Long, ByVal key2 As Long, ByVal key3 As Long,
ByVal key4 As Long) As Long
Declare Function IG_lic_OEM_license_key_set Lib "igcore15d.dll"
(ByVal SolutionName As String) As Long
Dim IGErr As Long

IGErr = IG_lic_solution_name_set("Your Solution Name")
IGErr = IG_lic_solution_key_set(&H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A)
IGErr =
IG_lic_OEM_license_key_set("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsO
PePf...")

C#:

The names of the ImageGear functions may change depending on how you wrap the DLL for use in C#. For an example on wrapping the ImageGear Libraries, please refer to the DLL "C#.net Demo" program and source.

ASCIIEncoding encoding = new ASCIIEncoding();
byte[] SolutionName = encoding.GetBytes("Your Solution Name");
byte[] OEMKey =
encoding.GetBytes("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...");
fixed (byte* pszBuffer = SolutionName)
{
    IGLib.IG_lic_solution_name_set( pszBuffer );
}
IGLib.IG_lic_solution_key_set (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);

fixed (byte* pszBuffer = OEMKey)
{
    IGLib.IG_lic_OEM_license_key_set ( pszBuffer );
}

C++:

IG_lic_solution_name_set( "Your Solution Name" );
IG_lic_solution_key_set(0x473F47EC, 0xDEDCEDC4, 0xAFFBB23E,
0xFBFBDE4A );
IG_lic_OEM_license_key_set
("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...");

VB.NET:

'Licensing Functions Definitions
Declare Function IG_lic_solution_name_set Lib "igcore15d.dll"
(ByVal SolutionName As String) As Long
Declare Function IG_lic_solution_key_set Lib "igcore15d.dll"
(ByVal Key1 As Long, ByVal key2 As Long, ByVal key3 As Long,
ByVal key4 As Long) As Long
Declare Function IG_lic_OEM_license_key_set Lib "igcore13d.dll"
(ByVal SolutionName As String) As Long
Dim IGErr As Long
IGErr = IG_lic_solution_name_set("[Your Solution Name]")
IGErr = IG_lic_solution_key_set(&H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A)
IGErr =
IG_lic_OEM_license_key_set("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsO
PePf...")

Delphi:

IG_lic_solution_name_set( `[Your Solution Name]' );
IG_lic_solution_key_set( $473F47EC, $DEDCEDC4, $AFFBB23E,
$FBFBDE4A );
IG_lic_OEM_license_key_set(
`1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...' );

Legacy ActiveX version

The licensing calls within the Legacy ActiveX components reside in the Core ImageGear component.

VB:

ImGear1.SolutionNameSet ("Your Solution Name")
ImGear1.SolutionKeySet &H473F47EC, &HDEDCEDC4, &HAFFBB23E,
&HFBFBDE4A
ImGear1.OEMLicenseKeySet
"1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf..."

C#:

uint key1, key2, key3, key4;
key1 = 0x473F47EC;
key2 = 0xDEDCEDC4;
key3 = 0xAFFBB23E;
key4 = 0xFBFBDE4A;
axIGCoreCtl1.SetSolutionName("Your Solution Name");
axIGCoreCtl1.SetSolutionKey ((int)key1, (int)key2, (int)key3,
(int) key3);
axIGCoreCtl1.OEMLicenseKeySet
("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...");

C++:

//Pointer to Gear Control
IGear13* m_pIGear;
//Licensing Calls
CString  strSolutionName( "Your Solution Name" );
pDoc->m_pIGear->SolutionNameSet ( A2W(strSolutionName) );
pDoc->m_pIGear->SolutionKeySet (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);
pDoc->m_pIGear-
>OEMLicenseKeySet(A2W("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...
"));

VB.NET:

IGCoreCtl1.SolutionNameSet("[Your Solution Name]")
IGCoreCtl1.SolutionKeySet(&H473F47EC, &HDEDCEDC4, &HAFFBB23E,
&HFBFBDE4A)
IGCoreCtl1.OEMLicenseKeySet("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOs
OPePf...")

Delphi:

IGCoreCtl1.SolutionNameSet( `[Your Solution Name]' );
IGCoreCtl1.SolutionKeySet( $H473F47EC, $HDEDCEDC4, $HAFFBB23E,
$HFBFBDE4A );
IGCoreCtl1.OEMLicenseKeySet(
`1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...' );

PowerBuilder:

IGCoreCtl.Object.SolutionNameSet("[Your Solution Name]")
IGCoreCtl.Object.SolutionKeySet(of_HexToUlong("H473F47EC"),
of_HexToUlong("HDEDCEDC4"), of_HexToUlong("HAFFBB23E"),
of_HexToUlong("HFBFBDE4A")) - *
IGCoreCtl.Object.OEMLicenseKeySet("1.0.WkFoEmKFJkSdDHJfFDGsTRYd
IUfIOsOPePf...")
See Also:

Solution Key Converter for PowerBuilder 10

ActiveX version

With the new ActiveX components, the IGLicense object of the Core Control handles the licensing of ImageGear.

VB:

IGCoreCtl1.License.SetSolutionName "Your Solution Name"
IGCoreCtl1.License.SetSolutionKey &H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A
IGCoreCtl1.License.SetOEMLicenseKey
"1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf..."

C#:

Due to the difference in the bit size of an integer in C#, you need to create the License Keys as unsigned integers and type cast them to integers.

uint key1, key2, key3, key4;
key1 = 0x473F47EC;
key2 = 0xDEDCEDC4;
key3 = 0xAFFBB23E;
key4 = 0xFBFBDE4A;
axIGCoreCtl1.License.SetSolutionName("Your Solution Name");
axIGCoreCtl1.License.SetSolutionKey ((int)key1, (int)key2,
(int)key3, (int) key3);
axIGCoreCtl1.License.SetOEMLicenseKey
("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...");

C++:

//Global pointer reference.
GearCORELib::IIGCoreCtlPtr g_pIGCore = NULL;
//g_pIGCore is a reference to a global pointer to the Gear Core
Control
g_pIGCore->License->SetSolutionName("Temp Test Platinum
License");
g_pIGCore->License->SetSolutionKey (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);
g_pIGCore->License->SetOEMLicenseKey
("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...");

VB.NET:

IGCoreCtl1.License.SetSolutionName("[Your Solution Name]")
IGCoreCtl1.License.SetSolutionKey(&H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A)
IGCoreCtl1.License.SetOEMLicenseKey("1.0.WkFoEmKFJkSdDHJfFDGsTR
YdIUfIOsOPePf...")

Delphi:

IGCoreCtl1.License.SetSolutionName( `[Your Solution Name]' );
IGCoreCtl1.License.SetSolutionKey( $H473F47EC, $HDEDCEDC4,
$HAFFBB23E, $HFBFBDE4A );
IGCoreCtl1.License.SetOEMLicenseKey(
`1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUfIOsOPePf...' );

PowerBuilder:

IGCoreCtl.Object.License.SetSolutionName("[Your Solution
Name]")
IGCoreCtl.Object.License.SetSolutionKey(
of_HexToUlong("H473F47EC"), of_HexToUlong("HDEDCEDC4"),
of_HexToUlong("HAFFBB23E"), of_HexToUlong("HFBFBDE4A") - *
IGCoreCtl.Object.License.SetOEMLicenseKey("1.0.WkFoEmKFJkSdDHJf
FDGsTRYdIUfIOsOPePf...")
See Also:

Solution Key Converter for PowerBuilder 10

.NET version

VB .NET:

Dim Key1, Key2, Key3, Key4 As UInt32
Dim LKey1, LKey2, LKey3, LKey4 As Long
LKey1 = 1382566911
LKey2 = 5853474885
LKey3 = 7422822616
LKey4 = 3275893442
Key1 = Convert.ToUInt32(LKey1)
Key2 = Convert.ToUInt32(LKey2)
Key3 = Convert.ToUInt32(LKey3)
Key4 = Convert.ToUInt32(LKey4)
ImGearLicense.SetSolutionName("Your Solution Name")
ImGearLicense.SetSolutionKey(Key1, Key2, Key3, Key4)
ImGearLicense.SetOEMLicenseKey("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUf
IOsOPePf...")

C# .NET:

ImGearLicense.SetSolutionName("Your Solution Name");
ImGearLicense.SetSolutionKey(0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);
ImGearLicense.SetOEMLicenseKey("1.0.WkFoEmKFJkSdDHJfFDGsTRYdIUf
IOsOPePf...");

Solution Key Converter for PowerBuilder 10

PowerBuilder 10 does not support hexadecimal numbers, so the PowerBuilder users can use the following converters passing the solution keys as strings:

//
===============================================================
=======
//
//      Function:  of_UlongToHex (Ulong aul_data)
//
//      Description:  convert an unsigned long data to its
hexedecimal
//                       value in string format
//
//      Access:  public
//
//      Arguments:
//      Ulong   aul_Data        Ulong data to be converted
//
//      Returns:  string
//              The output of hexedecimal value
//              Null    if the input data is null
//
//      Author: Lijun Yang
//
//      Date:           4/9/97
//
//
===============================================================
=======
//
//      Revision History
//
//      Date            Initials                Description of
Change
//      ----            --------                ---------------
-----
//      4/9/97          L.Y.                    Initial creation
//
===============================================================
=======
ulong   lul_mod
string ls_Return = ""
char    lc_hex[0 to 15] = {'0', '1', '2', '3', '4', '5', '6',
'7', &
'8', '9', 'a', 'b', 'c', 'd', 'e', 'f'}
Char    lc_char[]
// Check if the argument is null
IF IsNull (aul_data) THEN
SetNull (ls_Return)
RETURN ls_return
END IF
DO WHILE aul_data > 0
lul_mod = mod (aul_data, 16)
ls_return = lc_hex[lul_mod] + ls_return
aul_data /= 16
LOOP
IF ls_return = "" THEN ls_return = '0'
Return ls_return
//
===============================================================
=======
//
//      Function:  of_HexToUlong (string as_hex)
//
//      Description:  convert a hexedecimal value (string
format) into
//              its unsigned long value
//
//      Access:  public
//
//      Arguments:
//      string  as_Hex  hexedecimal data to be converted
//
//      Returns:  ulong
//              the output of the hex value
//              NUll    if the input data is null
//
//      Author: Lijun Yang
//
//      Date:           4/9/97
//
//
===============================================================
=======
//
//      Revision History
//
//      Date            Initials                Description of
Change
//      ----            --------                ---------------
-----
//      4/9/97          L.Y.                    Initial creation
//
===============================================================
=======
Integer li_i
ulong   lul_value
integer li_len
Char    lc_char[]
ulong lul_return = 0
// Check if the argument is null
IF IsNull (as_hex) THEN
SetNull (lul_return)
RETURN lul_return
END IF
li_len = len (as_hex)
as_hex = lower (as_hex)
lc_char  = as_hex
FOR li_i = 1 to li_len
IF lc_char[li_i] > '9' then
//get the value for 'a' - 'f'
lul_value = asc (lc_char[li_i]) - 87
ELSE
lul_value = long (lc_char[li_i])
End IF
lul_return = lul_return * 16 + lul_value
NEXT
RETURN lul_return
See Also:

ImageGear Licensing API Reference


The Web Process

This section defines the steps you need to take in order to license and deploy the ImageGear components over the Web.

License Binding

If you are using the license binding scheme to license your ImageGear ActiveX-based application, all ImageGear deployment license data has to be written in the AccusoftLicenseBinding.txt file. You have to enter it manually, using the license information provided to you from the AccuSoft licensing service.

NOTE: Please see the detailed information about ImageGear license binding in the section "Using ImageGear Licensing API" in the "Using ImageGear" chapter of the core ImageGear Professional ActiveX version manual.

For the User License model, the AccusoftLicenseBinding.txt file needs to have 3 lines with the following format:

Solution name = <solution name>
Solution key = <solution key>
OEM license key = <user license key>

Where the <solution name> is a case-sensitive name of the solution that can have more than one space character between words. The <solution key> parameter is a 4 hexadecimal integer key separated by either a comma or space characters (or both). Note that the <user license key> is a valid user license key without quotation marks. For example:

Solution name = Your Platinum Solution Name
Solution key = 0x1111, 0x2222, 0x3333, 0x4444
OEM license key = 1.0.RELJDAKDALJDSKL
NOTES: The identifiers can be written in any order and without quotation marks. They are case sensitive. Only one identifier per line is allowed.

The file is case sensitive.

The next section, "The LPK Tool" explains what to do with the text file.

The LPK Tool

A licensed ActiveX control does not load properly in an Internet Explorer HTML page if the computer is not licensed to use the control. For example, if you use Microsoft® Visual C++® to build the control, the HTML page loads properly with the control on the computer where it was built, but it will not load correctly on a different computer. This is because an HTML page with licensed controls requires a single associated license package that stores the run-time licenses for all the controls used on the page. The HTML page should point to a license package via a relative URL. This tool allows you to author a license package file.

An LPK file is a file that licenses ImageGear ActiveX controls when running on a Microsoft Internet Explorer Web Browser. This file must be created for all ActiveX components that require licensing, regardless of manufacturer.

Creating an LPK File

1. Obtain the Microsoft LPK File Generation Tool either from your Visual Studio Installation, from the Microsoft Internet Explorer API Pack, or from Microsoft's Download File Section of their Web site.

a) Check: LPK Tool found in the Tools folder of your Visual Studio 6.0 Installation CD- ROM
...or...

b) Download: Microsoft LPK Tool [74.5 KB] from Microsoft Server

This program is the only program that can generate LPK files and is provided by Microsoft.

2. Open the LPK Tool and select the ImageGear Components you will be using on the Web page. Also select other ActiveX controls that you will be using on the same Web page that require licensing. You can only have one LPK file per Web page, so you will need to select all ActiveX controls that will be used.

3. Click the "Save & Exit" button to generate the LPK file.

4. In the Save As dialog box that appears, you can name the LPK file anything you want. However, we recommend that you do not include spaces or non-standard characters.

5. Copy the LPK file to a location on your Web server. If you are just creating a single Web page, we recommend that you place the LPK file in the same folder as the Web page. If you are creating multiple Web pages, we recommend that you place the LPK file in a common folder off of the root of your Web server, such as /download.

Integrating the LPK File into Your Web Page

Place the following block of code, substituting the name of your LPK file, at the top the body section of your Web page.

<html>

<head>
<title>LPK File Example Page</title>
</head>

<body>

<object CLASSID="clsid:5220cb21-c88d-11cf-b347-00aa00a28331"
VIEWASTEXT>
<param name="LPKPath" value="/download/MyLPKfile.lpk">
</object>

...include all ActiveX component object tags only after this
line...

</body>

</html>
NOTE: The CLASSID must always be the value specified above. This is the CLASSID of the Microsoft License Manager component, which provides licensing services to ActiveX components that require licensing. This CLASSID is the same for all versions of Microsoft Internet Explorer

You can only have one LPK file entry per Web page.


Server Licensing

The Server licensing model has three different scenarios. Once you have added the licensing calls to your application, as explained in the next section, you need to follow additional steps. Depending on the licensing scenario you choose, refer to one of the following sections for further information:

  • The Server Licensing Utility (SLU) Process

The SLU process is ideal for limited licensing (for example, an internally deployed server application). Less coding is required up-front, but there is manual intervention required.

  • The Automatic Scenario

The Automatic process requires that your end users have an Internet connection. The process is automatic, which means that there is less intervention, but also less control.

  • The Manual Scenario

The Manual process is designed for end users who do or do not have an Internet connection. Although the process is more complex, you have more control over licensing.

The manual and automatic scenarios achieve the same end result, and can be mixed among your end users, since the License Key is generated by the same Deployment Licensing Service for either scenario. The automatic scenario is the recommended method, but if an Internet connection is not available, then the manual scenario can be used.

Errors can occur during licensing with either scenario, e.g: Internet connection problems (in automatic mode), registry permission problems, invalid access keys, etc. To guarantee that your application runs after installation, the Licensing Component automatically activates the grace period when any error occurs during licensing. The default grace period is 14 days, but this can be customized for each deployment pool by request to AccuSoft. The licensing process can be repeated during the grace period, and once the application is licensed successfully, the grace period is cleared.

NOTE: With either scenario, your application only needs to be licensed once, after which it will work indefinitely. In the event that your end user recovers from a backup onto different hardware, the license needs to be transferred as described in the below and then bound to the new hardware.

AccuSoft provides the Licensing Component that facilitates the licensing process on the end user's system for the Server model.

The Server License model provides the following benefits:

  • You can integrate the Vendor Licensing Utility functionality into your own system (e.g., order processing system).
  • You can set up the Deployment Proxy Service on your site and program the Licensing Component to communicate with the Deployment Proxy Service instead of the Deployment Licensing Service.
  • You can set up custom End User licensing scenarios. For example, directing end users to come to a Web application hosted on your Web site to get a License Key.

The following tools and utilities are provided by AccuSoft to prepare your application for deployment:

  • The Vendor Licensing Utility
  • A License Deployment Kit (LDK) that includes:
    • Licensing Component
    • Sample VB-script (see Licensing Component Wrapper)
    • Sample MSI-package (see Licensing Component Wrapper)
    • Deployment Proxy Service
    • Deployment Packaging Wizard (see also Deploying Your Product)
  • A Configuration file to be used with the Licensing Component


Adding Licensing Calls to Your Application

With Server deployment (Gold) licensing, regardless of which scenario you choose, you need to provide your ImageGear-based application with a Solution Name and a Solution Key obtained using the Vendor Licensing Utility. You do this using the ImageGear licensing API:

  • To specify the Solution Name you call
    • IG_lic_solution_name_set function for the DLL version
    • SolutionNameSet method for the Legacy ActiveX version
    • IGLicense.SetSolutionName method for the ActiveX version
    • ImGearLicense.SetSolutionName method for the .NET version
NOTE: When you are ready to deploy your ImageGear-based application, you need to replace the generic solution name that you have used with the ImageGear evaluation and development licenses with the unique solution name assigned to your application by AccuSoft.
  • To specify the Solution Key you call
    • IG_lic_solution_key_set function for the DLL version
    • SolutionKeySet method for the Legacy ActiveX version
    • IGLicense.SetSolutionKey method for the ActiveX version
    • ImGearLicense.SetSolutionKey method for the .NET version
See Also:

Code Samples for Server (Gold) Model

Once you have added the licensing calls to your application, depending on the licensing scenario you choose, refer to one of the following sections for further information:

  • The Server Licensing Utility (SLU) Process
  • The Automatic Scenario
  • The Manual Scenario

Code Samples for Server (Gold) Model

DLL version:

VB:

'Licensing Functions Definitions
Declare Function IG_lic_solution_name_set Lib "igcore15d.dll"
(ByVal SolutionName As String) As Long
Declare Function IG_lic_solution_key_set Lib "igcore15d.dll"
(ByVal Key1 As Long, ByVal key2 As Long, ByVal key3 As Long,
ByVal key4 As Long) As Long
Dim IGErr As Long

IGErr = IG_lic_solution_name_set("AccuSoft 1-100-15")
IGErr = IG_lic_solution_key_set(&H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A)

C#:

The names of the ImageGear functions may change depending on how you wrap the DLL for use in C#. For an example on wrapping the ImageGear Libraries, please refer to the DLL "C#.net Demo" program and source.

ASCIIEncoding encoding = new ASCIIEncoding();
byte[] SolutionName = encoding.GetBytes("AccuSoft 1-100-15");
fixed (byte* pszBuffer = SolutionName)
{
    IGLib.IG_lic_solution_name_set( pszBuffer );
}
IGLib.IG_lic_solution_key_set (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);

C++:

IG_lic_solution_name_set( "AccuSoft 1-100-15" );
IG_lic_solution_key_set(0x473F47EC, 0xDEDCEDC4, 0xAFFBB23E,
0xFBFBDE4A );

Legacy ActiveX version

The licensing calls within the Legacy ActiveX components reside in the Core ImageGear component.

VB:

ImGear1.SolutionNameSet ("AccuSoft 1-100-13")
ImGear1.SolutionKeySet &H473F47EC, &HDEDCEDC4, &HAFFBB23E,
&HFBFBDE4A

C#:

uint key1, key2, key3, key4;
key1 = 0x473F47EC;
key2 = 0xDEDCEDC4;
key3 = 0xAFFBB23E;
key4 = 0xFBFBDE4A;
axIGCoreCtl1.SetSolutionName("AccuSoft 1-100-13");
axIGCoreCtl1.SetSolutionKey ((int)key1, (int)key2, (int)key3,
(int) key3);

C++:

//Pointer to Gear Control
IGear13* m_pIGear;
//Licensing Calls
CString  strSolutionName( "AccuSoft 1-100-13" );
pDoc->m_pIGear->SolutionNameSet ( A2W(strSolutionName) );
pDoc->m_pIGear->SolutionKeySet (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);

ActiveX version

With the new ActiveX components, the IGLicense object of the Core Control handles the licensing of ImageGear.

VB:

IGCoreCtl1.License.SetSolutionName "AccuSoft 1-100-15"
IGCoreCtl1.License.SetSolutionKey &H473F47EC, &HDEDCEDC4,
&HAFFBB23E, &HFBFBDE4A

C#:

Due to the difference in the bit size of an integer in C#, you need to create the License Keys as unsigned integers and type cast them to integers.

uint key1, key2, key3, key4;
key1 = 0x473F47EC;
key2 = 0xDEDCEDC4;
key3 = 0xAFFBB23E;
key4 = 0xFBFBDE4A;
axIGCoreCtl1.License.SetSolutionName("AccuSoft 1-100-15");
axIGCoreCtl1.License.SetSolutionKey ((int)key1, (int)key2,
(int)key3, (int) key3);

C++:

//Global pointer reference.
GearCORELib::IIGCoreCtlPtr g_pIGCore = NULL;
//g_pIGCore is a reference to a global pointer to the Gear Core
Control
g_pIGCore->License->SetSolutionName("AccuSoft 1-100-15");
g_pIGCore->License->SetSolutionKey (0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);

.NET version

VB .NET:

ImGearLicense.SetSolutionName("AccuSoft 3-40-2");
ImGearLicense.SetSolutionKey(0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);

C# .NET:

ImGearLicense.SetSolutionName("AccuSoft 3-40-2");
ImGearLicense.SetSolutionKey(0x473F47EC, 0xDEDCEDC4,
0xAFFBB23E, 0xFBFBDE4A);
NOTE: ImageGear for .Net 2.0 64-bit solution name is "AccuSoft 3-41-2".


The Server Licensing Utility (SLU) Process

In the Server Licensing Utility scenario, once you have added licensing calls to your application, as explained in the previous section (Adding Licensing Calls to Your Application), you only need to use our pre-packaged licensing utility for licensing either server-based ImageGear applications or a NetVue server. The Utility obtains a license key for the target server when a valid configuration file is presented. The license key is stored in the registry of the target server.

NOTE: For NetVue, the user count can be viewed in the Web server tools once the service is restarted.

With the configuration file sent after server licenses have been purchased, you will be able to use the Server Licensing Utility to license your ImageGear or NetVue based server. This process can be used only once per license purchased. When you are ready to install the deployment license, follow these steps (requires internet connection):

1. Save the config.txt, previously sent from your purchase of server licensing, to the target server in a readily available directory.

2. Run the following utility: C:\Program Files\AccuSoft\ImageGear v15\MD\LDK\Bin\SLU.exe

3. When the utility launches, click the Browse button, and browse to the config.txt file saved in step 1.

4. Click Auto Register.

If the auto register fails, it will start a manual process. If this occurs, then do the following:

a. In the second dialog window that appears, click the Copy Hardware Key button.

b. Go to: https://www.accusoft.com/Licensing/v1/WebDeployUser/WebDeployUser.aspx

c. In the Hardware Key box, paste the hardware key from the clipboard, which was obtained in step a.

d. Click Download License.

e. The resultant text file will be sent to your PC via your browser, which you can open.

f. Copy the entire License Key from the text file in step e.

g. Return to the licensing utility and paste the license key into the license key box.

h. Click License. The Server is now licensed for ImageGear.

NOTE: If you are licensing NetVue, restart the service. After you restart, you should now notice that the Server Status has X users, depending on amount purchased.


The Automatic Scenario

The Automatic scenario consists of the following:

1. You distribute a unique Access Key to the End User from the pool of created access keys.

2. The end user enters the access key when the installation program prompts for it.

3. As an alternative to steps 1 and 2, an Access Key can be automatically obtained from the pool available for your application. In this case no input from the end user is required (i.e. call GetLicKeyAuto("")).

4. The Licensing Component is used to form a Hardware Key, obtain a License Key, and store it into the registry.

5. If an error occurs, the grace period is activated.

When using the Automatic Licensing Scenario, once you have added licensing calls to your application, as explained in the previous section (Adding Licensing Calls to Your Application), the only additional step you need to complete to license your product is to add calls to the Licensing Component. The Licensing Component facilitates the process of obtaining a License Key bound to the End User's system. This is typically done during the ImageGear-based solution installation, but you might want to consider providing a separate registration utility (or menu item in your application) if you are licensing manually or to handle errors that may occur during the installation.

Accessing the Licensing Component from the installer is typically done using a script that is executed during installation (AccuSoft provides a sample VB Script). The Licensing Component allows you to implement two scenarios - an Automatic Licensing Scenario and a Manual Licensing Scenario. You can use either scenario to obtain a license for the end user's machine, although the automatic method is easier to use.

In The Automatic Scenario, you only need to call a single method (GetLicKeyAuto) of the Licensing Component that does the following things for you:

1. Obtains the Hardware Key from the End User system.

2. Sends a request to the licensing authority (either the Deployment Licensing Service or Deployment Proxy Service).

3. Stores the License Key into the registry on the end user's machine.

NOTE: This is the preferred method since it requires very little manual intervention or no intervention at all, depending on whether or not you have decided to distribute individual access keys to end users explicitly.


The Manual Scenario

The Manual scenario consists of the following:

1. You distribute a unique Access Key to the End User from the pool of created access keys.

2. The end user enters the access key when the installation program prompts for it.

3. As an alternative to steps 1 and 2, an Access Key can be automatically obtained from the pool available for your application. In this case, no input from the end user is required (i.e. call GetLicKeyAuto and GetHdwKey methods with the accKey argument as an empty string).

4. The Licensing Component is used to form a Hardware Key that is reported to the end user.

5. The end user communicates the hardware key to you (through e-mail, Web portal, etc.).

6. You exchange the hardware key for a License Key either by using the End User Licensing Utility or Using the Deployment Licensing Service to Generate License Key directly (the latter is for Server License only).

7. You communicate the license key back to the end user (through e-mail, Web portal, etc.).

8. The end user passes the license key to the Licensing Component (this is usually done via the registration process).

9. The Licensing Component stores the License Key in the registry.

10. If an error occurs, the grace period is activated.

When using the Manual Licensing Scenario, once you have added licensing calls to your application, as explained in the previous section (Adding Licensing Calls to Your Application), you need to add calls to the Licensing Component. The Licensing Component facilitates the process of obtaining a License Key bound to the End User's system. This is typically done during the ImageGear-based solution installation, but you might want to consider providing a separate registration utility (or menu item in your application) if you are licensing manually or to handle errors that may occur during the installation.

Accessing the Licensing Component from the installer is typically done using a script that is executed during installation (AccuSoft provides a sample VB Script and a sample MSI-package that demonstrate both the automatic and manual scenarios. See Licensing Component Wrapper). The Licensing Component allows you to implement two scenarios - an Automatic Licensing Scenario and a Manual Licensing Scenario. You can use either scenario to obtain a license for the end user's machine, although the automatic method is easier to use.

See Also:

Licensing Component API Reference

Deploying Your Product

Acquiring an Access Key for the End User's Machine

With the Server License model, you can choose whether you want to distribute individual Access Keys for each end user, or not. There are tradeoffs with either approach:

  • If you choose to distribute individual access keys, your application is protected at no cost for you. You get the benefit of licensing protection from AccuSoft, but you have to manage your pool of access keys with the Vendor Licensing Utility yourself.
  • If you choose not to distribute individual access keys, then the Licensing Component automatically obtains an access key and licenses the product on the end user's machine. In this case, you don't have to manage your pool of access keys with the Vendor Licensing Utility, but your software is not protected against unauthorized distribution. As a result, anyone installing it will automatically obtain an ImageGear license thus decrementing the total number of available licenses from your license pool.
NOTE: If you choose not to distribute individual access keys, you should use the GetLicKeyAuto and GetHdwKey methods of the Licensing Component with their first argument (accKey) as an empty string.

Transferring your license to new hardware

If you choose to distribute individual access keys to end users then you will be assigning an access key to each end user's machine. Should the end user need to upgrade their machine, they can re-use the same access key for the new machine. There is a limit on how often a machine can be changed. This frequency is limited to the 45 days by default, but it can be changed for each deployment pool per request to AccuSoft.

If you choose to acquire access keys automatically, then you will need to use the LicenseInfo API of the Licensing Component to help end users transfer their access keys into new hardware. For example, you might want to develop a license transfer utility or provide this functionality from within your application. This will allow the end users to extract the access key (that was automatically obtained) from the registry on the old machine and store it onto the new machine. The limitation on the frequency of hardware upgrades applies to this method as well.

See Also:

Server Licensing

About Web-Based Licensing Utilities

User Licensing

The Automatic Scenario

The Manual Scenario

License Administration for the Server Deployment Model

Setting License Email Notifications

Licensing Component API Reference


About Web-Based Licensing Utilities

Before we discuss Application Preparation, you should be aware that there are two AccuSoft Web-based licensing utilities you will use with Server licensing: Vendor Licensing Utility and End User Licensing Utility.


Vendor Licensing Utility

The Vendor Licensing Utility (WebDeployClient utility) is the Web application that allows you to:

  • Browse solutions, deployment pools, and the attributes of both including the: Solution Name and Solution Key.
  • View the list of licensed product features and versions, e.g. CORE, OCR, Barcode, PDF, etc. for ImageGear Professional.
  • Generate new Access Keys and obtain existing access keys from license pools.

To run the Vendor Licensing Utility (WebDeployClient utility) enter the following URL:

https://www.accusoft.com/Licensing/v1/WebDeployClient/Login.aspx

into Internet Explorer and press Enter.

In the WebDeployClient Entry screen, enter the Username and Password provided to you by AccuSoft, and begin to manage your deployment solutions.

Integrating the Vendor Licensing Utility Functionality into Your System

The Deployment Licensing Service is implemented as a .NET Web Service; the following Deployment Licensing Service API has to be used to accomplish this (C# notation is used):

// obtains all solution names
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStrArr GetSolutionNames();
// obtains solution key for the solution
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStr GetSolutionKey( string solutionName);
// obtains names of all the pools associated with the solution
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStrArr GetPoolNames( string solutionName);
// creates new access keys for the specified solution and pool
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStrArr CreateNewLics( string solutionName,
string poolName, int nLics, bool sendKeys);
// obtains all access keys for the specified solution and pool
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStrArr GetAccKeys( string solutionName, string
poolName,
int startIndex, int numbKeys);
// this method returns pool attributes for the pool whose name
is passed in as a parameter
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSDepPool GetPoolInfo (string solutionName,
string poolName);
See Also:

Using the Deployment Licensing Service to Generate License Key

Setting License Email Notifications

Deployment Proxy Service (DPS)

Generating Access Keys

The Vendor Licensing Utility (WebDeployClient utility) can be used to generate Access Keys. After logging in to the utility and selecting the solution and deployment pool, the following screen is presented:

To generate access keys:

1. Specify the number of keys you wish to generate in the Number of new keys field.

2. If you want to download the new keys once they are created, click the Download new keys checkbox before generating the new keys.

3. Click the Create new access keys button to generate the specified number of access keys.

NOTE: To download all access keys available for this pool, click the Download all access keys button. This is non-reversible, so be sure you want to retrieve all your access keys before pressing this button.
NOTE: You will only need to use the Vendor Licensing Utility to generate access keys if you have decided to distribute access keys for end users explicitly. However even if you have decided to obtain access keys automatically using the Licensing Component, you can still use the Vendor Licensing Utility to retrieve the access keys that were automatically generated.
See Also:

Vendor Licensing Utility

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


End User Licensing Utility

The End User Licensing Utility (WebDeployUser utility) is the Web application that allows to generate a License Key based on the Hardware Key. (This is used in the manual mode process).

To run the End User Licensing Utility (WebDeployUser utility) enter the following URL:

https://www.accusoft.com/Licensing/v1/WebDeployUser/WebDeployUser.aspx

in Internet Explorer and press Enter.

In the WebDeployUser Entry screen, type your Hardware Key and press the Download License button to get your License Key.

See Also:

Server Licensing

The Manual Scenario


License Administration for the Server Deployment Model

If you are using the Server deployment model, you have the ability to integrate licensing service into your infrastructure to manage licensing in a way similar to your other business processes. You can setup the Deployment Proxy Service (DPS) on your site for proxying between AccuSoft and your customers and implement your own versions of the Vendor Licensing Utility and End User Licensing Utility. The Deployment Proxy Service (DPS) also allows you to license a product in a scenario where an end user's machine has limited Internet access.

See Also:

Deployment Proxy Service (DPS)

Integrating the Vendor Licensing Utility Functionality into Your System

Using the Deployment Licensing Service to Generate License Key

Setting License Email Notifications


Using the Deployment Licensing Service to Generate License Key

At times it might be convenient to use the Deployment Licensing Service API directly to generate a License Key based on the Hardware Key. For example, it can be useful in the The Manual Scenario, to set up a custom licensing portal on your site.

Here is the API description, C# notation:

// it takes hardware key and returns license key.
[WebMethod]
[SoapHeader("LicServiceHeader")]
    public AccuWSStrTriplet GenerateLicKey( string licParams);
See Also:

Server Licensing

The Manual Scenario

Setting License Email Notifications


Setting License Email Notifications

License Thresholding and Email Notification services are built into the AccuSoft Deployment Licensing Service. This provides the ability to setup e-mail notifications when a set percentage of the licenses are used up in the pool.

When establishing a new license pool with AccuSoft you can specify whether or not you would like to be notified and threshold value (if you have chosen to be notified). You can always update your preferences later by contacting AccuSoft.

See Also:

Server Licensing

License Administration for the Server Deployment Model

Licensing Component API Reference


Deployment Proxy Service (DPS)

License Administration involves the distribution and accounting of licenses against deployed solutions. Your involvement with License Administration depends upon the licensing model (Server, User) you choose, and whether you decide to utilize the Access Key or no Access Key licensing mechanism. (Please see the section Acquiring an Access Key for the End User's Machine for the detailed information).

On the one extreme with the Server model, AccuSoft can perform License Administration for you and your end users. The AccuSoft Licensing Service administers the deployment of License Keys directly with your end users over the internet, with little or no intervention on their part.

At the other extreme with the User model or the "no Access key" Server model, licensing is completely managed by you. Only periodic reconciliation of licensing totals is expected with AccuSoft for license accounting.

In between these two extremes, with the Server model, you can assume a participative role in License Administration with AccuSoft. To facilitate this, a Deployment Proxy Service (DPS) is provided that you can adapt to broker between your corporate software infrastructure, your end users, and AccuSoft's Deployment Licensing Service. This gives you the flexibility to design licensing into your current business model. As a simple example, the Deployment Proxy Service (DPS) would be installed on a server at your location. The DPS then communicates with AccuSoft's Deployment Licensing Service to administer the deployment of licenses. Once installed, the DPS can then be modified to work with any CRM systems that exists in your own business infrastructure.

In this section, we will review a simple DPS implementation that sets up the licensing proxy service for communication with AccuSoft's Deployment Licensing Service. Following this, the Deployment Licensing API will be presented for further adaptation at your location.

In a baseline implementation there are three steps to DPS-based License Administration:

  • Server Preparation
  • Deployment Proxy Service (DPS) Installation
  • Binding Licensing Component to DPS

Server Preparation

License Administration is typically executed on a Microsoft Windows 2000 Server platform. The Deployment Proxy Service (DPS) is implemented as a .NET Web Service, working through the Microsoft Internet Information Server (IIS). So server setup involves setting up:

  • IIS - Internet Information Server
  • Microsoft .NET Framework
  • .NET Framework 'machine.config' file

Microsoft's Internet Information Server (IIS) is typically installed during a Windows 2000 Server installation. Verify that you have IIS installed on your server by checking that the C:\InetPub\wwwroot directory exists. This is the default location for IIS. If IIS is not installed, add the IIS web server components to the default directory (C:\InetPub\wwwroot).

The Microsoft .NET Redistributable Package can be downloaded from Microsoft's Web site at the following link:

http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/829/msdncompositedoc.xml

It also contains installation requirements for the Microsoft .NET Redistributable Package.

Since some of the Deployment Licensing Service (DLS) methods may take some time to execute, AccuSoft recommends that you make the following modifications to the machine.config file after you have installed Microsoft .NET Framework:

1. Locate the file. On most PCs it would be at: C:\WINDOWS\Microsoft.NET\Framework\v1.0.3705\CONFIG\machine.config

2. In the file locate the processModel tag. The full path to it is:

<configuration>
<system.web>
<processModel>

3. Find the responseDeadlockInterval parameter within the processModel tag. By default it looks like:

responseDeadlockInterval="00:03:00"
Its format is [Infinite | HH:MM:SS]

4. Change the value to "00:30:00".

Deployment Proxy Service (DPS) Installation

Next, the Deployment Proxy Service (DPS) needs to be installed on the server where IIS and the .NET Framework were installed. For this example, we will use a zipfile (DplProxy.zip), available from AccuSoft, which contains a set of files for setting up a baseline DPS on your server to communicate with AccuSoft's Deployment Licensing Service. The first step is to extract the files under your Web Server (C:\InetPub\wwwroot), or to move them there after extraction. This will create a folder named "Licensing". You can extract the files in any folder, as long as you set up a virtual directory pointing to the folder where you unzipped the files.

From the IIS console, you then need to make sure that this "Licensing" folder is setup as an application. This can be done by right clicking on the folder and selecting Properties. Under the application settings section of the Directory tab, select the "create" button. This will create an application for this folder. The default of "licensing" will suffice, but you may name the application anything you'd like. The DPS is now setup with the Proxy Service on your server.

Binding Licensing Component to DPS

The Licensing Component has the property SrvURL that needs to be set to the URL of the Deployment Proxy Service like this (VB Script notation):

objLic.srvURL = "https://www.yoursite.com/licensing/dps/
dps.asmx"

DPS Source Code

AccuSoft provides the source code for the Deployment Proxy Service. While you don't have to use the source code it can serve as an example if you choose to modify the provided proxy to your needs or develop your own proxy. The code is written in C# and can be compiled using MSVS .NET.

See Also:

Integrating the Vendor Licensing Utility Functionality into Your System

Using the Deployment Licensing Service to Generate License Key

Setting License Email Notifications


Deploying Your Product

The first step in deploying your application is to package the required ImageGear run-time components. To do this, you run the Deployment Packaging Wizard to identify and generate the ImageGear run-time components required by your application. The Deployment Packaging Wizard packages the required components and stores them into a specified output folder, creating subfolders for the run-time and licensing components.

NOTE: When deploying the ActiveX Recognition component, it's necessary to also register one of the third party DLLs identified by the Deployment Packaging Wizard. The name of this third party DLL is IPRO.DLL.


Running the Deployment Packaging Wizard

To package the required ImageGear run-time components, do the following:

1. From the Start menu, choose .../Programs/AccuSoft/ImageGear/Deployment Kit folder and run the Deployment Packaging Wizard program.

2. Enter the path where you want to place the components and click the Next button to continue.

3. In the ImageGear Run-Time Components form, select the type of ImageGear run-time components you would like to generate, then select the components you would like to include into the installation package for your application. Click Next to continue.

4. In the ImageGear Licensing Components form, check whether you want to generate the ImageGear licensing components, add the Server Licensing Utility, or to have no licensing (default for User). Click the Next button to continue.

5. Finally, you can see a list of all the selected components that will be generated for your deployment. If this looks correct, click the Finish button to complete the Deployment Packaging process.

Once the Deployment Packaging process is finished, the Deployment Packaging Wizard reports its successful completion.

Now you can take the files that the Deployment Packaging Wizard created for you and include them into the installation package along with your application.

See Also:

About Web-Based Licensing Utilities

Creating an Installer

Appendix B: Troubleshooting


Creating an Installer

With Server licensing using either the Automatic or Manual scenario, to prepare your Application for distribution, you create an Installer for the Application and include any required ImageGear components. While this varies based on your application, in general it includes the following:

1. Replace config.txt with the one given to you for deployment. This file is located at C:\Program Files\AccuSoft\ImageGear v15\[ImageGear Edition]\LDK\Config.

2. Create an Installer (see Example.msi - a Wise installer example, that is located at C:\Program Files\AccuSoft\ImageGear v15\[ImageGear Edition]\LDK\Samples\MSI). The config.txt file that you replace above is added to the installer.

3. Add the Runtime and Licensing components generated when you ran the DPW.

4. Rename and save the Installer (Example: myinstaller.msi).

Licensing Component Wrapper

A Licensing Component Wrapper is provided for you in the form of a sample VB-script file that demonstrates how to implement different licensing scenarios using the Licensing Component, and proposes default handling for all error situations. The sample VB-script file (AccuLicClient.vbs) is located in the \Samples\VBScript directory of your Licensing Deployment Kit installation.

Also, there is a sample MSI installation file with the VB-script wrapper integrated into it. The sample MSI installation file (Example.msi) is located in the \Samples\MSI directory of your Licensing Deployment Kit installation. This MSI sample can be taken and integrated into your installer.

See Also:

Licensing Component API Reference

Licensing Component Error Codes and Messages


ImageGear Licensing API Reference

This section provides you with the detailed reference for the following ImageGear licensing API:

  • DLL version :
    • IG_lic_OEM_license_key_set
    • IG_lic_solution_key_set
    • IG_lic_solution_name_set
  • Legacy ActiveX version (for ImageGear v13.x) :
    • OEMLicenseKeySet
    • SolutionKeySet
    • SolutionNameSet
  • ActiveX version (for ImageGear v15.x):
    • IGLicense object
      • GetMetaAttr
      • SetOEMLicenseKey
      • SetSolutionKey
      • SetSolutionName
      • Type
  • .NET 2.0 version:
    • ImGearLicense class
      • SetOEMLicenseKey
      • SetSolutionKey
      • SetSolutionName


DLL version

This section provides you with the detailed reference for the following ImageGear licensing API:

    • IG_lic_OEM_license_key_set
    • IG_lic_solution_key_set
    • IG_lic_solution_name_set


IG_lic_OEM_license_key_set

Group: DLL version

Declaration:

AT_ERRCODE  ACCUAPI  IG_lic_OEM_license_key_set( LPCHAR
lpLicenseKey );

Arguments:

lpLicenseKey
The string of ImageGear license key.

Description:

This function specifies the License Key to ImageGear for the User deployment licensing model.

Bits Per Pixel: N/A

Return Value:

Returns the result code of this function call.


IG_lic_solution_key_set

Group: DLL version

Declaration:

VOID ACCUAPI IG_lic_solution_key_set (
    DWORD dwKey1,
    DWORD dwKey2,
    DWORD dwKey3,
    DWORD dwKey4
    );

Arguments:

dwKey1
Key1 component of the solution key
dwKey2
Key2 component of the solution key
dwKey3
Key3 component of the solution key
dwKey4
Key4 component of the solution key

Description:

This function specifies your deployment Solution Key for the Server/User deployment licensing models.

Bits Per Pixel: N/A

Return Value:

None.


IG_lic_solution_name_set

Group: DLL version

Declaration:

AT_ERRCODE ACCUAPI IG_lic_solution_name_set (LPCHAR
lpSolutionName)

Arguments:

lpSolutionName
The license solution name.

Description:

This function provides the Solution Name of the ImageGear license for the Server/User deployment licensing models.

Bits Per Pixel: N/A

Return Value:

Returns the result code of this function call.


Legacy ActiveX version (for ImageGear v13.x)

This section provides you with the detailed reference for the following ImageGear licensing API:

    • OEMLicenseKeySet
    • SolutionKeySet
    • SolutionNameSet


OEMLicenseKeySet

Group: Legacy ActiveX version

Description:

This method sets the License Key of ImageGear for the User deployment licensing model. To check whether this method call is successful, you can use the ErrorCheck method of ImageGear.

Declaration:

OEMLicenseKeySet(LicenseKey as BSTR)

Parameters:

LicenseKey
The string of ImageGear License Key.

Bits Per Pixel: N/A

Return Value:

None.


SolutionKeySet

Group: Legacy ActiveX version

Description:

This method sets your deployment Solution Key for the Server/User deployment licensing models. To check whether this method call is successful, you can use the ErrorCheck method of ImageGear.

Declaration:

SolutionKeySet( iKey1 as Long, iKey2 as Long, iKey3 as Long,
iKey4 as Long)

Parameters:

iKey1
Key1 component of the solution key
iKey2
Key2 component of the solution key
iKey3
Key3 component of the solution key
iKey4
Key4 component of the solution key

Bits Per Pixel: N/A

Return Value:

None.


SolutionNameSet

Group: Legacy ActiveX version

Description:

This method sets the Solution Name of your ImageGear license for the Server/User deployment licensing models. To check whether this method call is successful, you can use the ErrorCheck method of ImageGear.

Declaration:

SolutionNameSet (SolutionName as BSTR);

Parameters:

SolutionName
The license solution name.

Bits Per Pixel: N/A

Return Value:

None.


ActiveX version (for ImageGear v15.x)

This section provides you with the detailed reference for the following ImageGear licensing API:

    • IGLicense object
      • GetMetaAttr
      • SetOEMLicenseKey
      • SetSolutionKey
      • SetSolutionName
      • Type


IGLicense

Group: ActiveX version

Description:

This object is contained inside IGCoreCtl control and provides access to the licesning API.

Interface:

IIGLicense

Class Members:

Type
property
This property returns the type of product license.
GetMetaAttr
method
This method gets a meta attribute by name.
SetOEMLicenseKey
method
This method sets OEM license key.
SetSolutionKey
method
This method sets solution key.
SetSolutionName
method
This method sets solution name.


GetMetaAttr

Group: ActiveX version

Description:

This method gets a meta attribute by name.

Declaration:

GetMetaAttr (sAttrName As String) As String

Parameters:

sAttrName
The name of the meta attribute

Return value:

The value of the meta attribute

Bits Per Pixel: N/A

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


SetOEMLicenseKey

Group: ActiveX version

Description:

This method sets OEM license key.

Declaration:

 SetOEMLicenseKey (sLicKey As String)

Parameters:

sLicKey
License key

Return value: N/A

Bits Per Pixel: N/A

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


SetSolutionKey

Group: ActiveX version

Description:

This method sets the solution key.

Declaration:

SetSolutionKey (Key1 As Long, Key2 As Long, Key3 As Long, Key4
As Long)

Parameters:

Key1
Key1 element of the solution key
Key2
Key2 element of the solution key
Key3
Key3 element of the solution key
Key4
Key4 element of the solution key

Return value: N/A

Bits Per Pixel: N/A

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


SetSolutionName

Group: ActiveX version

Description:

This method sets the solution name.

Declaration:

SetSolutionName (sSolutionName As String)

Parameters:

sSolutionName
Solution name

Return value: N/A

Bits Per Pixel: N/A

Sample: Core

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Type

Group: ActiveX version

Description:

This property returns the type of product license.

Property Summary:

Data Type:
enumIGLicenseType
Default Value:
N/A
Access:
Read only
Settings:
See enumIGLicenseType values
Bits Per Pixel:
N/A
Sample:
None


.NET 2.0 version

This section provides you with the detailed reference for the following ImageGear licensing API:

    • ImGearLicense class
      • SetOEMLicenseKey
      • SetSolutionKey
      • SetSolutionName


ImGearLicense

Group: .NET version

Description:

This class manages licensing data (i.e., license type and key).

Assembly:

ImageGearV2n.dll

Declaration:

public sealed class ImGearLicense

Class Members:

SetOEMLicenseKey
method
Sets OEM license key.
SetSolutionKey
method
Sets solution key.
SetSolutionName
method
Sets name of solution.

Remarks:

To be able to use any ImageGear for .NET functionality, licesing information must be provided. For more information see ImageGear for .NET licensing scheme.


SetOEMLicenseKey

Group: .NET version

Description:

Sets OEM license key.

Declaration:

static void SetOEMLicenseKey(string licKey)

Parameters:

licKey
Obtained from AccuSoft OEM license key.

Remarks:

In case of OEM license type, there is no need to call any other members of ImGearLicense class.


SetSolutionKey

Group: .NET version

Description:

Sets solution key.

Declaration:

static void SetSolutionKey(int key1, int key2, int key3, int
key4)

Parameters:

key1
Key1 part of solution key.
key2
Key2 part of solution key.
key3
Key3 part of solution key.
key4
Key4 part of solution key.

Remarks:

Solution name must be set up in addition to key.


SetSolutionName

Group: .NET version

Description:

Sets the name of the solution.

Declaration:

static void SetSolutionName(string SolutionName)

Parameters:

SolutionName
Name of solution.

Remarks:

Solution key must be set up in addition to name.


Licensing Component API Reference

The Licensing Component's purpose is to obtain a license key bound to the end user's system.

The Licensing Component performs the following functions:

  • Obtains the Hardware Key of the End User system.
  • Sends a request to the licensing authority (either Deployment Licensing Service or Deployment Proxy Service).
  • Stores the License Key into the registry on the end user machine.

As mentioned in the section on Licensing Administration, you can set up the Deployment Proxy Service on your Web site and program the Licensing Component to communicate with the Deployment Proxy Service instead of the Deployment Licensing Service

Also, using the Licensing Component you can set up different custom End User licensing scenarios. For example, directing end users to come to a Web application hosted on your Web site to get a License Key.

The Licensing Component implements licensing via the following API.


ConfigPath

Property ConfigPath of BSTR type.

This property is used to set and get a path to the deployment configuration file.

NOTE: The Licensing Component has to be initialized with the path to the `config.txt' file before it can perform any of its functions. The `config.txt' file is provided to you by AccuSoft for each ImageGear-based solution. You need to distribute it with the Licensing Component in order for the component to work.


GetEvalPeriod

HRESULT GetEvalPeriod ([out, retval] long* EvalPeriod)

This method obtains the remianing time on an evaluation (in days). Returns EvalPeriod < 0 in case if the evaluation period is expired.


GetHdwKey

HRESULT GetHdwKey ([in] BSTR accKey, [out, retval] BSTR* hdwKey)

This method obtains a hardware key from the current machine and returns it (as hdwKey).

If you choose not to distribute individual access keys, you need to provide the accKey argument as an empty string.

See Also:

Acquiring an Access Key for the End User's Machine


GetLicKeyAuto

HRESULT GetLicKeyAuto ([in] BSTR accKey)

This method obtains a License Key for the end user's system using the automatic scenario. It takes an Access Key as its input parameter, and stores the obtained license key in the registry.

If you choose not to distribute individual access keys, you need to provide the accKey argument as an empty string.

See Also:

Acquiring an Access Key for the End User's Machine


LicenseInfo

Property LicenseInfo of BSTR type

This property is used to transfer license information into new system hardware.

To transfer the license information into new system hardware, do the following:

1. Get the LicenseInfo value and store it in a safe place.

2. Change the system hardware.

3. Set the LicenseInfo to the value you saved in step (1).

4. Run the GetLicKeyAuto method (or it's manual analog) to obtain a license for the new system hardware.


LicKey

Property LicKey of BSTR type.

This property stores the License Key to the registry when it is set, and reads it from the registry during the get operation.


ResultCode

Property ResultCode

This property can be used to contain any of the error codes described in Licensing Component Error Codes and Messages.


ResultString

Property ResultString

This property contains the string descriptions of errors.


SrvURL

Property SrvURL of BSTR type.

This property is used to set and get the URL path to the licensing web service. The default is the URL path to AccuSoft's Deployment Licensing Service.


StartEvalPeriod

HRESULT StartEvalPeriod()

This method sets an evaluation licensing mode for the product and starts an evaluation period. This method is provided so you can distribute an evaluation version of your application, without having to distribute Access Keys to people who would like to evaluate your software. Using this method you can license ImageGear on the end user's system for a limited time - the default is 30 days, but it can be customized per request to AccuSoft. If the evaluators purchase your software, you can then issue them an access key using either the automatic or manual scenarios to obtain a permanent ImageGear license, just as AccuSoft does for its evaluators.


Error Codes

Licensing Component Error Codes and Messages

The following are the Licensing Component error codes:

Error constant
Error description
LDK_SUCCESS
No error.
LDK_ERR_GENERAL
General error.
LDK_ERR_INET_CONN_BROKEN
No Internet connection.
LDK_ERR_REGISTRY_ACCESS
Can't write license key to the registry. This can happen if a user doesn't have administrative privileges.
LDK_ERR_LOCKOUT
Auto mode only, it should happen when we receive several requests from the same IP address within a short period of time with the wrong access keys.
LDK_ERR_HDW_INCOMPATIBLE
Manual mode only, it means that the utility had to verify the hardware ID and didn't match the one stored in the license.
LDK_ERR_HDW_ID_QUERY
Can't get the hardware ID of the client system. This should not happen unless something goes really wrong with the system.
LDK_ERR_HDW_ID_RELEASE
Auto mode only, this happens when someone is trying to change hardware ID within 45 days after a previous hardware ID has been associated with the license.
LDK_ERR_NO_LICENSE_KEY
No license key passed as a parameter.
LDK_ERR_INVALID_LICENSE_KEY
License key passed as a parameter is invalid.
LDK_ERR_NO_ACCESS_KEY
No access key passed as a parameter.
LDK_ERR_INVALID_ACCESS_KEY
Access key passed as a parameter is invalid.
LDK_ERR_INVALID_SOLUTION_NAME
Invalid solution name.
LDK_ERR_NO_CONFIG_FILE
Cannot find the configuration file.
LDK_ERR_INVALID_CONFIG_FILE
Invalid configuration file.
LDK_ERR_NOT_INITIALIZED
Licensing Component is not initialized.
LDK_ERR_NO_LICENSE_INFO
No license info passed as a parameter.
LDK_ERR_INVALID_LICENSE_INFO
License info is invalid.
LDK_ERR_INCOMPATIBLE_LICENSE
This license is not compatible with your deployment configuration.
LDK_ERR_OBTAINIG_LICENSE
Can't obtain license from the system.

The following are the default Licensing Component Wrapper error messages:

Error constant
Error description
MSG_LDK_SUCCESS
"The product has been successfully licensed!"
MSG_LDK_ERR_GENERAL
"An unknown error has occurred during licensing. Please contact your vendor."
MSG_LDK_ERR_INET_CONN_BROKEN
"No Internet connection is available. Please check your connection and retry."
MSG_LDK_ERR_REGISTRY_ACCESS
"Unable to write the License Key to the registry. Please verify that you have administrative privileges."
MSG_LDK_ERR_LOCKOUT
"Licensing has been locked out after multiple requests. Verify that you have a valid Access Key, then contact your vendor."
MSG_LDK_ERR_HDW_INCOMPATIBLE
"This license is not compatible with your system hardware, please contact your vendor."
MSG_LDK_ERR_HDW_ID_QUERY
"Unable to obtain the Hardware ID of your system. Please contact your vendor."
MSG_LDK_ERR_HDW_ID_RELEASE
"Your Hardware ID has changed. Please contact your vendor."
MSG_LDK_ERR_NO_ACCESS_KEY
"No Access Key was received. Please retry and enter an Access Key."
MSG_LDK_ERR_INVALID_ACCESS_KEY
"The Access Key entered appears invalid. Please retry, then contact your vendor."
MSG_LDK_ERR_NO_LICENSE_KEY
"No License Key was received during licensing. Please retry, then contact your vendor."
MSG_LDK_ERR_INVALID_LICENSE_KEY
"The License Key received appears invalid. Please retry, then contact your vendor."
MSG_LDK_ERR_INVALID_SOLUTION_NAME
"The Solution Name is invalid. Please contact your vendor."
MSG_LDK_ERR_NO_CONFIG_FILE
"Can't find configuration file. Please contact your vendor."
MSG_LDK_ERR_INVALID_CONFIG_FILE
"An invalid configuration file was received. Please contact your vendor."
MSG_LDK_ERR_NOT_INITIALIZED
"Licensing Component is not initialized. Please contact your vendor."

ImageGear Licensing Error Codes

The following table describes general ImageGear licensing errors that can occur at run-time if the product is not licensed properly:

Error constant
Error code
Error description
Comment
IGE_FAILURE
-1
Failure to open registry value
This error occurs if the license key cannot be obtained from the registry. Server licensing model only.
IGE_NOT_LICENSED
-2
Invalid license key
This error occurs if the license key passed to the ImageGear is invalid. All licensing models.
IGE_NOT_LICENSED
-2
Version is not licensed
This error occurs if the license key is valid, but does not license the current version of the product. All licensing models.
IGE_NOT_LICENSED
-2
Your evaluation license has expired. Please run AccuSoft License Manager if you would like to get a new license
This error occurs if the evaluation license key has expired. Evaluation licensing only.
IGE_NOT_LICENSED
-2
The product is not licensed for this machine
This error occurs if the evaluation license key is not compatible with a hardware key for the current machine. Evaluation licensing only.
IGE_NOT_LICENSED
-2
The hardware ID of this machine doesn't match license information. Please run AccuSoft License Manager on this machine to add its hardware ID to your license.
This error occurs if the development license key is not compatible with a hardware key for the current machine. Development licensing only.
IGE_NOT_LICENSED
-2
Solution name is required
This error occurs if an empty solution name is passed as a parameter. All licensing models.
IGE_NOT_LICENSED
-2
Invalid solution name
This error occurs if the solution name from the license doesn't match the solution name passed as a parameter. All licensing models.
IGE_NOT_LICENSED
-2
Invalid solution key
This error occurs if the solution key from the license doesn't match the solution key passed as a parameter. All licensing models.
IGE_NOT_LICENSED
-2
Invalid executable name
This error occurs if the executable name from the license doesn't match the name of the application executable. Deployment licensing models locked to the executable only.
IGE_NOT_LICENSED
-2
Please use OEM licensing API with this license
This error occurs if the User/OEM license is being initialized via the registry. The User/OEM license has to be initialized by using the OEM API. User licensing model only.
IGE_NOT_LICENSED
-2
Please do not use OEM licensing API with this license
This error occurs if a non-User/OEM license is being initialized via the OEM API. Only the User/OEM license has to be initialized by using the OEM API. Server licensing model only.

ActiveX Errors

The following table describes ImageGear ActiveX-specific licensing errors that can occur at run-time if the ImageGear ActiveX control is not licensed properly:

Error constant
Error code
Error description
Comment
IGE_NOT_LICENSED
-2
COM licensing method is required to be used
This error occurs if ImageGear ActiveX is running under a web browser and being licensed via the API. If licensing via the web, ImageGear ActiveX has to be license by using the COM license binding. All licensing models.
IGE_NOT_LICENSED
-2
Licensing ambiguity. Cannot use both API licensing method and license binding method
This error occurs if ImageGear ActiveX is being licensed via the API, as well as license binding. All licensing models.


Appendix A: Terminology

Access Key

The key provided to the end user for licensing the application. Uniquely identifies each license issued by AccuSoft. You can only generate as many different access keys as the total number of deployment licenses purchased. One an access key needs to be associated with each end user's machine, you can choose to either: distribute access keys to end users explicitly, or use the Licensing Component to acquire access keys automatically behind the scenes.

Concurrent

Licenses that are co-used by a specific number of users and that are counted as 1 license.

Deployment Kit

A set of wizards and tools that help you license your applications.

Deployment Licensing Service

The Web service at AccuSoft that handles all licensing requests.

Deployment Packaging Wizard

The tool included in the Deployment Kit that helps you package the appropriate ImageGear runtime components.

Deployment Pool

Each solution can have several deployment pools associated with it. A Pool is a set of licenses of the same type. When a pool is set up, the product features, the deployment model, and other information are associated with it. All the licenses from the same pool have the same attributes, except for hardware parameters (if bound to hardware parameters).

Deployment Proxy Service

The Web service running at your site for proxying between the Deployment Licensing Service and the Licensing Component running on the end user's system.

End User

The customer using your application.

End User Licensing Utility

The Web application you use to generate license keys based on hardware keys.

Hardware Key

The key dynamically constructed on the end user's machine by combining the access key and hardware parameters of the machine. Obtained on the end user's machine by combining the access key and the hardware parameters of the end user system. This typically happens during an installation process using the Licensing Component.

ImageGear Runtime Components

The ImageGear runtime components that are licensed for deployment with your application.

License Key

The key containing information about ImageGear licensed features and hardware parameters of the target machine (if bound to hardware parameters). Generated by the Deployment Licensing Service in exchange for the hardware key, and stored in the End User's system registry.

Licensing Component

A component that obtains an ImageGear license for the end user's machine.

Licensing Component Wrapper

A VBScript wrapper around the Licensing Component with methods for handling error result codes, etc. This wrapper serves as a template that can be modified as needed.

LPK

An LPK file is a file that licenses ImageGear ActiveX controls when running on a Microsoft Internet Explorer Web Browser. This file must be created for all ActiveX components that require licensing, regardless of manufacturer.

Named

Licenses that are counted as they are deployed to individual users.

Server License

Bound to hardware parameters. Therefore an individual node-locked License Key has to be generated for each system where the ImageGear-based solution is used. With this model, the Licensing Component running on the end user's machine can communicate directly to the Deployment Licensing Service but you also have the choice of setting up a Deployment Proxy Service at your site - in this case Licensing Component would communicate through this proxy service.

Server Licensing Utility

A standalone program that can be used to generate a license key given a configuration file.

Solution Key

A combination of 4 32-bit integers that are unique for each solution using AccuSoft's technology. This key is generated and assigned to your solution by AccuSoft.

Solution Name

The name of your ImageGear-based application.

User License

Not bound to hardware parameters. Therefore only one license key is required per ImageGear-based application.

Vendor

The Accusoft customer who is developing an ImageGear-based application (you).

Vendor Licensing Utility

The Web application you use to view deployment pools and obtain access keys.


Appendix B: Troubleshooting

This Appendix reviews potential issues you may experience during the licensing process.

Some general notes about licensing you should be aware of:

  • This was designed as an Internet-based licensing process. It is best if your end users have an Internet connection to get a License Key. The only exceptions are if you are a User License Licensee, or if you are distributing licenses manually on a very limited basis.
  • Once an application is licensed, no further Internet connection or interaction is required until you re-install the system or restore a previously backed-up system onto new hardware.
  • End Users are blocked from using the same Access Key to install the same application on different hardware. This is to prevent piracy.
  • A lightweight Licensing Component will grant a grace period to your end user whenever there is a licensing issue for any reason. You can modify the end user instructions to solve the problem.
See Also:

End User has no Internet connection

Internet connection is temporarily broken during installation

Transferring ImageGear license into new hardware system

Reinstallation of ImageGear-based application into the same hardware system

The End User's Windows registry changed (licensing info lost)

Implementing Automatic Licensing Scenario on Windows 98


End User has no Internet connection

User License level licensing or manual licensing is required if applications are going to be deployed to end users who will never have an Internet connection. Please be advised that manual licensing requires interaction on your part when installing the application on the end-user system.


Internet connection is temporarily broken during installation

In this case, the auto-licensing method will return an error, and the grace period will be activated. The grace period will allow your application to function normally during a limited period of time, and you will need to repeat the licensing process (either manual, or automatic after connection is restored).


Transferring ImageGear license into new hardware system

An error can occur during installation of your application into a new machine or as the result of restoring a backup into different system hardware.

When you need to transfer an ImageGear license onto new system hardware, you have to use the same Access Key that was used to license ImageGear on the old system.

If you are not distributing access keys to the end users you will need to provide a mechanism for transferring an access key into a new machine using the Licensing Component LicenseInfo API as described below.

The Deployment Licensing Service will issue a new license key if a certain number of days (default = 45) have already lapsed since the previous license key has been generated for the same access key with different hardware parameters. Otherwise end users would need to contact you, and you would need to call AccuSoft to authorize a license transfer.


Reinstallation of ImageGear-based application into the same hardware system

In this case, the license will be either found in the registry, or obtained from Deployment Licensing Service, regardless of when it was last requested.


The End User's Windows registry changed (licensing info lost)

In general, if the registry is corrupted it might make sense to reinstall the application or even the entire system. But if the licensing info is the only data deleted from the registry, the licensing process that is executed as a part of the installation/registration can be repeated to retrieve a License Key from the Deployment Licensing Service.


Implementing Automatic Licensing Scenario on Windows 98

If you are using the The Automatic Scenario (see also the GetLicKeyAuto method), AccuSoft Deployment Licensing ActiveX uses the Secure Socket Layer (SSL) and Transport Layer Security (TLS) Security Support Provider Interface for communication with the Deployment Licensing Service.

NOTE: Using a secure communication channel ensures that proprietary information, such as the Access Key, hardware parameters, and the License Key, are protected during communication between the end user's machine and the licensing service.

To support the encryption/decryption API by the SSL/TLS Security Support Provider on Windows 98 the following components have to be installed on your PC:

  • Internet Explorer 5.01 or later
  • Directory Service Client for Windows 98 (available on the Windows 2000 Server CD (\Client\Win9x\dsclient.exe)

In addition to installing the above components, the SChannel Security Support Provider must be enabled in the registry.

To enable the SChannel security package, please do the following:

  1. Locate the following key in the registry:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders

  1. Modify the following registry value:

Value Name: SecurityProviders

Data Type: REG_SZ

Value: Append ",schannel.dll" (with comma, no quotes) to previous string

NOTE: The above information is taken from the Microsoft Knowledge Base Article - 276245 (Encryption/Decryption Support for SSL/SSPI on Windows 95 and Windows 98). For more information please refer to http:// support.microsoft.com/default.aspx?scid=KB;en-us;q276245