LSUpdate
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