The SNCheckInCopyProtection function attempts to perform an automated Check-In operation on Copy-Protection.

Syntax

HRESULT SNCheckInCopyProtection( long * return_code ) ;

Parameters

return_code

[OUT] This is (a pointer to) a numeric value that returns with the outcome of the operation. See RETURNCODES for a complete list of possible values.

Remarks

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

The SNCheckInCopyProtection function attempts to perform an automated Check-In operation on Copy-Protection.

If the license has not been correctly initialized with a call to StartUp, the return_code will return with FALSE_LICENSE_NOT_INITIALIZED.

If the license does not contain a Release Copy-Protection Authorization Definition, the return_code parameter will return with FALSE_CODE_OUT_OF_RANGE.

If the found Release Copy-Protection Authorization Definition does not contain any Serial Number, the return_code will return with FALSE_NO_SN.

If the CheckPoint URL is inside the license is empty, the return_code parameter will return with FALSE_NO_CHECKPOINT_URL.

If the CheckPoint server can not be contacted (using the CheckPoint URL and any proxy server information stored inside the license) the return_code will return with FALSE_CONNECTION_FAILURE.

If a Deactivate Authorization Definition ID is not found in the license, the return_code will return holding FALSE_NO_DEACTIVATE_ID. If the pre-condition of the deactivation is not met (probably the release of Copy-Protection), the return_code will return with FALSE_PRECONDITION_NOT_MET.

Note that while a Deactivation Confirmation Code is used in this process, the license is not deactivated as a whole (UNLIKE when you call ForceDeactivate) .  Instead, the Copy-Protection release itself will be removed.  If you do wish to also permanently deactivate the license you must call ForceDeactivate separately).

The OnAttemptCheckInCopyProtection event will fire, giving your application a chance to interact with the user and give them a last chance to abort the Check-In operation.  If the user sets the AllowCheckIn parameter in that event handler to false, the return_code will return holding FALSE_REFUSE_TO_DEACTIVATE.

Otherwise, the Copy-Protection will be "un-released" for this machine.  This essentially means that the systems FingerPrint is removed from the list of authorized machines inside the encrypted license. The CheckPoint server will then be invoked to remotely Check-In the associated Serial Number stored inside the Release Copy-Protection Authorization Definition.

If Serial Number is invalid (on the server) the return_code will return with FALSE_INVALID_SN.

If there have never been any activations consumed before on this Serial Number in the CheckPoint database, the return_code will return with FALSE_NO_ACTIVATIONS.

If the Deactivation Confirmation Code does not validate on the server the return_code will return holding FALSE_CODE_INVALID_BAD_ID.

Otherwise, the consumed count is reduced by one in the CheckPoint database and the operation succeeds.

Back on the client machine, if the server operation fails, Copy-Protection will be "re-released" for this machine - putting the license state it back to where it was. This essentially means that the systems FingerPrint is re-added to the list of authorized machines inside the encrypted license.

If this return from the CheckPoint operation is success, the associated Authorization Definitions state is set to Activated = false, stored parameter = 0, stored Serial Number = "".  In this case, the return_code parameter returns with FALSE_CODE_NOT_ACTIVATED - which means that the Check-In was successful, and the associated Authorization Definition is no longer activated.

The flow of control of this function is illustrated in the  GameShield ClientProtector Control Flow Charts. Please review them to get a precise picture of what this function does.

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"