VLSgetTrialUsageInfo

Client	Server	Static Library	DLL
√		√	√

Obtains cumulative usage (both total and remaining) information about all the trial licenses available on the License Manager for a feature-version.

Syntax

LS_STATUS_CODE VLSgetTrialUsageInfo (	 	 
unsigned char	 	*feature_name,
unsigned char	 	*version,
int	 	feature_index,
VLStrialUsageInfo *trial_usage_info );	 	 

Argument	Description
feature_name	The feature name identifier for the license code.
version	Version of the feature. Must be unique.
feature_index	Used to specify a particular feature-version combination.
trial_usage_info	This API function stores the structure in which the information is obtained. The memory for this structure must be allocated by the caller.

Description

This API is used to obtain trial usage information (including hours left and days left) for trial features. The trial usage information is refreshed while requesting, updating or releasing a trial license.

>If the active feature is an exclusive trial then the API returns trial usage information for this license only.

>If the active feature is an additive trial then the API returns cumulative trial usage information. The cumulative usage information is calculated using all activated trial license, that is:

>Licenses with non-zero (0) license precedence when multiple trial license of same feature exists.

>When trial license precedence is set to run on top of normal license (set to -1), then cumulative information is calculated considering trial licenses with negative license precedence.

>Additive trial licenses allow seamless dynamic switching to other license, that is, when an additive trial license gets exhausted it would switch to another license provided another license (trial or normal) of the same feature is loaded in the memory.

>Similarly, aggregate trial licenses allow dynamic switching to only exclusive (trial or normal) licenses, that is, when an aggregate trial license gets exhausted it would switch to another license provided another license (trial or normal) of the same feature is loaded in the memory.

Consider a scenario where two licenses of feature name MYTRIAL and feature version 1.0 are loaded by the licensing system. Now, trial usage information for the feature would be calculated as below:

Case 1 - Precedence of License 1 is set higher than License 2 (both greater than 0)

License 1	License 2	Cumulative Usage
Additive Trial	Additive Trial	License 1 + License 2
Additive Trial	Exclusive Trial	License 1 + License 2
Additive Trial	Aggregate Trial	License 1 + License 2
Exclusive Trial	Additive Trial	License 1
Exclusive Trial	Aggregate Trial	License 1
Exclusive Trial	Exclusive Trial	License 1
Aggregate Trial	AggregateTrial	License 1 + License 2
AggregateTrial	Exclusive Trial	License 1 + License 2
AggregateTrial	Additive Trial	License 1
Normal (Additive/Exclusive)	Additive Trial	Error Return
Normal (Additive/Exclusive)	Exclusive Trial	Error Return

Case 2 - Precedence of License 1 is set as -1 and License 2 is set as any positive value

License 1	License 2	Cumulative Usage
Additive Trial	Additive Trial	License 1 + License 2
Additive Trial	Exclusive Trial	License 1 + License 2
Additive Trial	Aggregate Trial	License 1 + License 2
Exclusive Trial	Additive Trial	License 1
Exclusive Trial	Aggregate Trial	License 1
Exclusive Trial	Exclusive Trial	License 1
Aggregate Trial	Aggregate Trial	License 1 + License 2
Aggregate Trial	Additive Trial	License 1
Aggregate Trial	Exclusive Trial	License 1 + License 2
Additive Trial	Normal (Additive/Exclusive/Aggregate)	License 1
Aggregate Trial	Normal (Additive/Exclusive/Aggregate)	License 1
Exclusive Trial	Normal (Additive/Exclusive/Aggregate)	License 1

The feature_index argument should be used in a loop to get information of all the features loaded in the memory till the API returns the VLS_NO_MORE_FEATURES status code. Either a feature_name + feature_version combination, or feature_index can be used to reach a particular feature available.

Returns

The status code LS_SUCCESS is returned, if successful. The other status codes that may be returned are:

Error Code	Description
VLS_NO_MORE_FEATURES	Finished retrieving all the features added.

If an error occurred, one of the following error codes is returned:

Error Code	Description
VLS_APP_UNNAMED	If: >If feature_name is NULL or feature_name contains only NULL character i.e '\0' and feature_index is less than zero >If feature_name is not NULL and version is NULL.
VLS_CALLING_ERROR	Argument specified is not correct, that is, one of the following reasons exist: >If trial_usage_info is NULL. >If feature_name or version buffer size exceeds the maximum size limit specified as VLS_MAXFEALEN and VLS_MAXVERLEN, respectively.
VLS_NO_SUCH_FEATURE	License with specified feature-version combination is not found.
VLS_MULTIPLE_VENDORID_FOUND	This occurs when more than one licenses for the specified Feature/Version is available on the License Manager, but the Vendor ID for all these licenses is different from the client library's Vendor ID.
VLS_RESOURCE_LOCK_FAILURE	Failed to fetch the API resource lock. On receiving this error, retry calling this API.
VLS_NORESOURCES	Error occurred in allocating resources needed by this API.
VLS_NON_TRIAL_LICENSE	This indicates that the specified feature is not a trial license. For ex, if the specified feature node contains a normal license.
VLS_TRIAL_LIC_NOT_ACTIVATED	When the trial license precedence is zero or the trial license persistence data is corrupted.
VLS_TRIAL_LIC_EXHAUSTED	The specified feature has an exhausted trial license.
LS_NO_NETWORK	Generic error indicating that the network is unavailable for servicing the license operation.
VLS_NO_SERVER_RUNNING	License Manager on specified host is not available for processing license operation requests.
VLS_BAD_SERVER_MESSAGE	Message from License Manager could not be understood.

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