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.