Chapter 3 License Management

There's a distinction between a license (or "activation") file or string, and a license. When you buy an RTI product, such as RTI Connext Professional, you are licensed to use it.

Within a package, some components may have to be activated using a license file or string, while others may not. For example, when you install the RTI Connext Professional package, the Core Libraries (which you are licensed to use) do not require a license file or string. However, tools like RTI Admin Console (which you are also licensed to use) require a license file.

Some components that do not require a license file in certain packages may require a license file in other packages. For example, the Core Libraries require a license file in the evaluation ("eval") and LM ("lm") packages. If a component in your Connext distribution requires a license file, you will receive one from RTI.

This section describes how to manage a license file. If you have more than one license file from RTI, you can concatenate them into one file. A single license file can be used to run on any architecture and is not node-locked. You are not required to run a license server.

In the rest of this section, the term license file is used interchangeably with activation file. We also use the term file generically to refer to both an actual file and the string with the contents of the file.

3.1 Installing the License File

You can install a license file using the six different mechanisms below, in order of priority. The first two mechanisms only activate the Connext Core Libraries in the LM or evaluation bundles. The other mechanisms apply to all the Connext components that require a license file, including the Connext Core Libraries in the LM and evaluation bundles.

You can also specify the location of your license file in RTI Launcher's Configuration tab. Then Launcher can copy the license file to the installation directory or to the user workspace.

In all components (such as Admin Console) except for the Connext Core Libraries, each time the component starts, it will look for the license file in the locations listed below until it finds a valid license.

For the Connext Core Libraries in the LM or evaluation bundles, your application's call to DomainParticipantFactory.create_participant() will return null, preventing communication, if it cannot find a valid license.

In the PropertyQosPolicy of the DomainParticipant, there may be a property called dds.license.license_string. (Only if you have an "eval" or "lm" version of Connext.) The value for this property can be set to the content of a license file. (This may be necessary if a file system is not supported on your platform.) You can set the property either in source code or in an XML file. An XML file example is shown below:

<domain_participant_qos>
    <property>
        <value>
            <element>
                <name>dds.license.license_string</name>
                <value>contents of license file</value>
            </element>
        </value>
    </property>
</domain_participant_qos>

If the content of the license file is in XML, special characters for XML need to be escaped in the license string. Special characters include: quotation marks (") (replace with "), apostrophes (') (replace with '), greater-than (>) (replace with >), less-than (<) (replace with <), and ampersands (&) (replace with &).

In the PropertyQosPolicy of the DomainParticipant, there may be a property called dds.license.license_file. (Only if you have an "eval" or "lm" version of Connext.) The value for this property can be set to the location (full path and filename) of a license file. (This may be necessary if a default license location is not feasible and environment variables are not supported.) You can set the property either in source code or in an XML file.

Example XML to set dds.license.license_file:

<domain_participant_qos>
    <property>
        <value>
            <element>
                <name>dds.license.license_file</name>
                <value>path to license file</value>
            </element>
        </value>
    </property>
</domain_participant_qos>

In the location specified in the environment variable RTI_LICENSE_FILE, which you may set to point to the full path of the license file, including the filename.

Note: When you run any of the scripts in the <NDDSHOME>/bin directory, this automatically sets the RTI_LICENSE_FILE environment variable (if it isn't already set) prior to calling the executable. It looks for the license file in two places: your rti_workspace directory and the installation directory (NDDSHOME). (See Chapter 2 Paths Mentioned in Documentation.)

If you are running any of the tools/services as executables via NDDSHOME/bin/<executable script> or through Launcher:

In your rti_workspace/<version> directory, in a file called rti_license.dat.
In your rti_workspace directory, in a file called rti_license.dat.
In <NDDSHOME> (the Connext installation directory), in a file called rti_license.dat.

If you are running your own application linked with Connext libraries:

In your current working directory, in a file called rti_license.dat.
In <NDDSHOME> (the Connext installation directory), in a file called rti_license.dat.

You can also provide a license string by creating a shared library called rti_activation, which implements the activation API. See 3.3 Activation Library.

As Connext attempts to locate and read your license file, you may (depending on the terms of the license) see a printed message with details about your license.

If you have any problems with your license file, please email support@rti.com.

3.2 Adding or Removing License Management

If you are using a package type that requires a license file and your license file changes—for example, you receive a new license for a longer term than your original license—you do not need to reinstall Connext.

However, if you switch from an evaluation ("eval") or LM ("lm") distribution of Connext to a regular distribution, or vice versa, RTI recommends that you first uninstall your original distribution before installing your new distribution. Doing so will prevent you from inadvertently using a mixture of libraries from multiple installations.

3.3 Activation Library

Providing a license string by copying a license file into the filesystem where the Connext applications run may not be feasible. For example, you may have your own license server from which you want to obtain all the licenses required by your applications, including the Connext licenses.

To help support these use cases, Connext allows you to provide a license string by implementing the C activation API in a shared library called rti_activation (e.g., librti_activation.so, rti_activation.dll). This activation mechanism is available on all platforms but VxWorks.

The C activation API is provided in the header file ndds/dl_driver/dl_driver_activation_user.h.

You must implement the following three APIs:

/**

* @brief Get the activation string.

* @pre buffer can be NULL if *size is 0.

* @pre size cannot be NULL.

* @pre exception cannot be NULL.

* @param buffer Out. Buffer where the activation string will be copied.

* @param size In/Out. In: Size of the buffer. Out: Size of the activation

* string. The size includes the null terminator.

* @param user_data In. User data returned by RTI_ActivationLibrary_initialize().

* @param exception Out. Exception object. If there is no error, code will be

* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code

* will be set to any of the predefined errors

* (RTI_ACTIVATION_LIBRARY_EXCEPTION_ERROR or

* RTI_ACTIVATION_LIBRARY_EXCEPTION_INSUFFICIENT_SPACE) or a user-defined

* error code. The exception message will contain a description of the error.

* If the input buffer is not big enough to hold the activation string, the

* function will return RTI_ACTIVATION_LIBRARY_EXCEPTION_INSUFFICIENT_SPACE

* and *size will be set to the required size of the activation string.

* This function can be called in parallel by multiple threads.

* @return 0 if there is an error, 1 otherwise.

*/

DLDRIVERDllExport

int RTI_ActivationLibrary_get_activation_string(

        char *buffer,

        unsigned int *size,

        void *user_data,

        struct RTI_ActivationLibraryException *exception);

/**

* @brief Initialize the activation library.

* This function will be called once after loading the activation shared

* library.

* @param user_data Out. User data. The library can initialize *user_data to

* NULL or to a pointer to a library-defined object.

* @param error_contact_info Out. Who-to-contact message. The library can use

* this message to change the displayed who-to-contact message in case of an

* exception.

* @param exception Out. Exception object. If there is no error, code will be

* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code

* will be set to any of the predefined errors or a user-defined error code.

* @return 0 if there is an error, 1 otherwise.

*/

DLDRIVERDllExport

int RTI_ActivationLibrary_initialize(

        void **user_data,

        char error_contact_info[RTI_ACTIVATION_LIBRARY_CONTACT_INFO_MESSAGE_MAX_SIZE],

        struct RTI_ActivationLibraryException *exception);

/**

* @brief Finalize the activation library.

* This function will be called once after unloading the activation shared

* library.

* @param user_data In. User data.

* @param exception Out. Exception object. If there is no error, code will be

* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code

* will be set to any of the predefined errors or a user-defined error code.

* @return 0 if there is an error, 1 otherwise.

*/

DLDRIVERDllExport

int RTI_ActivationLibrary_finalize(

        void *user_data,

        struct RTI_ActivationLibraryException *exception);

The loading of the rti_activation library will be done transparently by Connext if available in the environment, but only as the last mechanism for activation. If any other mechanism is provided (such as a valid license file), this library will not have any effect.

Once loaded, the RTI_ActivationLibrary_initialize API will only be called once per process. This provides an opportunity to initialize some state required to obtain the activation string. This state is returned in the userData output parameter.

The RTI_ActivationLibrary_get_activation_string API may be called one or more times per process whenever a valid activation string is needed. For example, for the Connext Core Libraries distributed with the LM or evaluation bundles, the API is called every time a DomainParticipant is created.

Optionally, before your application finishes, you might want to unload the Activation Library as part of your cleanup process. For this purpose, Connext provides the NDDS_LM_unload_activation_library() API, which will internally both call RTI_ActivationLibrary_finalize and unload the rti_activation shared library. This function is available for the C, Traditional C++, and Modern C++ API’s:

DDS_Boolean NDDS_LM_unload_activation_library();

Traditional C++:

class NDDSLM {

    static DDS_Boolean unload_activation_library();

};

Modern C++:

namespace rti { namespace util { namespace activation {

    bool unload_activation_library();

};