PLUSNative: Activating and Getting a License File (Online Method)

Online activation is one option for activating an application and retrieving a license file from SOLO Server. Obtaining a license file from SOLO Server is required when working with read-only license files, since only SOLO Server has the encryption key data necessary to encrypt and digitally sign a read-only license file. Although it is possible to create a self-signed writable license file without using SOLO Server, it is often more convenient to obtain the base license file from SOLO Server that can then be modified as necessary. Either way, the procedure is largely the same. The only difference being how you configure the API context.

Important

Activation is only intended to occur once per system and/or user. DO NOT configure your application to activate automatically every time it is run, as this can cause many problems that affect the reliability of your application, and is considered a misuse of the SOLO Server activation web services. If you wish to validate the status of the license with SOLO Server in your application, use background checking. If you wish to offer a limited number of users an option to check-in/check-out seats for a license, consider using Network Floating Licensing features for this purpose.

The following example demonstrates activating an installation, retrieving a license file from SOLO Server, and then saving that license file to disk.

Generating the Request

The PLUSNative library has built-in functions for generating requests for the SOLO Server XML Activation Service and XML License File Service web services. Use of these functions avoids having to manually build the web service XML request document. If one finds it necessary, the XML request document can be modified using any of the XML helper functions. For instance, new elements can be added using the SK_XmlElementAddNew function.

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_ActivateInstallationGetRequest(context, SK_FLAGS_NONE, 123, "password", NULL, 1000, 1000, FALSE, "My Installation", NULL, &request, NULL);

The above request is generated using fictional hard-coded data 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_ACTIVATEINSTALLATION_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_ACTIVATEINSTALLATION_URL constant that's defined for use with Instant SOLO Server. If using a dedicated or externally-hosted SOLO Server, this will need updating to point 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 possibleSOLO Server result codes. Optionally, a human-readable error message that can be extracted from the response document's ErrorMessage node.

Parsing the Response

Once you determine the web service call succeeded, you must manually parse the response to determine what actions to take. Here, the XML helper functions are used here to extract the data out of the response document. A read-only license file is contained as a sub-document in the response's 'License' node. Once you extract the license document from the response you can save it to disk.

C/C++
//get the license sub-document
result = SK_XmlNodeGetDocument(SK_FLAGS_NONE, response, "/ActivateInstallationLicenseFile/PrivateData/License", &license);

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

if (NULL != license)
{
//save the license file to disk
result = SK_PLUS_LicenseFileSave(context, SK_FLAGS_NONE, filename, license);

//free our license document
SK_XmlDocumentDispose(SK_FLAGS_NONE, &license);
}

Although the above example saves the license file to disk, it can actually be saved anywhere, such as in a database. In such a scenario, you would only need the license string to save. If you don't save the license file using SK_PLUS_LicenseFileSave, it is necessary to call SK_PLUS_LicenseLoad to load the newly obtained license into memory.

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.