VLSrequestExt2

Syntax

VLSrequestExt2 (	 	 
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,
LS_HANDLE	 	*lshandle,
VLSserverInfo	 	*serverInfo,
unsigned long	 	*team_capacity_reqd,
unsigned long	 	*user_capacity_reqd,
unsigned char	 	*vendor_identifier,
unsigned long	 	*special_flag );

Argument	Description
license_system	Unused. >Use LS_ANY as the value of this variable. > LS_ANY is specified to indicate a match against the installed license system.
publisher_name	>A string identifying the publisher of the product. Limited to 32 characters and cannot be NULL. >Company name and trademark may be used.
product_name	>Name of the feature for which a license code is requested. >May consist of any printable characters and cannot be NULL. >Limited to 24 characters.
version	>Version of the feature for which a license code is requested. >May consist of any printable characters. Limited to 11 characters. >Version can be NULL.
units_reqd	>The number of licenses required. The License Manager verifies that the number of units exist and may reserve those units. The number of available units is returned. >From RMS v9.5 onwards, up to 4,294,967,294 licenses units are supported. This is applicable for license version 20 and above. >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 units_reqd. If units_reqd is NULL, a value of 1 unit is assumed. >To use the capacity licensing it is necessary that units required be always 1.
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(IN/OUT)	>The challenge structure. If challenge-response mechanism is not being used, this pointer must be NULL. >The response to the challenge is provided in the same structure, provided a license was issued, i.e., provided the function VLSrequestExt2 returns LS_SUCCESS.
lshandle	>The handle for this request is returned in lshandle. 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 lshandle must be allocated by the caller.
serverInfo(IN/OUT)	>This information is passed to the License Manager for use in License Manager hook functions. >VLSinitServerInfo must be called to initialize serverinfo.
team_capacity_reqd	>Required team capacity >If the License Manager does not have the requested capacity this field will return the team capacity available with the License Manager for this feature and version. >If the request is made for a non-capacity license, this must be passed as NULL.
user_capacity_reqd	>Required user capacity >If the License Manager does not have the requested user capacity, this field will return the user capacity available with the License Manager for this feature and version. >If the request is made for a non-capacity license this must be passed as NULL.
vendor_identifier	Specify the same string as used in the VLSenableVendorIsolation API function while customizing the isolated License Manager. For more information, see the section “Deploying Isolated License Manager”. >If the two strings do not match, then error VLS_NON_INTENDED_SERVER_CONTACTED is returned, implying that the license is being requested from a generic License Manager or any other vendor’s isolated License Manager. >If NULL is specified, there will be no change in the behavior of this API.
special_flag(IN/OUT)	An IN/OUT parameter with the following possible values: >The IN value can be any of the following: •VLS_IGNORE_GRACE_ERROR - Any error encountered during the installation of a grace license will be ignored and the VLSrequestExt2 function will succeed. • VLS_NOTIFY_GRACE_ERROR - Any error encountered during the installation of a grace license will make the VLSrequestExt2 function fail (and the application will not run). •VLS_DISABLE_GRACE_BROADCAST - Introduced in v9.2.0, this suppresses the network broadcast taking place in the case of a grace license. You can also pass VLS_IGNORE_GRACE_ERROR or VLS_NOTIFY_GRACE_ERROR in combination with VLS_DISABLE_GRACE_BROADCAST (using the OR operator). >The OUT value will be the grace period-related error code. •VLS_IGNORE_GRACE_ERROR will be applicable to the other variants of the request API functions (like LSrequest, VLSrequestExt, and so on).

Description

NOTE Supports capacity as well as non-capacity requests.

If the request is denied due to either insufficient team capacity or user capacity then accordingly the capacity_reqd or team_capacity_reqd field should contain the available capacity.

NOTE This API has been updated to additionally support license requests intended for isolated License Managers. Since v8.6.0, the vendor_identifier parameter has been introduced for directing the license requests to vendor-specific isolated License Managers.
Before granting a license, the vendor identifier obtained in the license request is matched with that of the isolated License Manager. For more information about the isolated License Managers, see the Chapter- Isolated License Managers of the Sentinel RMS SDK Developer guide.

VLSrequestExt2 must be used whenever the user wishes to use the capacity feature in a license. The call can also be used to obtain a token from normal license.

If the developer wishes to override any of the default user information passed to the License Manager, he would be using the VLSsetTeamId/ VLSsetTeamIdValue API.

The following information is sent by the licensing library as user identification information:

>User Name

>Host Name

>X-Display name

>Vendor defined string

This information is used by the License Manager when it manages or creates teams. VLSsetTeamId/ VLSsetTeamIdValue needs to be called before calling the request API so that it can pass the correct information about the user name etc. to the License Manager.

Lets consider a possible scenario to interpret the above:

Say we initialize the license system as:

int team_id = 1; /* Override username information */
int units_reqd = 1; /* Should always be 1 if using capacity request*/
unsigned long team_capacity = 1000; /* Say*/
unsigned long user_capacity = 800; /* Cannot be greater than team
  
LS_STATUS_CODE ret_val;
   if(VLSinitialize()){
     // Error in initializing SLM library.
     // Do error condition
   }
   VLSsetTeamId(1,"SENTINEL");
  
Here we pass ‘SENTINEL’ as the user name. So even if the user has logged into the client machine with say "XYZ" user name, the License Manager would see the request as if it is coming from user "SENTINEL". Now
  
ret_val = VLSrequestExt2(featureName, version,&units_reqd, &team_capacity, &user_capacity);
   if(ret_val == LS_SUCCESS){
// Succesfully got the requested token as well as team and user capacity. Now do further actions based on these values
 }

In case you are unable to get a license token.The possible reasons could be:

> Team limit has been exhausted

>User capacity has been exhausted

>Team capacity has been exhausted in case of pooled licenses only

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 name and version cannot be NULL at the same time. >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_CALLING_ERROR	>lshandle is NULL >challenge argument is non NULL >Attempted to use standalone mode with network-only library, or network mode with standalone library.
VLS_NO_LICENSE_GIVEN	>unitsReqd is zero >License request is denied due to License Manager hook failure.
VLS_NO_SUCH_FEATURE	License Manager does not have license that matches requested feature, version and capacity.
LS_NOLICENSESAVAILABLE	All licenses are in use.
LS_INSUFFICIENTUNITS	License Manager does not have sufficient licensing units for requested feature to grant license.
LS_LICENSE_EXPIRED	License has expired.
VLS_TRIAL_LIC_EXHAUSTED	Trial license expired or trial license usage exhausted.
VLS_USER_EXCLUDED	User or machine excluded from accessing requested feature.
VLS_CLK_TAMP_FOUND	>License Manager has determined that the client system lock has been modified. >The license for this feature has time tampering protection enabled, so the license operation is denied.
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 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 request.
VLS_NO_SERVER_RESPONSE	Communication with License Manager has timed out.
VLS_HOST_UNKNOWN	Invalid hostName was specified.
VLS_NO_SERVER_FILE	>No License Manager has been set >Unable to determine which License Manager to use.
VLS_BAD_SERVER_MESSAGE	Message from the 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	Failure occurred in setting timer. (Timer is only attempted to be set if timer is available for platform and if license requires timer for updates.)
VLS_INSUFFICIENT_TEAM_ CAPACITY	License Manager does not currently have sufficient team capacity available.
VLS_INSUFFICIENT_USER_ CAPACITY	License Manager does not currently have sufficient user capacity available for this team member.

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