The StartUp function must be called before you use the ClientProtector to enforce your license.  It ensures that the license is properly loaded  and initializes itself.  With the exception of SetPrependFingerPrintString, and QuickTestCheckPointConnection, this function should be the first function called after creating an instance of the ClientProtector component and prior to calling any other function of the ClientProtector.

Syntax

HRESULT StartUp ( BSTR MainLFName, BSTR MainLFPassword, BSTR GlobalAuthPassword, long FPCode, long DebugFlags, long * return_code );

Parameters

MainLFName

[IN] This is the name of the distributed license file you deploy with your software. Path information is not required if the main license file is in the host application directory. You do however, have the option of supplying path information if you choose to deploy your Main License File to a different location than the host application directory. See the remarks section below for details.

 

MainLFPassword

[IN] This is the password you used to encrypt your main license file.

 

GlobalAuthPassword

[IN] This is the Global Authorization Definition Password you use to encrypt the "outer" layer of all Authorization Codes.

 

FPCode

[IN] This is the numeric code that identifies what combination of System FingerPrint Options you have enabled in this license.

 

DebugFlags

[IN] This a numeric bit-field comprised of any number of CPDEBUGFLAGS values combined with a bit-wise OR.  (See remarks section below for details.)

 

return_code

[OUT] This is (a pointer to) a numeric value that returns with a RETURNCODE that identifies the outcome of the operation. (See remarks section below for details.)

Remarks

Note: This function is illustrated in the GameShield Flowcharts - (see flow chart #1).

Note that the Programming Notes File that is created when you compile a license contains an easy to use prototype of your specific function call to reduce the possibility of making an error in transcribing the license name, passwords, and FingerPrint code.

The StartUp function tries to load the license specified in MainLFName and goes through a series of checks to initialize the state of the license.  A substantial amount of processing may take place depending on the design and state of your license.  

During this call, the ClientProtector may fire five different events to your application.  Those events are: OnMissingLicenseFile, OnAttemptReleaseCP, OnAttemptRecover, OnPrepareAutoActivate and OnAutoActivateResult.  NOTE: StartUp is not reentrant. This means that you must not call StartUp from inside the scope of one of these event handlers or you will cause infinite recursion and a stack overflow.

When the call to StartUp returns, the value of the return_code parameter will contain the outcome of its processing. Again, the best way to understand which return_code values may return from this call is to refer to the GameShield Flowcharts.

Path Information

The MainLFName parameter is the name of the distributed license file you deploy with your software. Path information is not required if the main license file is in the host application directory. You do however, have the option of supplying path information if you choose to deploy your Main License File to a different location than the host application directory. You can do this two ways:

1. You can supply a relative path from the host application directory in standard format.

2. You can supply an absolute path.

Relative paths are always taken relative from the host application directory.

Absolute paths are identified as absolute by the colon ":" appearing anywhere in the string. The colon operator identifies and separates a drive letter from a path specification. Absolute paths provide you a way of deploying your licenses to arbitrary locations on the machine and this path can be constructed at runtime based on any logic you see fit, to provide added flexibility.

The MainLFName parameter is assumed to be relative unless it is identified as absolute by a colon appearing anywhere in the string.

Note: the Main License File must be deployed on the client machine.  It is not supported to deploy the Main License File (or the application itself) to any other machine through either a UNC path or a mapped drive.  The path you specify here must ultimately reside on the client machine.

Examples:

"MyLicenseFile.ini"

This example parameter (above) identifies the main license file (named "MyLicenseFile.ini") as relative to the host application directory and is located in the exact same directory as the host application.

"..\\..\\Licenses\\MyLicenseFile.ini"

This example parameter (above) identifies the main license file (named "MyLicenseFile.ini") as relative to the host application directory and is located two directories up, in a sub-directory named Licenses.

"D:\\Myfolder\\MyLicenseFile.ini"

This example parameter (above) identifies the main license file (named "MyLicenseFile.ini") as an absolute path located exactly as specified.

This file name alone (including extension) is entered into the license on the Main License File Tab of the GameShield License File Manager Application. Any path information must be added by your calling application.

Note: we recommend for simplicity to deploy your license if possible in the same directory as the host application.

Return Value

As with all COM function calls they return an HRESULT. HRESULT is a data type that is a 32-bit error or warning code. Check your compilers documentation for information on interpreting the HRESULT value.

Function Information

Exposed By Interface:	"ISSCProtector"
Exposed In COM Server Binaries:	"SSCProt.dll" and "SSCProtD.dll"