VLS_UPDATE \ LSUpdate

Renews the license by sending an update to the License Manager.

Syntax

LS_STATUS_CODE VLS_UPDATE (LS_HANDLE	lshandle);

Argument	Description
lshandle	The handle previously returned by the corresponding request call.

Description

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.

The update call is required only when the automatic license renewal is disabled using the VLSdisableAutoTimer API.

By default, the licensing library defaults to automatic license renewal, wherein application sends an update call after the 80% of the key lifetime has elapsed.

Refer to "License Token Lifetime" under the section "Planning Application Licensing" of the Sentinel RMS SDK Developer Guide for more details.

About LSUpdate

A variant of the VLS_UPDATE function is also available which allows passing additional parameters for specific purposes. Refer to the syntax and parameters below 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 LSUpdate (	 	 
LS_HANDLE	 	lshandle,
unsigned long	 	ulGraceSwitchToNetworkTm,
long	 		*new_units_reqd,
unsigned char	 	*log_comment,
LS_CHALLENGE	 	*challenge );

Argument	Description
lshandle	Same as VLS_UPDATE's lshandle parameter described above.
ulGraceSwitchToNetworkTm	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	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	>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.

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 VLS_UPDATE or LSUpdate 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.