TLicenseUse is an abstract base class and cannot be instantiated. Each licensed product instantiates an object of the developer's TLicenseUse derived class.
Time modalities
The primary function of the Licensing Service is to check for a valid license for a licensed product. For the product to initiate the check, it must create an object of its TLicenseUse derived class, perform optional set up, and then call the object's Check() member function. For an example of this procedure, see "Developer cookbook" on page 128. The check either succeeds in finding available licensing units for the product or fails with an exception.
Instantiation of the TLicenseUse object only declares the intent to perform licensing operations; however, instantiation does not actually acquire licensing units. The acquisition occurs only when Check() is called. This structure allows the licensed product to perform all initialization in a single part of its code (instantiation), while retaining flexibility over which parts of its code (checks) require licensing units.
Licensing units must be released by destroying the TLicenseUse object when the licensed product has finished with the units. The successful acquisition of licensing units is not the end of the licensing process
In many situations, the licensed product must actively deal with the duration of the time period during which the product is executed. For example, the license activation key that provided the licensing units might have an expiration date. In this case, the licensed product must reissue Check() periodically to determine whether the licensing units have expired.
Assigned units can also expire in the following situations, and periodic checking is required:
In a license activation key provided for demonstration purposes, Cool Software could specify a total of 1000 consumable units. This would allow their CAD product to be used for a total of 500 minutes before all of the units were exhausted and the user had to decide whether to purchase the licensed product.
In a purchased key, Cool Software could specify a total of 100 recyclable units, allowing unlimited simultaneous use of up to 10 copies of CoolSoftCAD. Because the units are recyclable, they will never be used up; however, each copy of the licensed product temporarily removes 10 units from the available pool. For a preferred customer, Cool Software could sell 200 recyclable units (for the same price they charge regular customers for 100 recyclable units), allowing unlimited usage by up to 20 simultaneous copies of their licensed product.
For example, the license activation key can specify that simultaneous usage of multiple copies of a licensed product by a single user can be handled in a variety of ways. The licensing server can debit the pool of available units:
Check performs the maintenance operations required to ensure that the TLicenseUse object controls a positive number of valid licensing units. When the product's licensing units have been depleted through consumption, Check contacts the license provider and requests more licensing units for the product to consume.
If the licensing units are consumable, the license provider decrements its available licensing units for the product with each request. If the licensing units are recyclable, the license provider decrements its available licensing units on the first request; at each subsequent request the license provider reissues the same licensing units to the product. If the product cannot be licensed, Check throws a TLicenseException that identifies the reason for the failure. For more information on license exceptions, see "Licensing exceptions" on page 162.
SelectProvider allows the licensed product to affect the order in which providers are searched by the 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 list and use it to set the selection argument. If no applicable providers are present in the list, the product throws a TLicenseNoAcceptableProvider exception that describes the error. Once a provider is selected by the product, its entry is removed from the list of providers for subsequent transactions. The default implementation processes the collection in arbitrary order.
GetOperations is a pure virtual function the implementation of which is supplied by the derived class of TLicenseUse. This function is passed a TLicenseProduct reference that identifies the license provider currently under consideration. Based upon the license provider, the licensed product can construct a set of operations for the license provider to execute. If the provider can satisfy the license request, it executes as many of the operations as possible to satisfy the calling product's need for authentication. For more information on TProviderOperation and its uses, see "Provider operation mechanism" on page 154.
The storage for the collection of operations belongs to the base TLicenseUse class. There is no guarantee that the operations added to the collection in the call to GetOperations are ever made available to AcceptOperationsResults; therefore, the collection assumes responsibility for the storage of the individual operations, and they should be allocated from the heap.
AcceptOperationsResults is a pure virtual function implemented by the derived class of TLicenseUse. This function is called with the set of TProviderOperation objects resulting from a successful license request. The AcceptOperationsResults function allows the licensed product to evaluate the responses to the requested operations. If the operations were not executed to the product's satisfaction, the AcceptOperationsResults implementation throws a specialized TLicenseException derived class that describes the error. For more information on license exceptions, see "Licensing exceptions" on page 162.
ReportException is a function that provides default reporting of license request failures that prevent the product from being licensed. The default reporting capability includes logging the exception and reporting to the user through a dialog. The product can override this behavior by implementing its own ReportException member in its TLicenseUse derived class.
If the product cannot be licensed, ReportException throws a TLicenseDeniedException.
SetRequestSize sets the number of licensing units that the TLicenseUse object allocates in each transaction with the license provider. SetRequestSize and SetConsumptionRate combine to determine the frequency of communication with the license provider, and typically the licensing server. If the request size is 10 units and the rate of consumption is 60 seconds per unit, then the TLicenseUse object is required to interact with the license provider approximately once every 10 minutes. Communication with the license provider incurs some overhead; therefore, set the request size to a value that limits contact with the license provider to once every 5+ minutes. The default request size is 1.
SetConsumptionRate sets the number of seconds that the licensed product can be used for every licensing unit. This member function and SetRequestSize combine to regulate the frequency of communication with the license provider. For more information on regulating the frequency of contact with the license provider, see "SetRequestSize." The default consumption rate is 5 minutes per licensing unit. If the consumption rate is set to a value less than or equal to 0, a TLicenseUsageException results.
GetNumberOfUnits returns the number of licensing units available to the licensed product.
GetRequestSize gets the currently configured licensing unit request size.
GetConsumptionRate gets the currently configured licensing unit consumption rate.
GetProduct gets the TLicenseProduct component of the TLicenseUse object. This object represents the licensed product.
ExecuteOperations allows the licensed product, via its derived class of TLicenseUse, to interact with a selected provider at any time during which the provider remains selected. ExecuteOperations is thus "out-of-band" with respect to the usual flow of control initiated by calling Check. The product passes this function a set of operations for the license provider to execute. TLicenseUse forwards this set on to the provider's session. The session executes as many of the operations as possible.
NOTE
Calling ExecuteOperations without having already selected a provider results in the exception TLicenseUsageException(kNoProviderSelected) being thrown. In addition, if the selected provider does not choose to support ExecuteOperations, the exception TLicenseUsageException(kSubclassDidNotExecuteOperations) is thrown. For more information on TProviderOperation and its uses, see "TProviderOperation" on page 155.
ProviderHasCreatedSession notifies the licensed product as soon as possible that the specified provider has successfully created a session (an instance of the selected provider's derived class of TLicenseProviderSession). This allows the product to initiate provider-specific configuration via ExecuteOperations before Check asks the session to allocate licensing units. This functionality is most useful with legacy providers that require information not otherwise available during the Check.
Licensing unit
acquisition and
release
Elapsed time
Recyclable and consumable licensing units
Licensing units can be either recyclable or consumable.
Recyclable units are only temporarily reserved for a product when a licensed product performs a Check().
To see the difference between the two types of units, assume that CoolSoftCAD acquires 10 units, each good for 30 seconds, in the following situations:
Consumable units are permanently removed from the pool of available units controlled by the license activation key. If the units are consumable on a time basis, a periodic Check() must be issued to perform the actual consumption of the units.
Placing business
terms in license activation keys
Business terms are specified in license activation keys; not in the licensed product code. Therefore, as the following CoolSoftCAD example shows, decisions about licensing policy and business terms can be deferred from the product development cycle to the time when the product is shipped or purchased.
class TLicenseUse : public MCollectible {
// Copyright (C) 1995 Taligent, Inc. All rights reserved.
public:
//.................................................................
// destructor
virtual ~TLicenseUse();
//.................................................................
// TLicenseUse specific operations.
virtual void SetRequestSize (const TLicenseUnit count);
virtual void SetConsumptionRate(const TTime& timePerUnit);
virtual void GetNumberOfUnits(TLicenseUnit& target) const;
virtual void GetRequestSize (TLicenseUnit& target) const;
virtual void GetConsumptionRate(TTime& target) const;
virtual void GetProduct (TLicenseProduct& theProduct) const;
virtual void Check ();
protected:
//.................................................................
// Constructors and restricted operations for abstract class.
TLicenseUse ();
TLicenseUse (const TLicenseProduct& theProduct);
virtual void SelectProvider (TLicenseProduct& selection,
const TCollectionOf<TLicenseProduct>& providers);
virtual void ProviderHasCreatedSession (const TLicenseProduct& theProviderProduct);
virtual void GetOperations (const TLicenseProduct& theProviderProduct,
TCollectionOf<TProviderOperation>& theOperations) = 0;
virtual void AcceptOperationsResults(const TLicenseProduct& theProviderProduct,
const TCollectionOf<TProviderOperation>& theOperations) = 0;
virtual void ExecuteOperations(TCollectionOf<TProviderOperation>& theOperations)
virtual void ReportException (const TStandardException& exception);
private:
};
Basic member
functions
There is a minimal set of basic member functions that a licensed product must call to use the Licensing framework. For examples in which these member functions are coded, see "Developer cookbook" on page 128 and "Example licensed product implementation" on page 129. Extended member functions
The extended member functions allow a licensed product to access more sophisticated functionality of the Licensing framework.
This member function serves as a structured extension mechanism for the interaction between a licensed product and a particular provider. Currently, no extensions are directly supported by the Licensing framework. Concurrency
TLicenseUse is not designed for concurrent access.
[Contents]
[Previous]
[Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Generated with WebMaker