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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-CCCEC352-3A49-534C-9551-A4CAE1A3475E" xml:lang="en"><title>How

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

    14 <p>A thread that requests an asynchronous service from another thread can

    15 continue processing but eventually reaches a point where it must wait until

    16 the asynchronous request is complete before it can resume processing.</p>

    17 <p>Typically, the requester performs the following sequence:</p>

    18 <ul>

    19 <li id="GUID-0A1C409D-80A4-5EC0-AC59-A3D6C7E5228D"><p>creates an object of

    20 type <codeph>TRequestStatus</codeph> to monitor the state of the request.</p> </li>

    21 <li id="GUID-BBCD758B-2B52-5D83-9C13-FC0204600563"><p>calls the asynchronous

    22 provider's request function, passing the <codeph>TRequestStatus</codeph> object;

    23 all asynchronous functions are prototyped to take a <codeph>TRequestStatus</codeph> parameter.</p> </li>

    24 <li id="GUID-E874E08B-19EF-5887-A7CC-DED65B5A84B4"><p>uses the operating system

    25 function <codeph>User::WaitForRequest()</codeph> to allow the thread to wait

    26 for completion of the request.</p> </li>

    27 </ul>

    28 <codeblock id="GUID-6425F8F3-7196-56C7-9886-F599EEA9E07D" xml:space="preserve">TRequestStatus status;                        // Request status object

    29 someProvider.IssueRequest(parameters,status); // Issue the request

    30 ...

    31 User::WaitForRequest(status);                 // Wait for completion

    32 if (status==KErrNone)

    33     {

    34     /* success */

    35     }

    36 else if (status==KErrXxx)

    37     {

    38     /* check for some error */

    39     }

    40 else // check for other error conditions etc.

    41 ...</codeblock>

    42 <section id="GUID-E8B90FAF-1891-49EE-8915-D9265F8884AB"><title>Notes</title> <ul>

    43 <li id="GUID-99618D33-6281-5C32-B54B-4451F6228C85"><p>there is no special

    44 name for a request function; the request performed depends on the class, the

    45 function name and the parameters passed.</p> </li>

    46 <li id="GUID-F1D8C498-3A72-5C02-892B-8DB1792D651F"><p>when the request is

    47 complete, an integer is stored in the request status object to convey additional

    48 information about the completion of the function. The meaning of the completion

    49 code varies from function to function. Additionally, information returned

    50 by the request may be returned to reference parameters passed to the request

    51 function.</p> </li>

    52 <li id="GUID-E87D9AED-C897-5F19-8E34-A43C2E7AFF35"><p>The integer completion

    53 code must not be <codeph>KErrPending</codeph>. By convention, <codeph>KErrNone</codeph> indicates

    54 no error and <codeph>KErrCancel</codeph> indicates a cancelled request. Other

    55 values may be used for specific types of error.</p> </li>

    56 </ul> </section>

    57 </conbody></concept>