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
);
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.
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. |
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.
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in lsapi.h.
Import Library: Use lsapi32.lib.
License Service Application Programming Interface Overview, LSAPI Functions, LS_CHALLENGE, LSEnumProviders, LSFreeHandle, LSGetMessage, LSRelease