Application Licensing
From DocR23
| ||
In order to activate protected Spatial software products, you must obtain an Application Key from the Spatial Website, specifically, one key for each of your applications. For every application key you request, Spatial requires that you submit criteria for the key, including:
- Spatial products you plan to use
- Release version of the Spatial products you plan to use
- Your company name
- Your application name
- Application key type
Note: You must obtain a new application key when any of the above criteria changes.
Important: This functionality is supported on Windows operating systems only.
Typically, you will obtain one application key for each of your applications. However, you may wish to obtain different keys for different sets of Spatial products, for example, if you ship a base product and an optional add-on product. All Spatial products support this type of configuration by allowing multiple application keys to be used in a single application.
Typical Scenarios for Obtaining a New Application Key
New Application Key for Next Major Release
Spatial releases the next major version of its software. You want to upgrade your Spatial products to the next version. Your existing application key is bound to the earlier version; therefore, you must obtain a new application key. (Service Pack releases continue to use the same application key; therefore, obtaining a new application key is not required.)
New Application Key after Evaluating Spatial Products
Under an evaluation license agreement you obtained an Evaluation application key in the past to evaluate Spatial products in your application. You have now decided to integrate Spatial products as a permanent choice for your application and to distribute your application to your end users. You contact your Spatial sales representative to have your license agreement changed to production. Hence, you must obtain a Production application key.
New Application Key when Changing Number of Products in Use
You obtained an application key for three Spatial products. You now wish to discontinue using one of those products, and in its place, begin using another Spatial product. You must obtain an application key that will be bound to the new product as well as the other two Spatial products you still plan to use.
Sample Application Key
The application key is comprised of a key string and a license-specific function provided in a C++ file from the Spatial Web Site. Together, the key string and function unlock Spatial products. When you obtain your application license key, the Spatial Licensing Web Site also returns specific data required by the Spatial registration function. From the same Web page, you are requested to download the C++ file which, contains the application key string and the license-specific function.
The contents of the C++ file are similar to the following:
#include "license.hxx" #include "spa_unlock_result.hxx" // Customer ID: ABC111 // Customer Name: ABC Company, Inc. // Application Name: ABC Application // Licensed Spatial Products: // 3D ACIS Modeler // 3D ACIS Deformable Modeling // 3D InterOp ACIS CATIA V4 Reader/Writer // Spatial Product Version: R17 // License Type: Permanent // Expiration Date: N/A // Application Registration: Required // License Key Index: 11 // License Key: // 11111111000000001111111100000000111111110000000011111111 // 11111111000000001111111100000000111111110000 // Generation Date: 2006/06/27 // GLOBAL_PROC void unlock_spatial_products_11() { const char* unlock_str = "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000"; spa_unlock_result out = spa_unlock_products( unlock_str ); if ( out.get_state() != SPA_UNLOCK_PASS ) { /* insert your error handling code here */; } }
If you use Spatial Registration, you must note the specific data required by the Spatial registration function before closing the Spatial Licensing Web page. These details are located near the end of the page. They include:
- Software Publisher
- Application
- Application Key Index
- Spatial Software Version
Use of these details is described in Registration.
Types of Application Keys
Spatial provides two types of application keys: "Production" and "Development". Most commonly, Spatial customers, who ship non-evaluation or development versions of Spatial products, obtain a "Production" application key, which is a permanent key.
The "Development" application key is automatically generated if any of the Spatial products bound to the application key are covered by an evaluation or development contract. The "Development" application key expires at the earliest expiration date of all relevant product contracts.
Using Your Application License Key
Application keys must be obtained from the Spatial Web site. A valid customer ID is required to access the site. The prompts are straightforward, and when completed, you will be presented with the option to download your C++ file containing your new application license key and other details to facilitate the registration process.
The process for using the key is as follows:
- Get the key by downloading the C++ file.
- Modify your application to include and call the function. Refer to Embedding the Key into Your Application for details.
- Modify the function to check the result of the unlock call. Refer to Checking the Result of the Unlock Call for details.
You may modify the function, but do not modify the variable unlock_str or the call to spa_unlock_products. Modifying these lines invalidates your Application Key at runtime.
Unlock Function
The C++ file contains code that you must embed into the end-user application. The C++ code returned from Spatial's Licensing Web site defines the function unlock_spatial_products_<ALKIndex>. This function is responsible for calling the main licensing function spa_unlock_products (declared in license.hxx) with all the information needed to process the license key and unlock the licensed products.
The unlock function in the C++ file will be similar to the following:
GLOBAL_PROC void unlock_spatial_products_11() { const char* unlock_str = "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000000011111111000000001111111100000000" "1111111100000000111111110000"; spa_unlock_result out = spa_unlock_products( unlock_str ); if ( out.get_state() != SPA_UNLOCK_PASS ) { /* insert your error handling code here */; } }
Important: The definition of the string argument passed into spa_unlock_products must not be edited. Any modification of this string results in a failure to unlock the licensed products.
Embedding the Key into Your Application
- Place the C++ source file in the same component where the end-user application is initialized.
- Forward declare the function unlock_spatial_products_<ALKIndex> in the file from which the unlock function is to be called.
- Ensure that the unlock_spatial_products_<ALKIndex> function is called in the end-user application before accessing any Spatial functionality.
Where <ALKIndex> is the Application Key Index value returned on the Spatial Licensing Web site's final screen upon generating a license key.
Calling the Unlock Function
The call to unlock_spatial_products_<ALKIndex> must be made after ensuring that the Base component is initialized. The necessary sequence of events is to call unlock_spatial_products_<ALKIndex> after the call to api_start_modeller or after an explicit call to initialize_base. The reason for this requirement is that licensing is a consumer of the memory management system which is initialized simultaneously with the Base component. Calling initialization APIs associated with other libraries such as Deformable Modeling or Warping before calling the unlock function is possible to do, however unlock_spatial_products_<ALKIndex> must be called before attempting to use any modeling functionality.
Checking the Result of the Unlock Call
Important: It is absolutely critical that your application checks the result of the unlock. If you do not and there is a problem with your key, such as expiration, the Spatial products within your application will shut down without warning.
The call to spa_unlock_products returns a spa_unlock_result object (defined in spa_unlock_result.hxx). Your application should query this object in order to determine if the Spatial products were successfully unlocked before proceeding. Do this by calling methods on the result object spa_unlock_result to check the result.
The get_state method of the spa_unlock_result object returns a spa_unlock_state enumeration value. Three possible values can be returned by spa_unlock_products. The return values and what they indicate are as follows:
- SPA_UNLOCK_PASS indicates that the licensed products have been successfully unlocked.
- SPA_UNLOCK_PASS_WARN indicates that the licensed products have been successfully unlocked, but the validation manager has issued a warning. Warnings typically occur when the license is set to expire in some time period.
- SPA_UNLOCK_FAIL indicates that an error occurred during validation of the application key or during registration, in which case all Spatial products remain locked.
Troubleshooting When the Unlock Process Fails
If spa_unlock_products returns SPA_UNLOCK_PASS_WARN or SPA_UNLOCK_FAIL, you may retrieve more details concerning the nature of the warning or error from the returned spa_unlock_result object.
The get_message_no method returns the most severe error or warning encountered during validation in the form of a spa_unlock_errmsg enumeration value. The corresponding text message may be retrieved using the get_message_text method. When validation produces a warning or error related to the expiration date of a license, use the get_num_days method to determine the number of days until expiration. If a key has already expired, then the returned value is negative.
The get_log_info method returns a string containing information that can be saved to a file and sent to Spatial for debugging.
The unlock_spatial_products_<ALKIndex> function returned from the Spatial server does not provide any error handling. The spa_unlock_result object returned from the spa_unlock_products function should be checked by the application, and in the event of a failure, a warning or error message should be presented to the end user.
