NLSGetTransaction(3nw)


NLSGetTransaction -- retrieves a single transaction record

Synopsis

   LS_STATUS_CODE NLSGetTransaction( 
      LS_STR      *licenseSystem, 
      LS_STR      *publisher, 
      LS_STR      *product, 
      LS_STR      *version, 
      LS_STR      *userName 
      LS_ULONG     maxStrLen, 
      LS_HANDLE   *transactionHandle, 
      LS_STR      *transactionPublisher, 
      LS_STR      *transactionProduct, 
      LS_STR      *transactionVersion, 
      LS_STR      *transactionUserName, 
      LS_ULONG    *index); 

Description

The parameters are as follows:

licenseSystem
(IN) Points to the licensing system to receive transaction entries from. Specify a specific licensing system name as received from LSEnumProviders, or specify LS_ANY to initiate a search for the first matching certificate.

publisher
(IN) Points to the publisher name to filter by. Only transactions that have this publisher name are returned. LS_ANY indicates that transactions will not be filtered by publisher.

product
(IN) Points to the product name to filter by. Only transactions that have this product name are returned. LS_ANY indicates that transactions will not be filtered by product.

version
(IN) Points to the version string to filter by. Only transactions that have this version string are returned. LS_ANY indicates that transactions will not be filtered by version.

userName
(IN) Points to the user/object name to filter by. Only transactions that have this user/object name are returned. LS_ANY indicates that transactions will not be filtered by user/object.

maxStrLen
(IN) Specifies the maximum length (in bytes) of string output that can be placed into transactionPublisher, transactionProduct, and transactionVersion. If any of these output strings is longer than maxStrLen, LS_BUFFER_TOO_SMALL is returned.

transactionHandle
(OUT) Points to the handle for the transaction. The individual entries for the overall transaction can then be obtained by calling NLSGetEntry with this handle. The handle is only valid when LS_SUCCESS is returned.

transactionPublisher
(OUT) Points to the name of the publisher for this transaction. This name applies to all entries in the returned transaction.

transactionProduct
(OUT) Points to the name of the product for this transaction. This name applies to all entries in the returned transaction.

transactionVersion
(OUT) Points to the version string for this transaction. This version string applies to all entries in the returned transaction.

transactionUserName
(OUT) Points to the user/object name that was responsible for initiating this transaction. This name applies to all entries in the returned transaction.

index
(IN/OUT) Used to iterate through the entire list of transactions. index should be initialized to zero on the first call to the function, then opaquely passed back into the function on successive calls. To retrieve all information, continue this process until LS_BAD_INDEX 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_BAD_ARG
One or more parameters are invalid.

LS_BUFFER_TOO_SMALL
The maxStrLen parameter did not indicate a buffer large enough to hold one of the requested output parameters.

LS_AUTHORIZATION_UNAVAILABLE
Specified license certificate could not be located, or you do not have privileges to delete this license certificate.

LS_BAD INDEX
There are no more entries after the specified index.

Notices

NLSGetTransaction retrieves a single transaction record based on the filtering licenseSystem, publisher, product, version, and userName. This single transaction describes all of the individual calls a single licensed application made, including errors generated, from the initial call to LSRequest through the call to LSFreeHandle. It also includes license certificate installation and deletion.

The transaction handle is a one-for-one mapping with the license handle. The individual entries can be accessed with NLSGetEntry.


30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.