Prompt For Recovery

Before reading the rest of this page, you should already understand the basics of license recovery. If not, please read License Recovery in this Feature Guide.

Prompt for Recovery is an option you can set in your license project before you compile it for distribution. When set, in the case that an inconsistent state arises which could possibly be recovered from by using this option, an attempt to do so is made by prompting the user through your programs connected event handler. This is the recommended method of implementing recovery in your license.

If you enable this option, the ClientProtector will fire the OnAttemptRecover event to your application if you have NOT enabled the Auto-Recover option AND one of the following:

During the scope of the StartUp call, none of the Alias Files were found, but the Virgin Registry Data (if any) was found. This indicates that the Alias Files have been purposefully deleted, but the software had indeed been run on the machine before. This is an inconsistent state.
During the scope of the StartUp call, all of the Alias Files were found, but at least one of them either did not corroborate (was out of sync) or had been internally altered (tampered with). This is an inconsistent state.

To best understand when and where the ClientProtector will fire the OnAttemptRecover event during the scope of the StartUp call, please have a copy of the SoftwareShield ClientProtector Control Flow Charts on hand as you read the rest of this section.

If one of the above inconsistent states arises and you have set the option to Prompt to Recover, the following occurs:

The Authorization Definition in your license for License Recovery is found.
The Authorization Request Code for this definition is generated.
The OnAttemptRecover event is fired, sending the Authorization Request Code. It also sends an empty Activation Code reference parameter which your program can fill with an Activation Code (input from the user).
If the user input an Activation Code, it is parsed like any other Activation Code and if successful, the license is recovered to the state of the Main License File. (See License Recovery for the specific actions that occur during recovery).
If no Activation Code is input, or if the code is not verified, the StartUp call returns an return_code indicating the outcome.

Note that using the Prompt for Recovery option allows your application to prompt the user to recover their license using an Authorization Request Code / Activation Code exchange during the StartUp call. You do not have to enable this option in order to prompt the user to recover their license in this way. If you choose not to, you would have to do it outside the scope of the StartUp call - after interpreting its return_code and determining on your own that the license needs to be recovered. (See Recover by Activation Code for more details).

Using the Prompt to Recover option requires the user to communicate an Authorization Request Code to you and input the reciprocated Activation Code from you in order to recover their license. While this may be a slight inconvenience for you and the user, it is much more secure against crackers since they will only be able to make one attack in this manner on your licensed software before they need to contact you to recover it. Repeated requests for a recovery code obviously indicate someone purposefully tampering with the licensing system and you can take corrective action. It is important to consider the tradeoffs here and make a careful decision about its use.

More Information

For help on actually setting the Prompt to Recover option in your license, see License Behaviour Tab in the SoftwareShield License Manager Reference.

For help on understanding the flow of control during the call to StartUp and how the logic behind Prompt to Recover works, see SoftwareShield ClientProtector Control Flow-Charts in the ClientProtector Reference.

For help in connecting to the ClientProtector OnAttemptRecover event, see Creating a ClientProtector COM Event Sink in the SoftwareShield ClientProtector Reference.

For help on actually using the OnAttemptRecover event, see OnAttemptRecover in the SoftwareShield ClientProtector Reference.