VLS_REQUEST \ LSRequest

Requests an authorization license code from the License Manager.

NOTE If a particular License Manager name is not set as the Contact server, the application will determine the server name using the default mechanism (broadcast within the subnet). In this case, the License Manager that grants the license is also set/designated as the contact server.

Syntax

LS_STATUS_CODE VLS_REQUEST (unsigned char      *feature_name,
                            unsigned char      *version,
                            LSHANDLE           *handle_addr );

Argument	Description
feature_name	Name of the feature for which the licensing code is requested. May consist of any printable characters and cannot be NULL. 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.
handle_addr	The handle for this request is returned in handle_addr. This handle must be used to later update and release this license code. A client can have more than one handle active at a time. Space for the handle must be allocated by the caller.

Description

The VLS_REQUEST function is used by the application to request licensing resources to allow the application to execute. If a valid license is found, LS_SUCCESS is returned. Both feature and version strings are used to identify matching license(s). When the application has completed execution, it must call VLS_RELEASE to release the license resources.

Every client should complete this call successfully before commencing execution of the application or the feature.

If the default error handler is not used, the client application must check the status code returned and should continue only if LS_SUCCESS is returned. The default error handler will exit the application on error.

If queuing is desired, you must use VLSqueuedRequest instead.

About LSRequest

A variant of the VLS_REQUEST function LSRequest is also available which allows passing additional parameters for specific purposes. Refer to the syntax, parameters, and description for more details.

The function calls, return codes, and data types that begin with the LS prefix are part of the LSAPI standard, which was followed up till few years ago and has now been dropped. The API that begin with the VLS prefix are the extensions that make licensing easier to implement.

LS_STATUS_CODE LSRequest (	 	 
unsigned char	 	*license_system,
unsigned char	 	*publisher_name,
unsigned char	 	*product_name,
unsigned char	 	*version,
unsigned long	 	*units_reqd,
unsigned char	 	*log_comment,
LS_CHALLENGE	 	*challenge,
LSHANDLE	 	*lshandle );

Argument	Description
license_system	Unused. Use LS_ANY as the value of this variable. LS_ANY is specified to indicate a match against installed license systems.
publisher_name	A string giving the publisher of the product. Limited to 32 characters and cannot be NULL. Company name and trademark may be used.
product_name	Same as VLS_REQUEST's feature_name parameter described above.
version	Same as VLS_REQUEST's version parameter described above.
units_reqd	>The number of licenses required. The License Manager verifies the requested number of units exist and may reserve those units. The number of units available is returned. If the number of licenses available with the License Manager is less than the requested number, the number of available licenses will be returned using unitsReqd. If unitsReqd is NULL, a value of 1 unit is assumed. >From RMS v9.5 onwards, up to 4,294,967,294 licenses units are supported. This is applicable for license version 20 and above.
log_comment	>If vendor usage data attribute consists of multiple words, each will be anonymized individually, only if they are separated using a space. In general, avoid specifying the same entry (or word) twice in the vendor usage data attribute as the "uniquely" anonymized data will be repeated. >The spaces in the vendor usage data attribute are replaced with underscores (_). Also, the keyword <an> itself is not anonymized and is replaced by an underscore (_) in the resulting usage log line record. >To complete the vendor usage data attribute anonymization process, the system administrator must have also allowed anonymity of user information (either by setting the LS_LOG_ANONYMITY environment variable or using the -log-anonymity License Manager start-up option).
challenge	The challenge structure. If the challenge-response mechanism is not being used, this pointer must be NULL. The space for this structure must be allocated by the calling function. The response to the challenge is provided in the same structure, provided a license was issued (the function returned LS_SUCCESS).
lshandle (OUT)	Same as VLS_REQUEST's handle_addr parameter described above.

If you wish to add your own log comments to the RMS usage logs, then you should use the LSRequest function instead of the more generic VLS_REQUEST.

You would use LSRequest also when you have decided to use the challenge-response mechanism for authenticating the License Manager that issued licenses. If a valid license is found, the challenge-response is computed (if applicable) and LS_SUCCESS is returned. The challenge-response is computed if a non-NULL value is passed for the challenge argument.

At minimum, the feature and version strings are used to identify matching license(s).

If the number of units required is greater than the number of units available, then LSRequest will not grant the license.

Returns

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

Error Code	Description
VLS_CALLING_ERROR	>lshandle is NULL. >challenge argument is non-NULL, but cannot be understood. >Attempted to use standalone mode with network-only library, or network mode with standalone library. >The log comment value has exceeded the maximum allowed buffer size. Up to 100 characters are allowed (excluding the null character). If you plan to have only a part of data as anonymized, then use the following formula to calculate the maximum allowed data: 100 bytes = 17x + y, where "x" is the number of words to be anonymized and "y" is the length of the unanonymized data. If you plan to have only anonymized characters in the usage log file, then after the anonymization tag <an>, up to 6 words separated by a space can be included. >The log comment probably consists of the hash (#) sign in the beginning or end of the string. Also, it should not contain consecutive hash signs.
VLS_APP_UNNAMED	>featureName is NULL >version is NULL. >Both feature name and version cannot be Null at the same time.
VLS_NO_LICENSE_ GIVEN	unitsReqd is zero.
VLS_NO_SUCH_ FEATURE	The License Manager does not have a license that matches the requested feature and version.
LS_INSUFFICIENTUNITS	>License Manager does not currently have sufficient licensing units for requested feature to grant license. >The units_reqd parameter of the call contains the hard limit of the feature for which authorization was requested if this request exceeded the hard limit of the license.
LS_LICENSE_EXPIRED	License is expired.
VLS_TRIAL_LIC_NOT_ACTIVATED	When the trial license precedence is zero or the trial license persistence data is corrupted.
VLS_TRIAL_LIC_ EXHAUSTED	Trial license expired or trial license usage exhausted.
VLS_APP_NODE_ LOCKED	Requested feature is node locked, but request was issued from 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_SERVER_SYNC_IN_PROGRESS	License Manager synchronization in process.
VLS_FEATURE_ INACTIVE	Feature is inactive on the specified License Manager.
VLS_MAJORITY_RULE_FAILURE	Majority rule failure prevents token from being issued.
VLS_NO_SERVER_ RUNNING	License Manager on specified host is not available for processing license operation requests.
VLS_NO_SERVER_ RESPONSE	Communication with License Manager has timed out.
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.
VLS_BAD_SERVER_ MESSAGE	Message from License Manager could not be understood.
LS_NO_NETWORK	Generic error indicating that the network is unavailable for servicing the license operation.
LS_NORESOURCES	An error occurred in attempting to allocate memory needed by function.
VLS_INTERNAL_ERROR	An internal error has occurred in the processing.
VLS_RESOURCE_LOCK_FAILURE	Failed to fetch the API resource lock. On receiving this error, retry calling this API.

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