<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E72E2602-0492-58F9-A01F-D72BCC3FFFD5" xml:lang="en"><title>Using

TRequestStatus</title><shortdesc>This document describes the use of TRequestStatus objects to hold

the completion status of an asynchronous request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A request status object is used to carry the completion status of an asynchronous

request.</p>

<p>Typically, an asynchronous request is made by an active object, an instance

of a <codeph>CActive</codeph> 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.</p>

<p>Note that the request status object is the data member: <xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita#GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F/GUID-0EBC52DE-37A7-31A8-AB78-99E65CFEAED5"><apiname>CActive::iStatus</apiname></xref> of

the <xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita"><apiname>CActive</apiname></xref> base class.</p>

<codeblock id="GUID-2F4F5562-22C1-5868-8B1F-DE0A05B43CEA" xml:space="preserve">class CMyActive : public CActive

 {

 void RunL();

 void IssueRequest();

 ...

 RTimer         iTimer;

 }</codeblock>

<p>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 <codeph>KRequestPending</codeph> before

initiating the request. For example:</p>

<codeblock id="GUID-E16E9168-8AAD-52E9-8734-7865A6939E67" xml:space="preserve">void CMyActive::IssueRequest()

 {

 timer.CreateLocal();   // created for this thread

 ...

 timer.After(iStatus,5000000); // Notification after 5 seconds

 SetActive();

 ...

 }</codeblock>

<p>The active object’s completed request handler, i.e. its <codeph>RunL()</codeph> function

can check the completion code as the code fragments show. While not particularly

useful for timers, it shows the general principle:</p>

<codeblock id="GUID-927EBB91-9772-5A48-B5F8-C909552F898A" xml:space="preserve">//

// Extracting the completion code value

//

void RunL()

 {

 ...

 User::LeaveIfError(iStatus.Int());// leave on bad return code

 ...

 }</codeblock>

<codeblock id="GUID-0501DC7C-84BA-5784-BA36-BCE595C2E95E" xml:space="preserve">//

// Using a comparison operator

//

void RunL()

 {

 ...

 if (iStatus == KErrCancel);// check for a specific value 

 ...

 }</codeblock>

</conbody></concept>