Open topic with navigation

PLUSNative: Deactivating and Transferring Licenses

Deactivation can occur one of two ways: you may allow customers to deactivate from your application, or you can remotely deactivate a license or an activation using SOLO Server's administrative interface.

Important

It is very important to rely on background checking and refreshing when allowing users to deactivate your application!  Automated background checking helps prevent users from licensing more systems than intended by restoring the entire system/computer from an image or snapshot taken before deactivation occurred.

In either case, when your application deactivates its license, or runs a background check or refreshes its license and detects that it has been deactivated, it can then disable access to the application or certain features.

Important

Be mindful about whether or not disabling access to your application is appropriate.  For example, if your application requires high availability (such as a web application or service) and/or your application serves some mission-critical function, it may be more appropriate to have your application display nag messages and/or disable only non-critical features so as to avoid disrupting your customers' business or operation.

Deactivating and Transferring Licenses in your Application

Allowing your customers to do deactivate individual activations online is a convenience to them that also reduces your support overhead. Since deactivating allows users to activate a new system, this is a very simple and convenient way for your customers to essentially migrate (or transfer) the license from one system to another. An example of when a customer would want to use this functionality would be when he or she is upgrading from one computer to another.

Generating the Request

The following code snippet demonstrates generating the activation request:

C/C++
//declare variables
SK_ResultCode result = SK_ERROR_NONE;
SK_ApiContext context = NULL;
SK_XmlDoc request = NULL;
SK_XmlDoc response = NULL;
int resultCode = 0;
int statusCode = 0;
SK_XmlDoc license = NULL;

//initialize API context (usually called during application start-up)
//refer to the Configuring the API Context topic for instructions

//generate the activation request
result = SK_SOLO_DeactivateInstallationGetRequest(context, SK_FLAGS_NONE, "UB6AL-MAVGB-A2YWX-2Q4QL-UCKMB-2", &request, NULL);

The above request is generated using fictional, hard-coded Installation ID for demonstration purposes. The code snippet above omits many of the parameters necessary to initialize the API context (the context variable). Refer to the Configuring the API Context topic for instructions and a complete example of calling the SK_ApiContextInitialize function.

Calling the Web Service

The code snippet below simply calls the web service using the request we built above. The request will be encrypted and digitally signed with the call to SK_CallXmlWebService provided the API Context has been configured to use the SK_FLAGS_USE_ENCRYPTION and SK_FLAGS_USE_SIGNATURE flags globally.

C/C++
//call the web service
result = SK_CallXmlWebService(context, SK_FLAGS_NONE, SK_CONST_WEBSERVICE_DEACTIVATEINSTALLATION_URL, request, &response, &resultCode, &statusCode);

//free our request document
SK_XmlDocumentDispose(SK_FLAGS_NONE, &request);

//check the result
if (SK_ERROR_NONE != result)
{
//handle error condition
...
}

The above call uses the SK_CONST_WEBSERVICE_DEACTIVATEINSTALLATION_URL constant that is defined for use with SOLO Server Shared URL. If using SOLO Server Custom URL, Dedicated URL, or Self-Hosted, define and use a new constant in your application's source code which points to your specific domain.

Determining the Result

When SK_CallXmlWebService returns 0 (zero), a valid response with no errors was received.

If you receive a result of SK_ERROR_WEBSERVICE_RETURNED_FAILURE, this indicates we successfully received a response, but SOLO Server encountered errors while processing the request. SOLO Server's web service error condition is returned in the resultCode parameter. References are available online for possible SOLO Server result codes. Optionally, a human-readable error message that can be extracted from the response document's ErrorMessage node.

Important

This basic example omits necessary error checking for the sake of clarity. Many of the functions used could fail for one reason or another, and it's important you make sure the function call succeeds before passing the result from one function to another. Otherwise, you may not be able to tell exactly where the problem occurred.

Revoking or Removing the License

Once you have determined the result of DeactivateInstallation indicates a successful deactivation with SOLO Server, you may then have your application revoke or remove its license. Deleting the license file is appropriate when using read-only license files. However, if you use writable license files, you will need to add logic to update the license file to correctly reflect the new state of the license (i.e. you could make it act like an expired evaluation/trial).

Manually Deactivating a License

There may be cases where a user does not have direct access to the Internet, yet there is a requirement to allow license deactivations. In these cases, a manual deactivation can be performed. To perform a deactivation, it’s nearly identical to doing manual activations, except you’ll use SK_SOLO_DeactivateInstallationGetRequest to generate the request data the user will copy to a system with Internet access, then process the response data as you would for an online deactivations shown above.

Important

Manual deactivations are not recommended as there is no guarantee a user will return the response data to the client. This would allow them to free up an activation in SOLO Server without deactivating the local client license.