Implementing EZ Trial and EZ Trigger

Refer to the Concept and Definitions topics EZ Trial and EZ Trigger for introductory information. A sample application EZTrial1 is included to give an reference implementation.

The most common form of security that is implemented with PLUS is trialware - a demo that runs for a certain period of time and can be unlocked into the retail version. Using EZ Trial allows you to achieve these common features with the least programming effort. The EZ Trial algorithm is described by the flow chart in the EZ Trial section of Concepts & Definitions chapter. The result is that your application will be in one of the following modes:

The sample application EZ Trial and EZ Trigger demonstrates one way to implement this form of licensing and is ready to compile and run for many programming languages. You may copy and paste this sample code into your application or use the systematic guide below.

Source Code Changes

1. Declare or define the pp_eztrial1() function to a module:

Declare Function pp_eztrial1 Lib "KeyLib32.DLL" (ByVal filename As String, ByVal password As String, ByRef errorcode As Long, ByRef lfhandle As Long) As Long

2. Declare or define the pp_eztrig1() function to a module:

Declare Function pp_eztrig1 Lib "KeyLib32.DLL" &_

(ByVal hwnd As Long, ByVal filename As String, ByVal password &_

As String, ByRef errorcode As Long) As Long

3. Create a subroutine or function called status change:

Public Sub StatusChange()

End Sub

4. In that subroutine for function call the pp_eztrial() function:

Dim result As Long, lfresult As Long, daysleft As Long

result = pp_eztrial1(App.Path & "\sample.ini", "password", lfresult, lfhandle)

5. On the Form_Load() event, call the subroutine or function StatusChanged:

StatusChanged

6. Now, add error handling code in the StatusChange subroutine/function. To do this, you must first declare/define the function by entering the following code in the main form or module:

Declare Sub pp_errorstr Lib "KeyLib32.DLL" (ByVal number As _

Long, ByVal buffer As String)

 Now go back to the StatusChange subroutine/function and enter the following code (can be modified to your preferences):

If result = 0 Then

MsgBox "File Error #" & result & " occurred - please contact Technical Support" 

End If

Also, realize that you can use a Select Case statement (similar to a switch statement). This will prevent a large amount of If, ElseIf, and Else statements from becoming a mess. Result is the returned value from pp_eztrial(). 0 means that there was an error when pp_eztrial() was executing. A select case statement would look like thise:

Select Case result

Case 0 

MsgBox "File Error #" & result ^ " occurred please contact Technical Support" 

End Select

7. If you want to limit functionality during the evaluation period (to encourage purchase), modify the Select Case statement like this:

Select Case result

Case 0:

' an error occurred 

Case 1:

' this is a retail product 

Case 2:

' this is a demo that hasn't expired 

Case 3:

' retail application failed software or hardware binding

Case 4:

' demo that has expired 

Case 5:

' clock has been turned back on demo 

Case 6:

' valid product in periodic expiration mode  

Case 7:

' The number of allowed users has been exceeded 

End Select

8. Add a menu option to display an EZ Trigger dialog box and act according to the result of the operation:

Private Sub mnuUnlock_Click()

Dim result As Long, lfresult As Long

' now run eztrig to possibly change the mode

result = pp_eztrig1(Me.hwnd, App.Path & "\sample.ini", "password", lfresult)

If result = 0 Then

If lfresult <> 0 Then 

MsgBox "File Error #" & lfresult & " occurred - please contact Technical Support" 

End If 

ElseIf result = ERR_INVALID_CODE_ENTERED Then

MsgBox "Invalid code entered!" 

Else

MsgBox "Action completed succesfully!" 

' call the Main subroutine again to reset all of our  

' indicators 

Unload Me 

End If

StatusChanged

End Sub

Set up Product Definition in LFEdit

Run LFEdit from Start / Programs / SoftwareKey Licensing System / PLUS. If using an evaluation copy, change the product name in the toolbar combo box to EZTrial1. Otherwise, click Product Definition menu then Setup. Click Add to create a new definition or select an existing one and choose Properties. It is important to change the Default: product name. On the License File Tab, be sure to change the password to the same value that you used for the password variable. Click on the Trigger Code tab. Choose values for Trigger Code seed and put that where the seed variable is, to differentiate yourself from other PLUS users. The evaluation copy of LFEdit does not permit changing the Trigger Code seed. Click on the EZ Trial Parameters Tab and change the properties as desired. Press F1 for a description of all of the fields and their purpose. You MUST leave "convert illegal copies to demo" checked. Click Ok to save all changes.

Create a License File in LFEdit

In LFEdit, click the New button on the toolbar. Click on the Expiration Fields Tab. Make sure the Expiration Type is D for Demo and that a hard expiration date is filled in. Even if you are letting the application run for an unlimited number of days, a hard expiration date must be filled in. To essentially disable the hard expiration date, fill in 12/31/2050. Save the License File.

Run Your Application

The application should run the number of days and times specified when you created the License File.

Activate the Application Using EZ Trigger™

Click on the menu option added to display the Trigger Code dialog. Write down the two numbers on the form. These two numbers are what your customer will give you by phone, fax, or e-mail. Run LFEdit. With the correct Product Definition selected in the toolbar, click on the Trigger Codes button (lock) on the toolbar. Select Code 18 if not using Hardware Binding (copy protection) or 31 if Hardware Binding was selected on the EZ Trial Parameters Tab. Click Select. Enter the two numbers previously written down and click Generate. Write this number down. This is the unlock code that will be given to the customer. Minimize LFEdit and enter this code into the application. You should see the "Activation Complete" message appear.

Using EZ Trial on a Network

Because most network installations do not maintain synchronized clocks, it is important that the last used time is not verified between installations, especially when License File Aliases are used. Be sure to turn off "Update last used time" in the EZ Trial Parameters tab of the product definition.

When deploying your application on a peer-to-peer network along with copy protection, disable Software Binding and choose Hardware Binding COMPNO_NETNAME along with one or more other algorithms. The EZ Trial engine will automatically use COMPNO_NETNAME algorithm from all of the workstations and will use the other algorithms on the server. You will need to activate your application twice - once on the server and once on one of the workstations.

It is now recommended to run the application installed on a peer server using the UNC path or mapped drive letter, just as a workstation would, so only the COMPNO_NETNAME algorithm is used and only a single activation is required to enable the entire network.

More Information

You can optionally display the number of days or executions left in the trial using the pp_daysleft() and pp_expired() functions, respectively. To extend the number of days, use code 24. To extend the number of executions, use Trigger Code 25.

The sample application EZTrial1 is included to demonstrate another way to use both EZ Trial and EZ Trigger. There may be cases where EZ Trial does not offer the exact implementation that you are looking for. In this case, you can customize the software licensing features by referring to the other implementation topics in the manual.