Getting Started With the Licensing API Calls

The code snippet below illustrates the most basic API functions used for implementing licensing:

/* Traditional API-based implementations*/
int main ()
{
  /* Calling VLSinitialize */
  status = VLSInitialize();
  /* Calling LSRequest */
  status = LSRequest(...);
  /* Calling LSUpdate */
  status = LSUpdate(...);
  /* Releasing the license token */
  status = LSRelease(...);
  /* Cleaning up the library */
   status = VLScleanup();
  return 0;
}

 

NOTE   For more information about traditional API, refer to the Sentinel RMS Legacy API and Features.

Initializing the Client Library - VLSinitialize

VLSinitialize is the first Sentinel RMS licensing function to be called in your application during its initialization. It has no parameters and will return LS_SUCCESS status upon success. You should proceed with your application after this call.

License Manager Detection - VLSsetContactServer and the Environment Variables

If you provide no information in the licensed application about the location of the RMS License Manager, it will use the broadcast mechanism to find an RMS License Manager on the local subnet. It will automatically establish a dialog with the first License Manager with a license for the given feature and version. However, this can be time-consuming on a large and busy network. You can prevent a network broadcast and instead direct the application to specific License Managers in the following ways:

>Using the LSFORCEHOST and LSHOST environment variables.

>Using the VLSsetContactServer API function

See Which Licensing Library to Use?.

Application Identification - LSRequest

LSRequest is the next function to be called. This function takes several parameters, including the PublisherName (identifies your company), the FeatureName (identifies your product), and the Version (identifies the version number for that product).

NOTE   The feature name and version specified in this call must match with what you specify during the license generation.

Each successful request returns a client handle, which identifies the dialog set up between the licensed application and the License Manager. This handle should be used in all subsequent dialogs or library calls. This architecture enables a licensed application to set up multiple connections with the License Manager and request multiple licenses. The License Manager treats each request independently. If you are going to license your application without separate feature sets, you will only need to call LSRequest once. However, if you are planning to license and charge based on features, you will need to call LSRequest once for each feature. These features will need to have a different name for identification. Each feature can have a version associated with it.

If you choose to implement license queuing, you may want to use the VLSqueuedRequest call instead.

Updating License Usage - LSUpdate

By default, auto timer is enabled to ensure that the license token is automatically renewed before it expires. This frees the application from worrying about renewing the license on a rigid time schedule. In case auto timer has been disabled, you can also call the LSUpdate API function periodically to ensure that the license token is renewed successfully (before it expires). It is important to note these behaviors are applicable to both network and standalone deployments.

Release and Cleanup - LSRelease and VLSCleanUp

Once the user has finished using the licensed feature/application, call LSRelease to return the license (or more precisely the license token) so other users can use it. Finally, after all licenses have been released and the program is ready to terminate, a call is made to VLScleanup to inform the library that any resources that it has allocated may be released.

Special Licensing Cases

There might be cases where you want to take advantage of built-in support for special licensing options. For example, a shared license allows more than one application/component to share the same license. This is useful for logically grouping similar features which you do not intend to charge the user for separately.

Another example of special licensing is the held license. If your program is short-lived, you can use VLSsetHoldTime to set the checkout time for a license. This allows users to reclaim a license when running a short-lived, frequently used application, such as a compiler.

Disabling Licensing

The macro NO_LICENSE in the lserv.h file can be set to completely disable licensing from your licensed application for debugging. This replaces all Sentinel RMS licensing function calls with LS_SUCCESS statements. Don’t forget to re-enable licensing before preparing your application for shipment.