This document describes the use of the CActive class
to implement asynchronous services and requests.
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.