LSRequest
Notice:This is preliminary documentation for technology that
will be supported in future releases of
Microsoft Windows.
The LSRequest
function asks that the license system grant the licensing resources so the
calling application can execute.
LS_STATUS_CODE LS_API_ENTRY LSRequest(
|
LS_STR *LicenseSystem, |
// pointer to
string identifying the license system |
|
LS_STR *PublisherName, |
// pointer to
publisher of product requesting licensing resources |
|
LS_STR *ProductName, |
// pointer to name
of product requesting licensing resources |
|
LS_STR *Version, |
// pointer to
version number of product requesting licensing resources |
|
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 |
|
LS_HANDLE *LicenseHandle |
// pointer to
handle to the license context |
|
); |
|
Parameters
LicenseSystem
[in] Points
to a string that uniquely identifies the particular license system. You can
obtain this string by using the LSEnumProviders function. If the constant
LS_ANY is specified, all license system providers will be searched for a
license match.
PublisherName
[in] Points
to a string containing the name of the publisher of the software product
requesting licensing resources. The first 32 characters of the string must be
unique. It is recommended that a company name and trademark be used. This string
cannot be null, nor can it be LS_ANY.
ProductName
[in] Points
to a string containing the name of the software product requesting licensing
resources. The first 32 characters of the string must be unique within the PublisherName
domain. This string cannot be null, nor can it be LS_ANY.
Version
[in] Points
to a string containing the version number of the product. The first 12
characters of the string must be unique within the PublisherName domain.
This string cannot be null, nor can it be LS_ANY.
TotUnitsReserved
[in]
Specifies the number of units required to run the application. The software
publisher may choose to specify this policy attribute within the application.
The recommended value of LS_DEFAULT_UNITS allows the license system to
determine the proper value using information provided by the license system or
the license itself. The license system verifies that the requested number of
units exist and it may reserve those units, but no units are actually consumed
at this time. The number of units available is returned in the TotUnitsGranted
parameter.
LogComment
[in] Points
to an optional string indicating a comment that will be associated 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 in which the total number of units granted is returned.
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 be
greater than or equal to the actual units requested. For example, the license
policy may allow only allow 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.
LicenseHandle
[out] Points
to an LS_HANDLE in which a handle to the license context 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_INSUFFICIENT_UNITS |
The
licensing system cannot locate enough available licensing resources to
complete the request. |
|
LS_SYSTEM_UNAVAILABLE |
A licensing
system cannot be found to perform the function invoked. |
|
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_BAD_ARG |
One or more
of the arguments is incorrect. |
Remarks
Use the LSRequest
function to request licensing resources to authorize the identified product to
execute. If a valid license is found, the challenge response is computed and
LS_SUCCESS is returned. At minimum, the PublisherName, ProductName,
and Version strings are used to identify a matching license or licenses.
Note that an underlying license system service provider may ascertain
additional information for the license request for example, the current user name, computer name,
and so forth.
If all
service providers cannot satisfy a call to the LSRequest function, then LSRequest
returns the handle associated with the last service provider response.
Therefore, regardless of whether valid licensing resources are granted, LSRequest
always returns a valid license handle. This handle must always be released with
the LSFreeHandle
function when the application has finished running. If licensing resources are
granted, the application must also call LSRelease to free the licensing
resources, before calling LSFreeHandle.
A challenge
response is not returned unless the license request completes
successfully that is,
unless it returns a status code of LS_SUCCESS.
If the number
of units requested is greater than the number of units available, the license
request is not granted. Upon successful completion, the value returned in the TotUnitsReserved
parameter indicates the number of units granted. This is greater than or equal
to the number of units requested unless LS_DEFAULT_UNITS was specified. In the
case of failure, the value returned in the TotUnitsGranted parameter is
zero.
See Also