Categories: Symbian C++ | Essential Idioms | Base/System | Code Examples

This page was last modified 07:23, 25 June 2008.

From Forum Nokia Wiki

Definition

Indicates the completion status of a request made to a service provider. When a thread makes a request, it passes a request status as a parameter. On completion, the provider signals the requesting thread's request semaphore and stores a completion code in the request status. Typically, this is KErrNone or one of the other system-wide error codes.

Using TRequestStatus

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.

The request status object is always a data member of the active object.

class CMyActive : public CActive
 {
 void RunL();
 void IssueRequest();
 ...
 //This class has no iStatus member of its own because it is inherited from CActive!
 RTimer iTimer;
 }

The active object does not need to initialise 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.

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