To display an activation dialog from an external DLL (before your application starts), check the option "Use embedded DLL to display your Activation Form", after that, select your DLL and the exported function in your DLL which will be called to display the activation form. When you protect your application, the activation DLL is embedded inside your protected application, so you don't need to ship it separately with your protected application. You can find examples to create an "Activation DLL" under the "WinlicenseSDK\Activation\ExampleActivationFromEmbeddedDLL" subfolder.
The function that is called to display the activation dialog has the following prototype:
int __stdcall ActivationHandler( int EventId, int ActivationErrorCode, int WinsockErrorCode, char *ServerResponseString, char *ActivationKey); |
function ActivationHandler( EventId: Integer; ActivationErrorCode: Integer; WinsockErrorCode: Integer; ServerResponseString: PAnsiChar; pActivationKey:PAnsiChar ):Integer; stdcall; |
Parameters
EventId
This parameter specifies the action required by WinLicense to be performed by the activation handler. The possible values are:
•EVENT_SHOW_ACTIVATION: WinLicense is asking to display the activation form, where you ask your customer to insert the Activation key
•EVENT_SHOW_DEACTIVATION: WinLicense is asking to display the deactivation form, where you ask your customer to insert the Activation key. This function is only called if you allow deactivation. This function is called when the customer launches your application with the /deactivate command line parameter.
•EVENT_CHECK_RESPONSE: When WinLicense processes the entered activation key that your customer inserted in your activation form, WinLicense calls again your "ActivationHandler" function passing this parameter, so you can display the specific error code to your customer or let the customer know that the activation was successful. At this time, the parameter "ActivationErrorCode" contains the error code of the processed activation key entered by your customer
ActivationErrorCode
This parameter contains the error code after processing the entered activation key. This parameter should only be processed when the "EventId" parameter is set to EVENT_CHECK_RESPONSE.
The following error codes are available:
RESPONSE_ACTIVATION_OK (0) |
The activation key was processed correctly and a license has been retrieved from the server to register your application |
RESPONSE_DEACTIVATION_OK (0) |
The deactivation process went OK and the current license has been removed from the system and marked as banned. The current PC is marked as revoked in the activation database |
RESPONSE_ERROR_KEY_NOT_FOUND (1) |
The entered activation key is not found in the database |
RESPONSE_ERROR_MAX_SIMULTANEOUS_ACTIVATIONS_REACHED (2) |
The activation key is currently activating the maximum number of simultaneous devices. The maximum number of simultaneous devices is specified by the "Simultaneous Devices" option in "WL Orders Manager" (in the "Manage Activations" panel). If the customer wants to activate a new device, he first needs to deactivate one activated device. |
RESPONSE_ERROR_NO_MORE_ACTIVATIONS_ALLOWED (3) |
The maximum number of activations for the current activation key has been reached. You can control the maximum number of activations from the "Activations Limit" option in "WL Orders Manager" (in the "Manage Activations" panel) |
RESPONSE_ERROR_NO_MORE_DEACTIVATIONS_ALLOWED (4) |
The customer has deactivated more devices than allowed. You can control the maximum number of deactivations from the "Deactivation Limit" option in "WL Orders Manager" (in the "Manage Activations" panel) |
RESPONSE_ERROR_DEVICE_NOT_FOUND (5) |
The device to deactivate is not found in the database. |
RESPONSE_ERROR_WRONG_DATA_RECEIVED (6) |
The activation key is processed correctly but the license data is not retrieved correctly (the license generator application is not generating an expected output) |
RESPONSE_ERROR_KEY_DISABLED_BY_SELLER (7) |
The activation key has been manually marked as "Disabled" in "WL Orders Manager" (in "Manage Activations" panel) |
RESPONSE_ERROR_KEY_EXPIRED (8) |
The expiration date (to allow activation) is already reached. This expiration date was inserted when the activation key was created in "WL Orders Manager". You can manually extend this date if required from the "Manage Activations" panel in "WL Orders Manager" |
RESPONSE_ERROR_NO_MORE_DIFFERENT_DEVICES_ALLOWED (9) |
The activation key has been already activated in more different PCs that were allowed. You can control the maximum number of different devices from the "Max. Different Devices" option in "WL Orders Manager" (in the "Manage Activations" panel) |
RESPONSE_ERROR_CANNOT_INSTALL_LICENSE (50) |
The activation key was processed correctly and the server sent back a correct license key, but it was not possible to write it to the expected location in the customer's PC. This happens if your application does not have rights to write to the expected location for your licenses (you can set the location of your license in the "Registration" panel) |
RESPONSE_ERROR_WINSOCK_ERROR (100) |
This error appears when there are problems to access to the internet or your web server from your application. To know the exact Winsock error code you can read the "WinsockErrorCode" parameter |
WinsockErrorCode
This parameter contains the Winsock error code in case that you get the "RESPONSE_ERROR_WINSOCK_ERROR" value in the "ActivationErrorCode" parameter
ServerResponseString
This parameter contains the buffer returned by your web server when you receive EVENT_CHECK_RESPONSE in the "EventId" parameter. You might want to display this buffer to the customer so he can send you further information about the exact reason of the error in the ActivationErrorCode parameter
ActivationKey
[out] The buffer pointed by the "ActivationKey" parameter will be filled with the activation key (ANSI string) that has been entered by your customer when the "EventId" parameter is set to EVENT_SHOW_ACTIVATION or EVENT_SHOW_DEACTIVATION
Return Values
You can return different values to WinLicense, to decide the action that will be taken when the dialog is closed. The available return values are:
FORM_RESPONSE_TERMINATE_APPLICATION (1) |
WinLicense will terminate your application after returning from your ActivationHandler function. You might want to terminate the application if the user has delivered closed your activation dialog or he has inserted an incorrect activation key multiple times. |
FORM_RESPONSE_RESTART_APPLICATION (2) |
WinLicense will restart your application after returning from your ActivationHandler function. For example, you might want to restart the application when the activation key has been processed correctly, so the application will be fully registered on start. |
FORM_RESPONSE_SHOW_ACTIVATION_FORM_AGAIN (3) |
WinLicense will call again your ActivationHandler function with "EventId" set to EVENT_SHOW_ACTIVATION/DEACTIVATION. You might want to return this value when you receive an error response in the "ActivationErrorCode" parameter, so the user will be asked again to enter the correct activation code. |