Chapter 1

some function that will later generate an event. Then call SetActive() to indicate that the
request has been issued.
You can deduce from this that an active object can be responsible for only one outstanding
request at a time. You can also deduce that all request functions take a TRequestStatus&
parameter – or, put the other way round, any function you see with a TRequestStatus&
parameter is a request function, which will complete asynchronously and generate an event.
Our GUI program calls this function from HandleCommandL() using
iDelayedHello->Cancel(); // Just in case
iDelayedHello->SetHello(3000000); // 3-second delay
In other words, it cancels any request so that the assertion in SetHello() is guaranteed to
succeed and then requests a delayed info-message to appear after 3 s.
When the timer event occurs, it is handled by the active object framework, as we'll describe
below, and results in RunL() being called:
void CDelayedHello::RunL()
{
iEnv->InfoMsg(R_ACTIVEHELLO_TEXT_HELLO);
}
Clearly, this code is very simple: it's a one-line function that produces an info-message with
the usual greeting text.
Important
The degree of sophistication in an active object's RunL() function can
vary enormously from one active object to another. CONE's
CCoeEnv::RunL() function initiates an extremely sophisticated chain
of processing; we have plenty of evidence for that from the debug
session in Chapter 4. In contrast, the function above was a simple oneliner.
17.1.3 Canceling a Request
If an active object's RunL() calls a leaving function, then that active
object should provide an override of the RunError() function.
If your active object can issue requests, it must also be able to cancel them. CActive
provides a Cancel() function that checks whether a request is active and if so calls
DoCancel() to cancel it. As the implementer of the active object, you have to implement
DoCancel():
void CDelayedHello::DoCancel()
{
iTimer.Cancel();
}
There is no need for any checking here. Because CActive has already checked that a
request is active, there is no need for you to check this or to reset the active flag.
Important
There is an obligation on any class with request functions, to provide