LSRequest(3nw)
LSRequest --
requests licensing resources associated with a specific software product
Synopsis
LS_STATUS_CODE LSRequest(
LS_STR
licenseSystem,
LS_STR
publisherName,
LS_STR
productName,
LS_STR
version,
LS_ULONG totUnitsReserved,
LS_STR logComment,
LS_CHALLENGE
challenge,
LS_ULONG
totUnitsGranted,
LS_HANDLE
licenseHandle);
Description
The parameters are as follows:
- licenseSystem
-
(IN) Points to a string (from LSEnumProviders) that uniquely identifies a specific licensing system. LS_ANY indicates a match against all installed licensing
systems.
- publisherName
-
(IN) Points to the name of the publisher (manufacturer) of this product. This string must not be NULL and must be unique in the first 32 characters. A company name and trademark
should be used to guarantee uniqueness.
- productName
-
(IN) Points to the name of the product requesting license units. This string must not be NULL and must be unique in the first 32 characters in the publisherName domain.
- version
-
(IN) Points to the version number of this product. This string must be unique in the first 12 characters in the productName domain. This string must not be NULL.
- totUnitsReserved
-
(IN) Specifies the number of units required to run the application. The software publisher can specify this policy attribute within the application. LS_DEFAULT_UNITS
lets the licensing system determine the number of units using information provided by the licensing system or the license certificate. NLS verifies that the requested number of
units exist and can reserve those units, but no units are actually consumed at this time. The number of units available is returned in totUnitsGranted.
- logComment
-
(IN) Specifies an optional string indicating a comment to be associated with the request and logged by NLS. The comment is logged even if an error is returned. To avoid logging
the comment, specify LS_NULL.
- challenge
-
(IN/OUT) On input, points to a challenge structure (LS_NULL if no challenge mechanism is desired). On output, points to the response to the challenge.
- totUnitsGranted
-
(OUT) Points to the LS_ULONG where the total number of units granted is returned.
- licenseHandle
-
(OUT) Points to the LS_HANDLE where a handle to the license context is returned.
Return values
This function returns a detailed error code that can be directly processed by the caller, or that can be converted by LSGetMessage to one of these message strings:
- LS_SUCCESS
-
The requested functionality completed successfully.
- LS_SYSTEM_UNAVAILABLE
-
DOS TSR or Windows DLL is not properly configured or available, or client has no licensing system to communicate with.
- LS_RESOURCES_UNAVAILABLE
-
Insufficient resources (such as memory) available to complete request.
- LS_AUTHORIZATION_UNAVAILABLE
-
Current user was not security-equivalent to the original creator of the licensing handle.
- LS_BAD_ARG
-
One or more parameters are invalid.
- LS_INSUFFICIENT_UNITS
-
Licensing system could not find enough installed license units to satisfy the request at this time.
- LS_LICENSE_UNAVAILABLE
-
Not enough license units are available to fulfill the request, but there are enough units installed to fulfill the request.
- LS_NETWORK_UNAVAILABLE
-
The network is currently unavailable.
Notices
If a valid license certificate is found and the challenge mechanism is used, the challenge response is computed and LS_SUCCESS is returned. At a minimum, the
publisherName, productName, and version strings are used to identify matching license certificates.
For an LSRequest to be able to access a license certificate, the distinguished name (DN) associated with the client's connection must be security-equivalent to at least
one of the assignments listed in the license certificate. If no assignments are listed, and the policy of the license certificate allows this, the license certificate can be
accessed by anyone. NLS also determines user and machine information based on the NCP connection and the associated NDS information, and determines whether license units can be
granted or not based on this information. Only license units that are accessible to the user are returned by this function.
The application should always call LSFreeHandle to release the memory associated with the specified handle. If license units are granted, the application must call
LSRelease to release the granted units before LSFreeHandle is called.
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.