Using TRequestStatus

This document describes the use of TRequestStatus objects to hold the completion status of an asynchronous request.

A request status object is used to carry the completion status of an asynchronous request.

Typically, an asynchronous request is made by an active object, an instance of a CActive derived class, to a service provider. When an asynchronous request completes, the service provider stores a completion code in the request status object and signals the caller’s thread. When the active object handles the completed request, it can check the completion code.

Note that the request status object is the data member: CActive::iStatus of the CActive base class.

class CMyActive : public CActive
 {
 void RunL();
 void IssueRequest();
 ...
 RTimer         iTimer;
 }

The active object does not need to initialize the request status object in any way; it simply passes it to the service provider’s request function when making the request. The service provider is responsible for changing the completion code; in particular it sets the code to KRequestPending before initiating the request. For example:

void CMyActive::IssueRequest()
 {
 timer.CreateLocal();   // created for this thread
 ...
 timer.After(iStatus,5000000); // Notification after 5 seconds
 SetActive();
 ...
 }

The active object’s completed request handler, i.e. its RunL() function can check the completion code as the code fragments show. While not particularly useful for timers, it shows the general principle:

//
// Extracting the completion code value
//
void RunL()
 {
 ...
 User::LeaveIfError(iStatus.Int());// leave on bad return code
 ...
 }

//
// Using a comparison operator
//
void RunL()
 {
 ...
 if (iStatus == KErrCancel);// check for a specific value 
 ...
 }