VLSlicense

Initializes contact with the License Manager, requests authorization and automatically updates the license.

Syntax

LS_STATUS_CODE VLSlicense (unsigned char              *featureName,
                            unsigned char              *version,
                            LS_HANDLE                  *lshandle );

 

Argument	Description
featureName	Name of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 24 characters.
version	Version of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 11 characters.
lshandle (out)	This handle must be used to release this license code by calling VLSdisableLicense. Space must be allocated by the caller.

Length limitations exist on feature name and version depending on the type of license you want to issue to your customer. See the Sentinel RMS SDK Developer Guide for details.

Description

This function obtains a license using LSRequest and then automatically updates the license after 80% of the license lifetime has passed using the LSUpdate function. This function uses timers (SIGALRM on UNIX) to update a license periodically for Win32 GUI-based applications and UNIX applications. You should not update that license yourself using LSUpdate or any other license renewal function.

NOTE   Since v9.2.0, the automatic update (using timers) is supported on Win32 console application as well.

When you wish to release the license (terminate the automatic updates), you must use the API function VLSdisableLicense, which removes the timer and releases the license. If you release the license using LSRelease and your application continues to run, the timer will keep trying to renew an invalid license since it does not know that you have released the license yourself.

On UNIX, since there is only one timer available to each running application, there will be a conflict if your application wishes to use timers and use VLSlicense at the same time. To accommodate multiple simultaneous uses of a single timer, the Sentinel RMS API provides a generalized version of the timer functions.

NOTE   This function is available on most UNIX platforms. This function may not be available on platforms that do not support a timer event or a time signal.

Returns

The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes:

Error Code	Description
VLS_APP_UNNAMED	>featureName is NULL >version is NULL >Both feature and version cannot be NULL at the same time.
VLS_CALLING_ERROR	>lshandle is NULL. >Attempted to use standalone mode with network only library, or network mode with standalone library.
LS_INSUFFICIENTUNITS	License Manager does not currently have sufficient licensing units for requested feature to grant a license.
VLS_NO_SUCH_FEATURE	License Manager does not have a license that matches requested feature, version and capacity.
VLS_TRIAL_LIC_EXHAUSTED	Trial license has expired.
LS_LICENSE_EXPIRED	License has expired.
VLS_APP_NODE_LOCKED	Requested feature is node locked, but request was issued from an unauthorized machine.
VLS_USER_EXCLUDED	User or machine excluded from accessing requested feature.
VLS_VENDORIDMISMATCH	This error can occur under the following scenarios: >The vendor of the requesting application does not match with the License vendor. >The License addition failed due to mismatch among the vendor of the license and vendor of the isolated License Manager.
VLS_NON_REDUNDANT_ SRVR	License Manager is non-redundant and therefore cannot support this redundancy-related operation.
VLS_SERVER_SYNC_IN_ PROGRESS	License Manager synchronization in process.
VLS_FEATURE_INACTIVE	Feature is inactive on specified License Manager.
VLS_MAJORITY_RULE_ FAILURE	Majority rule failure prevents token from being issued.
VLS_NO_SERVER_RESPONSE	Communication with License Manager has timed out.
VLS_BAD_SERVER_ MESSAGE	Message returned by License Manager could not be understood.
VLS_NO_SERVER_RUNNING	License Manager on specified host is not available for processing license operation requests.
VLS_HOST_UNKNOWN	Invalid hostName was specified.
VLS_NO_SERVER_FILE	The License Manager has not been set and the client application is unable to determine which License Manager to use.
LS_NORESOURCES	An error occurred in attempting to allocate memory needed by this function.
LS_NO_NETWORK	Failed to initialize Winsock wrapper. (Only applicable if using network-only library.) Generic error indicating network failure.
VLS_INTERNAL_ERROR	An internal error has occurred in processing.

For a complete list of the error codes, see Licensing Library Error and Result Codes.