VLSupdateExt

Syntax

LS_STATUS_CODE VLSupdateExt (LS_HANDLE           lshandle,
                             unsigned long       ulGraceSwitchToNetworkTm,
                             long                *new_units_reqd,
                             unsigned char       *log_comment,
                             LS_CHALLENGE        *challenge
                             VLSserverInfo       *serverInfo );

Argument	Data Type	Direction	Description
lshandle	LS_HANDLE	IN	The handle previously returned by the corresponding request call.
ulGraceSwitchToNetworkTm	unsigned long	IN	Unused till version 8.3.x. Since version 8.4.0, this parameter allows switching from a grace license to a network license . Accordingly, the parameter can have the following values: >A numeric value between 1 to 54,000, which is the time in seconds. After this time interval, the application looks for a license token on network. >VLS_GRACE_REMAIN_ON_NONET: When you do not want to allow switching from a grace license to network license (functionality so far and also the default setting). >LS_DEFAULT_UNITS: Sets the value of ulGraceSwitchToNetwork to 10 minutes.
new_units_reqd	long	IN/OUT	Unused till version 9.1.x. Since v9.2.0, it represents the number of license units that can be obtained from the License Manager while renewing the license. >If the License Manager has sufficient units to renew as per the refresh call, it will reclaim/release initial requested units and grant new units. In this case, two implicit entries for release and request are created in the usage log. >If the number of license units available with the License Manager is less than the required number, the LSUpdate call renews the existing number of units only (if any set using the LSRequest call). The value of new_units_reqd is updated with actual tokens requested/granted. Also, the last_status (a field of the lshandle structure) is updated to reflect the reason for failure. Use the VLSgetLastErrorStatusFromHandle API to view the view the last error status. >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	unsigned char	IN	>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	LS_CHALLENGE	OUT	The challenge structure.
serverInfo	VLSserverInfo	IN/OUT	This information is passed to the License Manager for use in License Manager hook functions. An IN\OUT parameter.

Description

An advanced variant of VLS_UPDATE \ LSUpdate that additionally returns the License Manager information during license update.

Once a license is obtained, the client must periodically renew its license and inform the License Manager that it is alive by calling the update call. However, this task can be performed by VLS_UPDATE \ LSUpdate alone. So, use of VLSupdateExt is recommended when custom License Manager hook functions are implemented by vendor to obtain License Manager information during license update (pre/post) events.

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 a queued handle. Cannot use VLSupdateExt to update a queued handle. >challenge argument is non-NULL, but cannot be understood. >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_NO_LICENSE_GIVEN	Generic error indicating that license was not updated.
LS_LICENSETERMINATED	Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed.
VLS_NO_SUCH_FEATURE	License Manager does not have license that matches requested feature, version and capacity.
LS_NOLICENSESAVAILABLE	All licenses in use.
LS_LICENSE_EXPIRED	License has expired.
VLS_TRIAL_LIC_ EXHAUSTED	Trial license expired or trial license usage exhausted.
VLS_FINGERPRINT_ MISMATCH	Client-locked; locking criteria does not match.
VLS_APP_NODE_LOCKED	Feature is node locked, but the update request was issued from an unauthorized machine.
VLS_CLK_TAMP_FOUND	License Manager has determined that the client’s system clock 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_INVALID_DOMAIN	The domain of the License Manager is different from that of client.
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_BAD_SERVER_ MESSAGE	Message returned by 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_RESOURCE_LOCK_FAILURE	Failed to fetch the API resource lock. On receiving this error, retry calling this API.
LS_BADHANDLE	The system is low on memory or is in unstable state.

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

VLSupdateExt

Syntax

Description

Returns

See Also