OnPrepareAutoActivate

OnPrepareAutoActivate is an event function of the ClientProtector dispatch interface. This event will fire during the scope of the StartUp call if you are using Copy-Protection to allow you to prepare the user for an activation (automated or not).

Syntax

HRESULT OnPrepareAutoActivate (

BSTR AuthRequestCode,

VARIANT_BOOL CheckPointConnectionDetected,

BSTR * SerialNumber,

long * RequestedActivateMethod,

VARIANT_BOOL * UseProxy,

VARIANT_BOOL * UseProxyAuth,

BSTR * ProxyServerName,

long * ProxyServerPort,

BSTR * ProxyServerUserName,

BSTR * ProxyServerPassword

) ;

Parameters

AuthRequestCode

[IN] This is a string that contains the Release Copy Protection Authorization Request Code. (See remarks below.)

CheckPointConnectionDetected

[IN] This is a boolean value that informs your application if the CheckPoint Server that is specified in your CheckPoint Server URL (stored inside the license) can be contacted through HTTP from the users machine.

SerialNumber

[OUT] This is (a pointer to) a string that you should return the Serial Number that the user entered. (See remarks below.)

RequestedActivateMethod

[OUT] This is (a pointer to) a numeric value that you must return the user chosen activation method. (See remarks below.)

UseProxy

[OUT] This is (a pointer to) a boolean value that you may return to the ClientProtector that tells it to use a proxy server in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). If you return false in this parameter, the remaining parameters are ignored. (See remarks below.)

UseProxyAuth

[OUT] This is (a pointer to) a boolean value that you may return to the ClientProtector that tells it to use a basic proxy server authentication in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). If you return false in this parameter, the ProxyServerUserName and ProxyServerPassword are ignored. (See remarks below.)

ProxyServerName

[OUT] This is (a pointer to) a string value that you may return to the ClientProtector that tells it the proxy server name the user wants to use in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). (See remarks below.)

ProxyServerUserName

[OUT] This is (a pointer to) a numeric value that you may return to the ClientProtector that tells it the proxy server port the user wants to use in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). (See remarks below.)

ProxyServerPort

[OUT] This is (a pointer to) a string value that you may return to the ClientProtector that tells it the authentication user name on the proxy server the user wants to use in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). (See remarks below.)

ProxyServerPassword

[OUT] This is (a pointer to) a string value that you may return to the ClientProtector that tells it the authentication password on the proxy server the user wants to use in communicating with the CheckPoint server (if specified in the returned RequestedActivateMethod parameter). (See remarks below.)

Remarks

OnPrepareAutoActivate is an event function of the ClientProtector dispatch interface. This event will fire during the scope of the StartUp call if you are using Copy-Protection to allow you to prepare the user for an activation (automated or not).

You can connect to this event if you wish to synchronously (inside the scope of the StartUp call) interact with the user to perform a Serial Number Code Exchange.

Dealing with the Internet Connection for Fully-Automated Activation:

When your program responds to this event, it should first determine if the CheckPoint Server can be contacted. Check the CheckPointConnectionDetected parameter. If it is true, no further input for networking information is required from the user to successfully perform a fully automated Serial Number Code Exchange.

However, if it is false, the server could not be contacted. There are a variety of reasons for this. If the user wishes to perform an automated Serial Number Code exchange, the connection problem must be resolved.

Naturally, when you design your license, you must make sure that you have set a valid URL in your licenses CheckPoint Server URL field and that the server can indeed be contacted through this URL.

On the clients machine, you should prompt your user to double-check various settings (e.g.: "We could not detect an internet connection. Are you connected to the internet? Is your network cable unplugged? Are you behind a proxy server?")

If the user is behind a proxy server (or the believes he fixed a connection problem) you can provide the user the ability to perform connection tests:

Synchronously Testing the Internet Connection (with or without a proxy server):

From inside the scope of this event handler you can repeatedly test the connection for the user if he wishes. If you choose to do this, you must:

Create a new instance of a ClientProtector object. You must do this because the ClientProtector COM server is non-reentrant and in this case you will be calling a function to test the connection from inside this synchronous event handler that it is blocking on.
Do not call StartUp on the new instance. You will be using just for testing the connection.
If necessary, gather test proxy server settings.
When the user wishes to test the connection, call QuickTestCheckPointConnection. You can call this function as many times as necessary until successful. The user may supply proxy server information for use in these tests.
When complete - destroy the new instance of the ClientProtector you were using for the tests.
Use any new proxy server information you gathered from a successful test as the last six return parameters from this event. (They may not be necessary if the connection problem was corrected by some other means.)

If the user chooses to do a phone-in activation and you provide this functionality synchronously from inside the scope of this event - you will need the user to communicate the Authorization Request Code to your staff.

About SSL (HTTPS) and Proxy Servers

Keep in mind that proxy servers generally can not act as a proxy for HTTPS (SSL) communication. HTTPS requires a secure handshake from point-to-point to enable its secure communications. A proxy server can not be in between the two participants (client and server) of an SSL communication. Most enterprises that use proxy servers allow direct outbound SSL communication for the workstations (default port 443) to allow SSL communication to work. If you are deploying your CheckPoint Server to be accessible via HTTPS only, be sure to take this into account when managing proxy server information.

Requested Activation Method

You can give the user the choice of either automated Activation or not (which implies manual Activation). Simply return the appropriate value in the RequestedActivateMethod parameter. See: REQUESTEDACTIVATEMETHOD for the values permitted.

Note that if you wish to perform an automated Activation you must set RequestedActivateMethod parameter to RAM_AUTO. By default it is set to RAM_MANUAL.

If you choose not to subscribe to this event or fail to change the RequestedActivateMethod parameter to RAM_AUTO, the StartUp call will proceed and not attempt an automated Serial Number Code Exchange.

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"