The RETURNCODES enumeration is used in several ClientProtector function calls. The values indicate the outcome of an operation.

Positive outcomes (true values) are greater than or equal to 100 and less than 500. Negative outcomes (false values) are greater than or equal to 500.

enum RETURNCODES { TRUE_NON_EXPIRY = 100, TRUE_EXPIRY = 101, TRUE_CODE_ACTIVATED = 102, TRUE_CODE_VALID = 103, TRUE_CHECKED_IN = 104, TRUE_CODE_GENERATED = 105, TRUE_LICENSE_DEACTIVATED = 106, TRUE_CONNECTED = 107, FALSE_INSTALL_DATE_INVALID = 500, FALSE_NOT_VIRGIN_INSTALL = 501, FALSE_LFS_NOT_CORROBORRATE = 502, FALSE_LICENSE_EXPIRED = 503, FALSE_MISSING_MAIN_LF = 504, FALSE_MAIN_LF_CORRUPT = 505, FALSE_CODE_NOT_ACTIVATED = 506, FALSE_WAITING_FOR_CODE = 507, FALSE_CLOCK_TURNED_BACK = 508, FALSE_LICENSE_DEACTIVATED = 509, FALSE_REFUSE_TO_DEACTIVATE = 510, FALSE_NO_DEACTIVATE_ID = 511, FALSE_DEACTIVATION_ID_ONLY = 512, FALSE_SYSTEM_NOT_AUTHORIZED = 513, FALSE_LICENSE_NEEDS_RECOVERY = 514, FALSE_CODE_OUT_OF_RANGE = 515, FALSE_PRECONDITION_NOT_MET = 516, FALSE_NOT_AUTH_NOT_EXPIRED = 517, FALSE_NOT_AUTH_CLOCK_TURNED_BACK = 518, FALSE_NOT_AUTH_EXPIRED = 519, FALSE_MLF_ACCESS_DENIED = 520, FALSE_MLF_READONLY = 521, FALSE_AF_VK_ACCESS_DENIED = 522, FALSE_AF_READONLY = 523, FALSE_CODE_INVALID_BAD_ID = 550, FALSE_CODE_INVALID_BAD_FP = 551, FALSE_CODE_INVALID_EXPIRED_SL = 552, FALSE_CODE_INVALID_SINGLE_USE = 553, FALSE_CODE_INVALID_FORMAT = 554, FALSE_CODE_INVALID_PASSWORD = 555, FALSE_LICENSE_NOT_INITIALIZED = 600, FALSE_NOT_VALID_HOST_APP = 601, FALSE_INTERNAL_LICENSE_CHECK_FAILED = 602, FALSE_NO_SN = 620, FALSE_INVALID_SN = 621, FALSE_NO_CHECKPOINT_URL = 622, FALSE_CONNECTION_FAILURE = 623, FALSE_NO_ACTIVATIONS = 624, FALSE_INTERNAL_FAILURE = 901 };

 

The meaning of a particular RETURNCODE depends on the context from which it was returned.  The best source of information for determining which values will be possibly returned from which function calls, and then interpreting their meaning is the SoftwareShield ClientProtector Control Flow Charts.  

The following descriptions of meaning is meant as a guide:

RETURNCODE Meaning:

TRUE_NON_EXPIRY: This return code indicates that no copy protection was found, or it was already released, no expiration was found, all alias files corroborate and are consistent.

TRUE_EXPIRY: This return code indicates that while the license is an expiring type of license (any of the three types) it has not yet expired. No copy protection was found, or it was already released, all alias files corroborate and are consistent.

TRUE_CODE_ACTIVATED: This return code indicates that a specific Activation Code has been successfully activated. This value is only (possibly) returned from functions which deal directly with Activation Codes. It also indicates that no copy protection was found, or it was already released, all alias files corroborate and are consistent.

TRUE_CODE_VALID: This return code indicates that a specific Activation Code was successfully validated but that the code was not "activated" and the license was not updated with any changes.  Note that this return code is only returned from the function ValidateActivationCode.

TRUE_CHECKED_IN: This return code indicates that an operation to Check-In a Serial Number was successful.  Note that this return code is only returned from SNCheckInCopyProtection, SNCheckInBySN or SNCheckInByID.

TRUE_CODE_GENERATED: This return code indicates that the CheckPoint License Server successfully parsed and validated the Serial Number in a Serial Number Code Exchange and returned an Activation Code. This return code is possibly returned from OnAutoActivateResult.

TRUE_LICENSE_DEACTIVATED: Reserved.

TRUE_CONNECTED: This return code indicates that the CheckPoint Server was successfully contacted in the scope of QuickTestCheckPointConnection.

FALSE_INSTALL_DATE_INVALID:  This return code indicates that the StartUp function could not complete because the Last Used Date Time inside the license, once converted from UTC (the raw storage format) to local time,  is  later than (after) the current system date and time.  This is usually only returned the very first time the license is initialized with a call to StartUp. This could indicate a user trying to defeat some aspect of your license by manipulating their clock.  You may wish to prompt the user to correct the clock and try again.

FALSE_NOT_VIRGIN_INSTALL: This return code indicates that key Alias Files were missing, but others were found or the Virgin Registry Data was found - indicating that the user has either inadvertently or maliciously tampered with the license files.  This return code only returns if the condition cited above occurs and you have no recovery mechanism in the license.

FALSE_LFS_NOT_CORROBORRATE: This return code indicates that at least one Alias File was tampered with or is otherwise out of synch with the Main License File - indicating that the user has either inadvertently or maliciously tampered with at least one of the Alias Files.  This return code only returns if the condition cited above occurs and you have no recovery mechanism in the license.

FALSE_LICENSE_EXPIRED: This return code indicates that the license is an expiring type of license (any of the three types) it has expired. No copy protection was found, or it was already released, all alias files corroborate and are consistent.

FALSE_MISSING_MAIN_LF: This return code indicates that the main license file was not found in the directory you specified in the parameter in the call to StartUp. Further - if your OnMissingLicenseFile event was connected, either the user failed to find it, they selected an incorrect file, the file was unable to be moved, read or written or your event handler simply failed to assign the actual file name path parameter correctly. Be sure the Main License File name you pass to the StartUp function is correct and that the file is located correctly as described in the documentation for StartUp.

FALSE_MAIN_LF_CORRUPT: This return code indicates that the Main License File was found in the correct location, however the ClientProtector was either unable to open it, read it, the contents had been tampered with or you simply provided the wrong Main License File Password parameter in the call to StartUp (which would result in the decryption process failing).  In almost every case, when this occurs it is impossible to recover the license (almost certainly caused by tampering).  The user may need a new license file from you.  

FALSE_CODE_NOT_ACTIVATED: This return code is returned from GetAuthorizationDetails and indicates that a the specific Authorization Definition you have inquired about is not activated.

FALSE_WAITING_FOR_CODE: This return code indicates that the RequestActivation function concluded.  This is the normal return code for this function.  This indicates that the ClientProtector took no specific action because it is waiting for a subsequent call to input an Activation Code.

FALSE_CLOCK_TURNED_BACK: This return code indicates the clock has been turned back.  You may wish to inform the user to correct the clock and try again.

FALSE_LICENSE_DEACTIVATED: This return code indicates the license has been deactivated.  The only way to reactivate the license is using a Reactivate License Authorization Definitions.

FALSE_REFUSE_TO_DEACTIVATE: This return code indicates that a call to RequestDeactivation was unable to complete the deactivation process because your event handler set the Allow Deactivate parameter to false when it was called.

FALSE_NO_DEACTIVATE_ID: This return code indicates that a call to RequestDeactivation was unable to complete the deactivation process because the license does not contain a valid Deactivation Authorization Definition.

FALSE_DEACTIVATION_ID_ONLY: This return code indicates that a call to RequestActivation or SetAuthorizationDetails failed because the request corresponded to a Deactivation Authorization Definition. Deactivation Authorization Definitions can only be manipulated by a call to RequestDeactivation.

FALSE_SYSTEM_NOT_AUTHORIZED: This return code indicates that the Copy-Protection mechanism failed to find the host machine FingerPrint in the list of authorized machines in the license.  Further, if the OnAttemptReleaseCP event fired, and was correctly connected to your event handler, the event handler failed to return any Activation Code whatsoever.  Further, this return code indicates that there is no expiration in effect.

FALSE_LICENSE_NEEDS_RECOVERY: This return code indicates that the call to StartUp found a condition which needs to be recovered from.  Further, you had set Prompt To Recover in the license, but your event handler for OnAttemptRecover failed to return any Activation Code whatsoever.

FALSE_CODE_OUT_OF_RANGE: This return code indicates that a call to SetAuthorizationDetails specified an Authorization Definition ID which was out of valid range (0 to 63 inclusive).

FALSE_PRECONDITION_NOT_MET: This return code indicates that a call to RequestDeactivation failed because the Pre-Condition associated with the Deactivation Authorization Definition was not met.

FALSE_NOT_AUTH_NOT_EXPIRED: This return code indicates that a call to StartUp found that the Copy-Protection mechanism failed to find the host machines FingerPrint in the list of authorized machines in the license.  Further, if the OnAttemptReleaseCP event fired, and was correctly connected to your event handler, the event handler failed to return any Activation Code whatsoever.  Further, this return code indicates that there is an expiration in effect - but it has not yet elapsed.

FALSE_NOT_AUTH_CLOCK_TURNED_BACK: This return code indicates that a call to StartUp found that the Copy-Protection mechanism failed to find the host machines FingerPrint in the list of authorized machines in the license.  Further, if the OnAttemptReleaseCP event fired, and was correctly connected to your event handler, the event handler failed to return any Activation Code whatsoever.  Further, this return code indicates that there is an expiration in effect - and the system clock has been turned back.  You may wish to prompt the user to correct it and try again.

FALSE_NOT_AUTH_EXPIRED: This return code indicates that a call to StartUp found that the Copy-Protection mechanism failed to find the host machines FingerPrint in the list of authorized machines in the license.  Further, if the OnAttemptReleaseCP event fired, and was correctly connected to your event handler, the event handler failed to return any Activation Code whatsoever.  Further, this return code indicates that there is an expiration in effect - and it has elapsed.

FALSE_MLF_ACCESS_DENIED: This return code indicates that processing can not continue because the user does not have sufficient permissions to access the Main License File.  The user must be able to read, write, append, delete and re-create the file in the specified location.  See: Windows Permissions And Security Considerations for more information.

FALSE_MLF_READONLY:  This return code indicates that processing can not continue because the Main License File is marked as read-only.  See: Windows Permissions And Security Considerations for more information.

FALSE_AF_VK_ACCESS_DENIED : This return code indicates that processing can not continue because the user does not have sufficient permissions to access some or all of the required Alias Files.  The user must be able to read, write, append, delete and re-create the file and or registry keys and sub-keys in the locations you designed in your license.  See: Windows Permissions And Security Considerations for more information.

FALSE_AF_READONLY: This return code indicates that processing can not continue because one or more of the Hidden or Steganographic Alias Files is marked as read-only.  See: Windows Permissions And Security Considerations for more information.

FALSE_CODE_INVALID_BAD_ID: This return code indicates that a function call which either verifies Activation Codes or manipulates Authorization Definitions directly, failed because either the embedded Authorization Definition ID (in the case of an Activation Code) or the specified Authorization Definition ID (in the case of other function calls) specified a value which was not valid for the license.

FALSE_CODE_INVALID_BAD_FP: This return code indicates that a function call which either directly or indirectly verifies Activation Codes failed because the embedded FingerPrint in the Activation Code did not match the host machines FingerPrint. In other words, the Activation Code was not meant for the host machine.

FALSE_CODE_INVALID_EXPIRED_SL: This return code indicates that a function call which either directly or indirectly verifies Activation Codes failed because the embedded Shelf-Life expiration date in the Activation Code has elapsed.

FALSE_CODE_INVALID_SINGLE_USE: This return code indicates that a function call which either directly or indirectly verifies Activation Codes failed because that exact Activation Code had been used before on that particular license and the Authorization Definition to which it corresponds is marked as "Generate Single-Use Activation Codes".

FALSE_CODE_INVALID_FORMAT: This return code indicates that a function call which either directly or indirectly verifies Activation Codes failed because the general format of the input Activation Code was incorrect. (Size wrong, dashes missing or in the correct place, invalid characters etc.)

FALSE_CODE_INVALID_PASSWORD: This return code indicates that a call to SetAuthorizationDetails failed because the supplied password did not match the Local Authorization Definition Password for the corresponding definition.

FALSE_LICENSE_NOT_INITIALIZED: This return code indicates that you have called a function on the ClientProtector before you have called StartUp.  Calling any function on the ClientProtector before you have initialized its license (using StartUp) is an error. You must call StartUp exactly once before you call any other function of the ClientProtector.

FALSE_NOT_VALID_HOST_APP: This return code indicates that you are attempting to use the ClientProtector to protect an application for which you are not licensed.  The Professional Edition of the SoftwareShield DRM Kit grants you the right to protect one named host application.  If you need to check the name of the host application you are licensed to protect, open the License Manager and click "Help > About...".  If you would like to upgrade to an edition which does not limit the number of named host applications you can protect, click "Registration > Purchase or Upgrade the SoftwareShield System Now..."

FALSE_INTERNAL_LICENSE_CHECK_FAILED: This return code indicates that the CheckPoint License Server (or other component) has detected that you are not permitted to use the features you are attempting to invoke.  Most frequently this occurs as a result of a call to the CheckPoint License Server by any of its available interfaces. If you believe this is an error, please contact SoftwareShield. If you would like to upgrade to an DRM Kit edition which does not impose these limits please contact SoftwareShield.

FALSE_NO_SN: This return code indicates that some operation was invoked that requires either a Serial Number value parameter or a stored Serial Number inside the currently loaded license, however no Serial Number was found.

FALSE_INVALID_SN: This return code indicates that some operation was invoked that requires either a Serial Number value parameter or a stored Serial Number inside the currently loaded license, however the Serial Number that was found was either an invalid format or its internal checksum did not validate.

FALSE_NO_CHECKPOINT_URL: This return code indicates that some operation that required or directed communication with the CheckPoint License Server could not continue because no CheckPoint server URL was provided or found stored in the currently loaded license.

FALSE_CONNECTION_FAILURE: This return code indicates that some operation that required or directed communication with the CheckPoint License Server could not continue because the CheckPoint Server could not be contacted.

FALSE_NO_ACTIVATIONS: This return code indicates that the CheckPoint License Server was invoked to perform a Serial Number Code exchange, however, the Serial Number that was passed had no remaining un-consumed Activations.

FALSE_INTERNAL_FAILURE: This return code indicates that a failure occurred inside the ClientProtector component. You should never receive this return code. If you do, this indicates a bug in the ClientProtector component. If you receive this return code, please report the bug and exactly how to replicate it to SoftwareShield.