Using CActive

 

--------------------------------------------------------------------------------

 

Writing derived classes

A CActive-derived class must fulfil a number of requirements, including providing a constructor and a number of functions.

 

To write a class which encapsulates an asynchronous service:

 

define and implement a C++ constructor through which the priority of the active object can be specified. A typical implementation calls the CActive constructor through a constructor initialization list.

 

define data members representing the asynchronous service provider; the number and meaning of these members depends on the services offered by the service provider

 

define and implement a second-phase ConstructL() member function, if this is necessary to initialise contact with the asynchronous service provider.

 

define and implement a DoCancel() member function to handle a cancel request to the service provider. This function is defined as pure virtual in CActive and any class derived from CActive must define and implement it.

 

define and implement one or more service request functions which forward requests to the service provider

 

To write a class which handles the completion of an asynchronous request, a RunL() function should be provided. The function is defined as pure virtual in CActive and any class derived from CActive must define and implement it. RunL():

 

handles completion of a request, if appropriate

 

if appropriate, renews the request, or initiates other requests, or decides to terminate the series of requests handled by the active object

 

In some cases, a derived-class's RunL() will do some pre-handling of the request, and then invoke one or more appropriate virtual functions to handle particular types of completion. A further-derived class must provide virtual functions to specify the way various types of completion are handled.

 

In the general case, the derivation of a concrete active object from the CActive base class may involve

 

a derivation for encapsulating the service

 

a derivation for encapsulating the abstract handling of completion

 

further derivations for making that handling more concrete

 

Depending on the circumstances, some of these stages of derivation may be amalgamated into one stage; or stages may be refined into even finer derivation stages.