<?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>