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