Using CActiveClass

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.