LSRequest

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)

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.