*

Visual Basic 6 ISV Application Development Guide


Preface

Overview Of License Enabling Activities

Defining Your License Management Policies

Deciding API Choice

Coding Against The API

Example Of Single-User License Key Check

Example Of Server License Key Check (Professional Edition Only)

Developing multithreaded applications

Packaging Your Product

Next Steps


Preface

This document guides you through the specifics of the process of license-enabling your Visual Basic 6 product with EasyLicenser.  It adds detail to the overview of the EasyLicenser Visual Basic 6 DLL Interface module and C/C++ Run Time Library API that are presented in the EasyLicenser Concepts guide.

Overview Of License Enabling Activities

The activities encompass:

    1. Defining your license management policies with respect to grace periods, grace quotas and custom key management.
    2. Deciding which API to use, according to your needs.
    3. Coding against the API.
    4. Packaging your product to include the run time library and license key.

Defining Your License Management Policies

A (no pun intended) key decision you need to make at the onset is whether you wish to enforce locking your license keys to specific hardware and / or operating system. Although locking your key provides a high degree of protection, it is also a sales inhibitor, as it subjects your end-customer to onerous procedures both at the time you take their order and whenever customers want to relocate their product installation. The approach is also less portable across platforms. The next decision you need to make is what you want to lock your key to: proprietary hardware, or the logical operating system runtime environment. If the former, you will need to implement or obtain hardware and operating system specific code and plug it into the EasyLicenser runtime framework. If the latter, you can utilize EasyLicenser's built-in enforcement facilities.

When your product is licensed for time limited or metered use, you can decide on what you want to have happen when a license key check indicates an expiring or expired key.  You can define thresholds for generating warnings on expiring keys and grace periods or quotas to suppress generating errors when a quota or expiration date is exceeded.

EasyLicenser has built-in license management models, types and parameters.  If you have a specialized need for your own variation to the built-in policies, you can accomplish this by defining custom keys and post-processing these after performing the basic license key check.

The specific mechanics of accomplishing these tasks are described below.

Deciding API Choice

Two API calls are available with the EzLicenseInfo class for checking a license key:

If your application does not require customized license management, you can use either of the two API’s according to whether your product is a user or server product.  If your application requires custom key management, the application is responsible for following up the API call with a call to retrieve the custom key and directly invoke custom logic to process the custom key.

Coding Against The API

The specific details of the API are available as in-context comments in the DLL Interface module ezLicenseinfoVV.bas located at “vb6\src”.  Some simple examples will be illustrated below that show how the API’s are used in typical application scenarios.  Source and binary code for additional examples are provided in the “vb6\demo” directory. In particular, the "src\vb_demo.frm" application is a simple GUI application that presents a screen where you paste a license key and user name and click on a button to check the key and display its parameters. For details on the demo program and how to run it, see the description of the directory structure in the Setup, Management And Deployment Guide.

Example Of Single-User License Key Check

Suppose you have a desktop application such as a file management utility program that you sell to end consumers.

Whenever a new customer visits your web site and downloads your application and pays by credit card for a perpetual license to use it, your web site defines a serial number or user id, which is also used as the EasyLicenser user name input to a key your web site programmatically generates and emails to your customer.  The key that you generate is a User license model, of User license type.  It is not time limited and does not have a quota limit defined on it.

At product installation time, your product asks the user for the key, which is then stored in the operating system registry.  Subsequently, each time the user runs your product, it prompts your user for the user id authentication information.  Your code can take that user name input, retrieve the license key from the registry, and perform the license key check.

 

’Get license key and user name from registry and

’UI text box respectively

strLicenseKey = getLicenseKey()

strUserName = UsernameTextbox.Text

’Allocate license info context

ezLicInstance = allocLicenseInfo()

’Check license key, set license info context

iStatus = checkSingleUserLicenseKeyBasic(

ezLicInstance, _

strLicenseKey, _

iDaysLeftThreshold, _

iQuotaUsageToDate, _

iQuotaThreshold, _

iDaysGracePeriod, _

iQuotaGrace, _

strUserName _

)

If (iStatus >= 0) Then

show_warnings(ezLicInstance)

Else

MsgBox "The License key is invalid", vbCritical, "Error"

End If

’Deallocate license info context

freeLicenseInfo(ezLicInstance)

Example Of Server License Key Check (Professional Edition Only)

Suppose you have an application server product that you wish to license by the number of concurrent sessions on the application server.  You do not wish to lock the user into a specific host machine, therefore you adopt a “soft” logical host naming policy that allows your customers to reconfigure their networks without being required to contact you for new keys.

The key that you generate is of a Server license model, and Concurrent User license type.  At the time of generating the key, you specify an upper limit on the number of concurrent users according to what your customer paid for.  It is not time limited, and you do not define a quota limit on it.

Your server application is designed to load at startup time an application property text file that includes, among other items, the license key and the host name, similar to the following:

 

:

LicenseKey=tFy67+h=…
HostName=licensedHostName1

:

At the time of product installation, your customer is responsible for setting the above values correctly and for ensuring that multiple product installations having the same host name specification are not allowed to exist.

At run time, either periodically or in response to specific events such as session initiation, your product code can interrogate its environment to obtain the number of active sessions and the application properties and check the license:

 

’Get license key and host name from registry and

’UI text box respectively

strLicenseKey = getLicenseKey()

strHostName = getHostname()

’Get active-session count from application context

sessionCount = getSessionCount();

’Allocate license info context

ezLicInstance = allocLicenseInfo()

’Check license key, set license info context

iStatus = checkMultiUserLicenseKeyBasic(

ezLicInstance, _

strLicenseKey, _

iDaysLeftThreshold, _

iQuotaUsageToDate, _

iQuotaThreshold, _

iDaysGracePeriod, _

iQuotaGrace, _

strHostName, _

sessionCount

)

If (iStatus >= 0) Then

show_warnings(ezLicInstance)

Else

MsgBox "The License is invalid for the specified session count",

vbCritical, "Error"

End If

’Deallocate license info context

freeLicenseInfo(ezLicInstance)

Developing multithreaded applications

The Visual Basic 6 DLL Interface module and the C/C++ Run Time Library can be used in a multithreaded environment, subject to the constraints described in the C/C++ ISV Application Developer’s Guide.

Packaging Your Product

Your product packaging should include the file “ezLicenserlibVV.dll” located at “cpp\lib\win32”, which your product installer should deposit either in your product installation binary files directory or an operating system binary directory.  The installer should also programmatically update the PATH system environment variable to include the binary file directory.

Next Steps

Refer to the in-context comments in the DLL Interface module ezLicenseinfoVV.bas located at “vb6\src” for specific information on the EasyLicenser API’s that you will use while writing your Visual Basic 6 product’s license-enabling code.