<?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-CCCEC352-3A49-534C-9551-A4CAE1A3475E" xml:lang="en"><title>How
to handle a single asynchronous request</title><shortdesc>This document describes how to handle a single asynchronous request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>A thread that requests an asynchronous service from another thread can
continue processing but eventually reaches a point where it must wait until
the asynchronous request is complete before it can resume processing.</p>
<p>Typically, the requester performs the following sequence:</p>
<ul>
<li id="GUID-0A1C409D-80A4-5EC0-AC59-A3D6C7E5228D"><p>creates an object of
type <codeph>TRequestStatus</codeph> to monitor the state of the request.</p> </li>
<li id="GUID-BBCD758B-2B52-5D83-9C13-FC0204600563"><p>calls the asynchronous
provider's request function, passing the <codeph>TRequestStatus</codeph> object;
all asynchronous functions are prototyped to take a <codeph>TRequestStatus</codeph> parameter.</p> </li>
<li id="GUID-E874E08B-19EF-5887-A7CC-DED65B5A84B4"><p>uses the operating system
function <codeph>User::WaitForRequest()</codeph> to allow the thread to wait
for completion of the request.</p> </li>
</ul>
<codeblock id="GUID-6425F8F3-7196-56C7-9886-F599EEA9E07D" xml:space="preserve">TRequestStatus status;                        // Request status object
someProvider.IssueRequest(parameters,status); // Issue the request
...
User::WaitForRequest(status);                 // Wait for completion
if (status==KErrNone)
    {
    /* success */
    }
else if (status==KErrXxx)
    {
    /* check for some error */
    }
else // check for other error conditions etc.
...</codeblock>
<section id="GUID-E8B90FAF-1891-49EE-8915-D9265F8884AB"><title>Notes</title> <ul>
<li id="GUID-99618D33-6281-5C32-B54B-4451F6228C85"><p>there is no special
name for a request function; the request performed depends on the class, the
function name and the parameters passed.</p> </li>
<li id="GUID-F1D8C498-3A72-5C02-892B-8DB1792D651F"><p>when the request is
complete, an integer is stored in the request status object to convey additional
information about the completion of the function. The meaning of the completion
code varies from function to function. Additionally, information returned
by the request may be returned to reference parameters passed to the request
function.</p> </li>
<li id="GUID-E87D9AED-C897-5F19-8E34-A43C2E7AFF35"><p>The integer completion
code must not be <codeph>KErrPending</codeph>. By convention, <codeph>KErrNone</codeph> indicates
no error and <codeph>KErrCancel</codeph> indicates a cancelled request. Other
values may be used for specific types of error.</p> </li>
</ul> </section>
</conbody></concept>