Home > Getting Started Guide > Installation and Integration

Licensing and Registration

In order to better protect the use of its intellectual property (IP) and gain a more accurate understanding of its use, Spatial has incorporated a licensing requirement into its products. Because Spatial does not sell end-user applications and understands that its customers are sensitive to changes that affect their end users, Spatial has ensured that the licensing process is seamless to the end user. This requirement has driven the design of the process.

At a glance, every application that uses Spatial products requires at least one unique application license key. In order to use the key it must first be embedded within your application. The key is duplicated each time you duplicate your application.

As an add-on benefit to this requirement, Spatial has added an optional registration feature. By using this feature, every installation of your application may be registered with Spatial. Rather than provide a registration application for your end users to run, Spatial supplies libraries that you will use to enable your installer to perform the registration.

Definitions

Application Licensing

About Application Keys

In order to activate protected Spatial software products, you must obtain an application key from the Spatial Licensing Web Site, specifically, one key for each of your applications. For every application key you request, Spatial requires that you submit criteria for the key, including:

Note:  You must obtain a new application key when any of the above criteria changes. Refer to the next topic for example scenarios.

Typically, you will obtain one application key for each of your applications. However, you may wish to obtain different keys for differrent 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.

Example Scenarios for Obtaining a New Application Key

Example 1

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; thus, obtaining a new application key is not required.)

Example 2

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.

Example 3

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 comprises of a key string and a license-specific function provided in a C++ file from the Spatial Licensing 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, discussed later in this section. From the same Web page, you are requested to download the C++ file which, again, contains the application key string and the license-specific function.

The contents of the C++ file are represented as follows:

#include "spa_unlock_result.hxx"
#include "spa_lic_err_gui.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 );

    // NOTE: The Spatial error GUI is activated by default.  Customers
    // are encouraged to replace the following with a customized solution.
    //
    if ( out.get_state() != SPA_UNLOCK_PASS )
    { spa_display_error_gui( out ); }
}

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:

Use of these details is described in the Registration section.

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 Licensing Web site located at www.spatial.com. 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.

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 license function in the C++ file is represented as follows:

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 )
    { spa_display_error_gui( out ); }
}
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.

Procedure for Using the Key to Unlock Spatial Products

The process for using the key is as follows:

  1. Add the function to your application. Refer to the section Embedding the Key into Your Application for details.
  2. Compile your code.
  3. Call the function at startup time.

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.

Embedding the Key into Your Application

  1. Place the C++ code file in the same component where the end-user application is initialized.
  2. Forward declare the function unlock_spatial_products_<ALKIndex> in the file from which the unlock function is to be called.
  3. Ensure that the unlock_spatial_products_<ALKIndex>() function is called in the end-user application before accessing any Spatial functionality. The value for <ALKIndex> is the Application Key Index value returned on the Spatial Licensing Web site's final screen upon generating a license key.

    Note for ACIS products:  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.
  4. Note that 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. You may use either the Spatial-supplied error GUI, which is enabled by default, or you may call 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.
  5. The following libraries are needed by your application at runtime. Through the use of #pragma comment directives, these libraries are linked into your application automatically by building the function unlock_spatial_products_<ALKIndex>:

Note:  The SPALicErrGUI.dll library is not required if you do not use the Spatial-supplied error GUI. Make certain that you comment out the lines shown in step 4 to prevent this DLL from being linked into your application.

REMINDER!
The most significant lines of code from the unlock_spatial_products() function are unlock_str and spa_unlock_products(). These lines must be called before any Spatial product APIs are called. As long as these lines of code are executed somewhere in your application, then using the customized function becomes irrelevant (for example, you may cut and paste the code to another location).

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_error_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 contains a default implementation of error handling. The spa_unlock_result object returned from the spa_unlock_products() function is passed into a simple error window object that displays the warning or error message to the end user. If an unlock error occurs, then you may choose the option to save a log file and send it to Spatial for debugging.

You most likely will implement your own means to notify your end users concerning the outcome of the call to spa_unlock_products(). If desired, the code defining unlock_spatial_products_<ALKIndex>() may be modified to return the outcome of the unlocking process to its calling function by commenting out the following #include and function call:
#include "spa_lic_err_gui.hxx"
...
spa_display_error_gui(out);

Registration

The Spatial registration function is used to register each installation of an application containing Spatial products. As the developer of a Spatial-enabled application, you will provide your end users with the means of performing this registration. Hence, Spatial has supplied a C DLL file containing a registration function. You will modify your installer to call this function, supplying it with data about your application.

The registration function requires an Internet connection. In the event that an Internet connection is unavailable or registration fails for any other reason, the registration function leaves a record of the failed attempt on the installation machine. Spatial provides a utility (the  Spatial Registration Utility) to recover from failed registration attempts.

Using the Registration Function

This section provides syntax and details regarding the registration API's parameters. The registration function must be called by your application, not the installer.

Syntax

The syntax for the registration function is as follows:

logical spa_lic_register_product (
      int app_key_index,
      const char* version,
      const wchar_t* customer_name,
      const wchar_t* application_name,
      const wchar_t* user_company_name,
      spa_lic_purpose license_purpose,
      const wchar_t* err_report_file=NULL,
      logical display_internet_access_panel=TRUE);

logical spa_lic_register_product (
      int app_key_index,
      const char* version,
      const char* customer_name,
      const char* application_name,
      const char* user_company_name,
      spa_lic_purpose license_purpose,
      const char* err_report_file=NULL,
      logical display_internet_access_panel=TRUE);

Parameters

Specifically, the parameters are defined as follows:

Returns

Possible return values are as follows:

TRUE indicates license installation was successful.
FALSE indicates license installation was unsuccessful.

Proxy Login Information

When the Registration function attempts to access the Internet, a new window is displayed asking the user for proxy login information if proxy authentication is required. The information needed includes:

Notes

The network message window is enabled by default as it is required by anti-spyware statutes in some locations. The window can be disabled by providing a FALSE value for the display_internet_access_panel argument. If you choose FALSE, then you must supply your own form of notification; do not avoid notification altogether.

IMPORTANT!
Spatial customers who choose the value FALSE for the display_internet_access_panel argument accept sole responsibility for the behavior of their installer, including Spatial's registration process, especially in locations where anti-spyware statutes apply.

The Spatial registration function requires the following files in order to run; they must be in the same folder, redistributed with the registration API and registration GUI:

The registration DLLs are not shipped on any debug arches.

Spatial Registration Utility

Spatial has provided a registration utility for you to use and redistribute to your end users. Its primary purpose is to perform registration in the event of a previously failed registration attempt. The utility also provides a means to manually register without using an installer by entering all of the parameters of the registration function (refer to Registering without an Installer for more information).

The Spatial Registration Utility requires an Internet connection. Typically, use of this utility occurs for those needing to register machines that do not have Internet access. Run the utility from an administrator machine with both Internet access and LAN access to the target machines.

Notes

The Spatial Registration Utility uses functionality that is not supported by Visual C++ 6 SP5. For this platform, the GUI built with Visual Studio .NET 2003 is provided in the bin/NT_NET_DLL directory.

The Spatial Registration Utility is not supported on Windows 2000 or earlier operating systems.

The Spatial Registration Utility requires the following files in order to run; they must be in the same folder, redistributed with the registration API and registration GUI:

The Spatial Registration Utility is not shipped on any debug arches.

The Spatial Registration Utility requests proxy login information if proxy authentication is required.

Components of the Spatial Registration Utility

The utility consists of three tabs: Local, Network, and Application.

Local Tab

The Local tab allows you to register installations of Spatial-enabled applications for this machine (the machine on which the utility is running). Upon enabling the utility, all applications for which registration has been attempted are shown. Every time the Local tab is accessed, this automatically refreshes the list of applications.

Network Tab

The Network tab allows you to register remote machines having applications that use Spatial products. Upon enabling the utility, the list of remote machine applications is empty. Once you supply a list of remote machines, each machine is accessed, and the pane displays all applications for which registration has been attempted. Every time the Network tab is accessed, this automatically refreshes the network machines list.

Application Tab

The Application tab allows you to manually register your machines having applications that use Spatial products by entering the same parameters as the registration function.

Registering Your Machines Using the Spatial Registration Utility

You may choose to register your applications with the utility because you may be:

Recovering from a Failed Registration Attempted by Your Product Installer

If you have attempted to register your Spatial products with your product installer by calling the Spatial registration API, and the registration was unsuccessful, then you may register using the Spatial Registration Utility.

Before you begin, ensure the following prerequisites:

To register your machine:

  1. Launch the utility, spa_lic_app.exe. Applications that access Spatial products appear in the Local tab of the utility and display their current state of registration.
  2. Select the application that you wish to complete registration. The Register button becomes enabled.
  3. Select the Register button. The utility contacts the registration server and registers the application.
  4. Check the Status field for the recently registered application:
    • If the Status field shows that registration was successful, you may close the utility.
    • If the registration status shows that the process was unsuccessful, then an error log can be retrieved by selecting the enabled Save Log... button. Proceed to Troubleshooting Registration Failures.
Registering Remote Machines without Network Access

If you have attempted to register remote machines with your product installer by calling the Spatial registration API, and the registration was unsuccessful, then you may register using the Spatial Registration Utility.

Before you begin, ensure the following prerequisites:

To register your remote machines:

  1. Launch the utility, spa_lic_app.exe.
  2. Select the Network tab.
  3. Select the Node List... button. A standard Windows Open dialog appears.
  4. Select the text file that contains the list of machines accessible on the network. This list may be a comprehensive list of machines accessible on the network or may contain solely those you wish to have registered. The utility opens the file and displays the list of installed applications containing Spatial products and their current state of registration in the Network tab.
  5. From the list in the Network tab, select the applications for which you wish to complete their registration. Use the CTRL and Shift keys to select individual rows or groups of rows. You may sort the rows by machine name, application name, license type, expiration date, or by status by clicking on the column heading. The Register button becomes enabled.
  6. Select the Register button. The utility contacts the registration server and registers the application.
  7. Check the Status field for the recently registered application:
    • If the Status field shows that registration was successful, you may close the utility.
    • If the registration status shows that the process was unsuccessful, then an error log can be retrieved by selecting the enabled Save Log... button. Proceed to Troubleshooting Registration Failures.
Registering without an Installer

You may opt to register your Spatial products without using an installer. The Application tab in the Spatial Registration Utility allows you to enter the same parameters as you would have with the registration function in an installer.

Before you begin, ensure the following prerequisites:

To register your machine:

  1. Launch the utility, spa_lic_app.exe.
  2. Select the Application tab.
  3. Enter the company name, application name, software publisher, and application ID in the appropriate fields.
  4. Choose the type of license for the application to be registered from the drop down box. Once all fields have been completed, the Register button becomes enabled.
  5. Select the Register button. The utility contacts the registration server and registers the application.
  6. Check the Status field for the recently registered application:
    • If the Status field shows that registration was successful, you may close the utility.
    • If the registration status shows that the process was unsuccessful, then an error log can be retrieved by selecting the enabled Save Log... button. Proceed to Troubleshooting Registration Failures.

Note:  If the machine does not have Internet access, then the utility reports that the registration has failed. In this case, a temporary license is installed on the machine so that it is authorized to use Spatial products for 30 days.

Troubleshooting Registration Failures

Upon unsuccessful registration, an error log is generated. You may retrieve the error log from the Spatial Registration Utility by selecting the Save Log... button on either the Local or Network tab. The error log contains details that allow Spatial to troubleshoot the cause for the unsuccessful registration. Spatial will not distribute or make public any of the details in the error log; this log file is for troubleshooting purposes only.

To retrieve the error log:

  1. Select the activated Save Log... button.
  2. When the Save dialog appears, choose an accessible location.
  3. Submit the log file from the Spatial Services Web site.

Related topics:

Redistributing the Spatial Registration Utility

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.