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 initialize 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.