Class: TLicenseUse

Declaration: LicenseUse.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

The core of the Licensing framework, this class contains all of the base-level primitives that are needed for license verification. A TLicenseUse derived class must be implemented by each developer of a licensed product. This allows the licensed product to provide product-specific behavior and override the standard TLicenseUse member functions for customization. TLicenseUse facilitates the complex interactions between the license product and the Licensing framework. These interactions are necessary for prioritization among the license providers and for challenge negotiation.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

All Licensed products need to provide a derived class of TLicenseUse. Each derived class must supply an implementation for the GetOperations and AcceptOperationsResults member functions. You can override SelectProvider to change the default prioritization scheme for selecting among multiple available license providers at an end-user site. Because TLicenseUse has insufficient information to interact directly with the user, it is recommended that the derived class override ReportException. ProviderHasCreatedSession can be overridden to allow the licensed product to know the earliest point at which it can use ExecuteOperations to invoke provider-specific operations.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLicenseUse::~TLicenseUse

virtual ~ TLicenseUse ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object. Also releases any unused license units back to the provider.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::SetRequestSize

virtual void SetRequestSize (const TLicenseUnit count)

Interface Category:

API.

Purpose:

Sets the number of license units that this TLicenseUse object allocates in each transaction with the license provider. SetRequestSize and SetConsumptionRate are combined to determine the frequency of communication with the license provider. If the request size is 10 units and the rate of consumption is 60sec/unit, then the TLicenseUse object is required to interact with the license provider on the order of once every 10 minutes. It is probably safe to assume that communication with the license provider will be a relatively expensive operation, therefore, it is suggested that the request size be set to a value that will limit contact with the license provider to once every 5+ minutes. The default request size is 1.

Calling Context:

Called by the product.

Parameters:

const TLicenseUnit count -The number of licensing units.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::SetConsumptionRate

virtual void SetConsumptionRate (const TTime & timePerUnit)

Interface Category:

API.

Purpose:

Sets the number of seconds that the product can be used for every license unit. This member function and SetRequestSize are combined to regulate the frequency of communication with the license provider. If the request size is 10 units and the rate of consumption is 60sec/unit, then the TLicenseUse object is required to interact with the license provider on the order of once every 10 minutes. It is probably safe to assume that communication with the license provider will be a relatively expensive operation, therefore, it is suggested that the request size be set to a value that will limit contact with the license provider to once every 5+ minutes. The default consumption rate is 5 minutes per license unit.

Calling Context:

Called by the product.

Parameters:

const TTime & timePerUnit -The number of seconds per licensing unit.

Return Value:

None.

Exceptions:

Throws TLicenseUsageException if the consumption rate is set to a value that is less than or equal to zero.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::GetNumberOfUnits

virtual void GetNumberOfUnits (TLicenseUnit & target) const

Interface Category:

API.

Purpose:

Gets the number of license units that are still available to the product.

Calling Context:

Called by the product.

Parameters:

TLicenseUnit &target -Sets the number of license units here.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::GetProduct

virtual void GetProduct (TLicenseProduct & theProduct) const

Interface Category:

API.

Purpose:

Gets the TLicenseProduct object that describes the licensed product.

Calling Context:

Called directly to get product information.

Parameters:

TLicenseProduct & theProduct -The storage where the product object is copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::Check

virtual void Check ()

Interface Category:

API.

Purpose:

Performs the maintenance operations that are required to ensure that the TLicenseUse object contains a positive number of valid license units. When the product's license units have been depleted through consumption, Check contacts the license provider and requests more license units for the product to consume. If the license units are truly consumable, the license provider decrements its available license units for the product with each request. If the license units are recyclable, the license provider decrements its available license units on the first request, and on each subsequent request the license provider simply reissues the same license units to the product. It is the responsibility of the licensed product to call the Check function frequently to allow license rights verification to occur. Check returns void and must throw an exception to signal that an error has occurred.

Calling Context:

Called by the product to check license rights.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TLicenseDeniedException if the product is not licensed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::TLicenseUse

TLicenseUse ()
TLicenseUse (const TLicenseProduct & aProduct)

Interface Category:

API.

Purpose:

Default constructor.
Constructs and initializes.

Calling Context:

Called by the stream-in operators.
Called by the product's constructors.

Parameters:

Takes no parameters.
const TLicenseProduct & aProduct -The product to license.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::SelectProvider

virtual void SelectProvider (TLicenseProduct & selection, const TCollectionOf < TLicenseProduct

& providers)

Interface Category:

API.

Purpose:

Allows the product to affect the order in which providers are searched by the Licensing framework. SelectProvider is called with a collection of TLicenseProduct objects that identify all of the license providers available to the product. The product should select one provider from the collection and use it to set the selection argument. If no acceptable providers are present in the collection, the product throws a TLicenseNoAcceptableProviders exception. Once a provider is selected by the product, its entry is removed from the collection of providers for subsequent transactions. The default implementation processes the collection in a deterministic but arbitrary order.

Calling Context:

Called by the Licensing framework.

Parameters:

TLicenseProduct & selection -The storage where the selected provider is copied.
const TCollectionOf < TLicenseProduct > & providers -The collection of possible providers.

Return Value:

None.

Exceptions:

Throws TStandardLicenseNoAcceptableProviders if the collection is empty.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::GetOperations

virtual void GetOperations (const TLicenseProduct& theProviderProduct, TCollectionOf < TProviderOperation > & theOperations)

Interface Category:

API.

Purpose:

A pure virtual function whose implementation is supplied by the derived class of TLicenseUse. This function is passed a TLicenseProduct that identifies the license provider currently under consideration. Based upon the license provider, the product can construct a set of operations for the license provider to execute. In the event that the provider can satisfy the license request, it executes as many of the operations as possible in an effort to satisfy the calling product's need for authentication.

Calling Context:

Called by the Licensing framework.

Parameters:

const TLicenseProduct & theProviderProduct -The provider product.
TCollectionOf < TProviderOperation > & theOperations -The collection where operations are to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The operations added to the collection are adopted by the collection, and not copied, therefore they should not be allocated from the stack frame of GetOperations.

Member Function: TLicenseUse::AcceptOperationsResults

virtual void AcceptOperationsResults (const TLicenseProduct& theProviderProduct, const TCollectionOf <TProviderOperation >& theOperations)

Interface Category:

API.

Purpose:

A pure virtual function whose implementation is supplied by the derived class of TLicenseUse. This function is called with the set of TProviderOperation objects resulting from a successful license request. AcceptOperationsResults gives the product an opportunity to evaluate the responses to the requested operations. If the operations were not executed to the product's satisfaction, AcceptOperationsResults throws a TLicenseException.

Calling Context:

Called by the Licensing framework.

Parameters:

const TLicenseProduct & theProviderProduct -The provider product.
const TCollectionOf < TProviderOperation > & theOperations -The collection of operations that have been executed by the provider.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::ReportException

virtual void ReportException (const TStandardException & exception)

Interface Category:

API.

Purpose:

Provides default reporting of licensing errors that prevent the product from being licensed. Because the TLicenseUse is unaware of the TLocale, the base class implementation of this member function cannot interact with the user. For this reason, the derived class should normally override this member function. The final action of the base class member function is to rethrow the passed exception.

Calling Context:

Called by the Licensing framework.

Parameters:

const TStandardException & exception -The exception that was thrown. If this exception is a TLicenseDenied object, further information is available by iterating over the object's collected exceptions.

Return Value:

None.

Exceptions:

Throws TLicenseDeniedException if the product cannot be licensed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::GetConsumptionRate

virtual void GetConsumptionRate (TTime & target) const

Interface Category:

API.

Purpose:

Gets the consumption rate associated with a TLicenseUse object.

Calling Context:

Called by the Licensing framework during the license consumption calculation.

Parameters:

TTime & target -The number of seconds per unit.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::GetRequestSize

virtual void GetRequestSize (TLicenseUnit & target) const

Interface Category:

API.

Purpose:

Gets the number of units requested by the Licensing framework on each license allocation.

Calling Context:

Called by the License framework.

Parameters:

TLicenseUnit & target -The storage where the number of units is copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::ExecuteOperations

virtual void ExecuteOperations (TCollectionOf < TProviderOperation > & theOperations)

Interface Category:

API.

Purpose:

This can be used to invoke provider-specific operations of the licensed product's choosing. It is up to each provider as to whether, and what, provider-specific operations it supports.

Calling Context:

Determined by client code.

Parameters:

TCollectionOf < TProviderOperation > & theOperations -A collection of operations that the licensed product wishes the selected provider to execute. Because these are provider specific, the product must construct an appropriate collection for each license provider.

Return Value:

None.

Exceptions:

Throws TLicenseUsageException with kNoProviderSelected if no session has been established. Throws TLicenseUsageException with kSubclassDidNotExecuteOperations if the selected provider does not support provider-specific operations, indicating either a coding error on the part of the licensed product or a change of semantics on the part of the provider.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLicenseUse::ProviderHasCreatedSession

virtual void ProviderHasCreatedSession (const TLicenseProduct & theProviderProduct)

Interface Category:

API.

Purpose:

A virtual function that can be overridden by clients to recognize the earliest possible time for invoking provider-specific operations. This informs a client when the Licensing framework selects a provider.

Calling Context:

Called by Licensing framework after both SelectProvider and CreateSession return and successfully create a session.

Parameters:

const TLicenseProduct & theProviderProduct -The product that was selected to be the license provider.

Return Value:

None.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.