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 |
|
); |
If the TotUnitsConsumed exceeds the number of units reserved, the error
LS_INSUFFICIENT_UNITS is returned and the remaining units are consumed.
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.
|
TotUnitsReserved | ||
|
Status code returned |
LS_DEFAULT_UNITS |
Other (specific count) |
|
LS_SUCCESS |
(A) |
(C) |
|
LS_INSUFFICIENT_UNITS |
(B) |
(D) |
|
Other errors |
(E) |
(E) |
(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.
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. |
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.