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.
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.
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:
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.
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.
The above call uses the SK_CONST_WEBSERVICE_ACTIVATEINSTALLATION_URL constant that's defined for use with SOLO Server Shared URL. If using SOLO Server Custom URL, Dedicated URL, or Self-Hosted, this will need updating to point to your specific domain.
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.
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.
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.
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.
PLUSNative allows activating an application using the Product ID and a serial number pre-loaded into SOLO Server. This method can be used instead of activating with a License ID and Activation Password, and it allows the use of your own activation serial numbers. This can be useful if your customers are already familiar with a certain license key format or if you need to import a list of serials from another system.
The SOLO Server manual topic Importing and Exporting Product Serial Numbers explains how to load a list of serial numbers in SOLO Server. Each time a new license is created for that Product, the next unused serial number in the list will be associated with the license. To issue a serial number to an existing license after uploading the serials, you can simply view the license in SOLO Server and choose the Issue Serial Number option in the Licenses menu.
You must use the mechanism described above to import serial numbers into SOLO Server. Attempting to manually enter a serial number into the serial number field by editing a License in SOLO Server will result in the activation failing with a Response Code of 100.
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.
Once the request data is generated, you may call the web service and parse the response the same as activating with a License ID and Activation Password. See the Calling the Web Service section above.
To generate the request data using the Product ID and Serial Number, be sure the Product ID was specified when creating the API context. Refer to the Configuring the API Context topic for instructions. Then, when calling the SK_SOLO_ActivateInstallationGetRequest API function, set the serial number value, set the License ID parameter to 0, and set the password parameter to NULL.
The following code snippet demonstrates generating the activation request using a serial number: