Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.
The LSUpdate function updates the synchronization between the licensed application software and the license system.
LS_STATUS_CODE LS_API_ENTRY LSUpdate(
| LS_HANDLE LicenseHandle, | // handle to the license context |
| LS_ULONG TotUnitsConsumed, | // units consumed in this handle context |
| LS_ULONG TotUnitsReserved, | // units required to run the application |
| LS_STR *LogComment, | // pointer to optional comment associated with the request |
| LS_CHALLENGE *Challenge, | // pointer to a challenge structure |
| LS_ULONG *TotUnitsGranted | // pointer to total number of units granted |
| ); |
Parameters
LicenseHandle
[in] Specifies the handle to the license context. This parameter must be a handle created with the LSRequest function.
TotUnitsConsumed
[in] Specifies the total number of units consumed in this handle context since the initial call to the LSRequest function. You can specify this license policy attribute within the application. A value of LS_DEFAULT_UNITS indicates that the license system should determine the appropriate value using its own license policy mechanisms. If an error is returned, no units are consumed.
If the TotUnitsConsumed exceeds the number of units reserved, the error LS_INSUFFICIENT_UNITS is returned and the remaining units are consumed.
TotUnitsReserved
[in] Specifies the total number of units to be reserved. If no additional units are required since the initial call to the LSRequest function or the last call to the LSUpdate function, then this parameter should be the current total returned in the TotUnitsGranted parameter. The total reserved includes the units consumed. That is, if an application requests 100 units, and then consumes 20 units, there are still 100 units reserved but only 80 available for consumption.
If additional units are required, the application must calculate a new total for TotUnitsReserved. You can specify the constant LS_DEFAULT_UNITS, but this does not allocate any additional units.
The license system verifies that the requested number of units exist, and it may reserve those units, but these units are not consumed at this time. This value may be smaller than the original number requested by LSRequest to indicate that fewer units are needed than originally anticipated.
LogComment
[in] Points to an optional string indicating a comment that the license system will associate with the request. The license system can log the comment if logging is supported and enabled. If an error is returned, the license system can log both the error and the comment, but this is not guaranteed. If you do not specify a string, the value must be LS_NULL.
Challenge
[in/out] Points to a challenge structure. The challenge response will also be returned in this structure.
TotUnitsGranted
[out] Points to an LS_ULONG value that returns the total number of units granted since the initial license request. The following table describes the TotUnitsGranted return value, given the TotUnitsReserved parameter input value, and the status code returned:
| TotUnitsReserved | |||||||||||||||||||||||||
| Status code returned | LS_DEFAULT_UNITS | Other (specific count) | |||||||||||||||||||||||
| LS_SUCCESS | (A) | (C) | |||||||||||||||||||||||
| LS_INSUFFICIENT_UNITS | (B) | (D) | |||||||||||||||||||||||
| Other errors | (E) | (E) | |||||||||||||||||||||||
TotUnitsGranted return values:
(A) The default number of units commensurate with the license granted.
(B) The maximum number of units available to the requesting software. This can be less than the normal default.
(C) The number of units used to grant the request. This value can differ from the actual units requested. For example, the license policy may only allow only increments of five units; therefore, a request of seven units would result in a grant of 10 units.
(D) The maximum number of units available to the requesting software. This can be more or less than the units requested.
(E) Zero is returned.
Return Values
If the function succeeds, the return value is LS_SUCCESS.
If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:
| Value | Meaning |
| LS_BAD_HANDLE | The handle used on the call does not describe a valid licensing system context. |
| LS_INSUFFICIENT_UNITS | The licensing system cannot locate enough available licensing resources to complete the request. |
| LS_LICENSE_TERMINATED | The licensing system has determined that the resources used to satisfy a previous request are no longer granted to the calling software. |
| LS_AUTHORIZATION_UNAVAILABLE | The licensing system has no licensing resources to complete the request. |
| LS_LICENSE_UNAVAILABLE | The licensing system has licensing resources that could satisfy the request, but they are not available at the time of the request. |
| LS_RESOURCES_UNAVAILABLE | The request cannot be completed because of insufficient resources, such as memory. |
| LS_NETWORK_UNAVAILABLE | The network is unavailable. |
| LS_LICENSE_EXPIRED | The license associated with the current context has expired. This may be due to a time-restriction on the license. |
| LS_BAD_ARG | One or more of the arguments is incorrect. |
Remarks
Your application should periodically call the LSUpdate function to verify that the current license is still valid. The application can use the LSQuery function to determine the proper time interval for the current licensing context. A guideline of once an hour may be appropriate, with a minimum interval of 15 minutes. Consult your license system vendor for more information.
The LSUpdate function verifies that the license system context has not changed from the one expected by the licensed software. The LSUpdate function can determine if the licensing resources granted to the specified handle are still reserved for this application. In a distributed license system, an error might indicate a temporary network interruption. It can also determine if the license system has released the licensing resources granted to the specified handle. An error indicates the software no longer has authorization to execute in a typical manner.
The call to the LSUpdate function can also indicate that the current licensing context has expired. For example, in the case of a time-restricted license policy, it returns the warning status LS_LICENSE_EXPIRED.
If the number of new units requested in the TotUnitsReserved parameter is greater than the number available, then the update request fails and it returns the error LS_INSUFFICIENT_UNITS.
If the call completes successfully, the value returned in the TotUnitsGranted parameter indicates the current total of units granted.
If LSUpdate returns an error, it does not return a challenge response. Application software should be prepared to handle vendor-specific error conditions if they arise. If any error is returned, a call to the LSRelease function is still required.
See Also