LSUpdate(3nw)


LSUpdate -- verifies that the current handle is still valid

Synopsis

   LS_STATUS_CODE LSUpdate( 
      LS_HANDLE       licenseHandle, 
      LS_ULONG        totUnitsConsumed, 
      LS_ULONG        totUnitsReserved, 
      LS_STR         *logComment, 
      LS_CHALLENGE   *challenge, 
      LS_ULONG       *totUnitsGranted); 

Description

The parameters are as follows:

licenseHandle
(IN) Specifies a handle identifying the license context. This argument must be a handle that was received from a successful call to LSRequest.

totUnits Consumed
(IN) Specifies the total number of units consumed so far in this handle context. The software publisher can specify this policy attribute within the application. LS_DEFAULT_UNITS indicates that the licensing system should determine the appropriate value, using its own licensing policy mechanisms. If an error is returned, the units are not consumed.

totUnitsReserved
(IN) Specifies the number of units to be reserved. If no additional units are required since the initial call to LSRequest, or since the last call to LSUpdate, then this parameter should be the current total as returned in totUnitsGranted from LSRequest. The total units reserved includes units consumed.

logComment
(IN) Points to 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 total number of units granted since the initial license request was 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_BAD HANDLE
licenseHandle did not indicate a currently valid licensing handle.

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_LICENSE_TERMINATED
Re-verification of the existing units failed, so no additional units were requested. An update was not done within the specified update period, and the license units were issued to another user by NLS before this update was attempted.

LS_LICENSE_EXPIRED
Re-verification of the existing units failed due to an out-of-date license certificate. Additional units were not requested.

Notices

The client application periodically issues this call to re-verify that the current license handle is still valid. LSQuery can be used to determine the proper update interval for the current licensing context. A guideline of once an hour might be appropriate, with a minimum interval of 15 minutes. By default, NLS utilizes the minimum time of once every 15 minutes. The software vendor can specify a different interval in the license certificate itself. Any update period specified in the license certificate overrides the default update period.

If the number of new units requested is greater than the number available, then the update request fails with an LS_INSUFFICIENT_UNITS error. On successful completion, LSUpdate returns totUnitsGranted to indicate the current running total of units granted. If totUnitsConsumed exceeds the number of units reserved, then the LS_INSUFFICIENT_UNITS error is returned, and the remaining units are consumed. A challenge response is not returned if an error occurs during the update process.

To successfully update license units, the user associated with the current connection must be security-equivalent to the original creator of the license handle (from LSRequest).


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