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