--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-C3AC4F95-67E9-5F1D-8CF0-F6B209319EC0.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,63 @@
+<?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-C3AC4F95-67E9-5F1D-8CF0-F6B209319EC0" xml:lang="en"><title>What
+asynchronous service providers do</title><shortdesc>This document describes the purpose of asynchronous service providers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-3653AC36-81A4-4207-B174-1EBBCCA43E65"><title>Request functions and the request status</title> <p>An asynchronous
+service provider offers one or more <i>request functions</i>. </p> <p>Only
+one request on a service provider can be outstanding at any one time. A <i>request
+function</i> is one that takes a <codeph>TRequestStatus&</codeph> parameter
+or, in rare cases, a <codeph>TRequestStatus*</codeph> parameter.</p> <p>When
+a request function is called (or when the asynchronous service provider is
+constructed, opened or initialized), the handle of the client thread is noted
+by the asynchronous service provider, so it knows which thread made the request.
+A panic results if any other thread tries to use the asynchronous service
+provider — for instance, to call its cancel function, or to issue another
+request — since the client of an asynchronous service provider is assumed
+to be a single thread.</p> <p>The asynchronous service provider's request
+function:</p> <ul>
+<li id="GUID-DB0F6F6D-DC43-568F-B675-5EEEE1EB0E2F"><p>first sets the value
+of the passed <codeph>TRequestStatus</codeph> to <codeph>KRequestPending</codeph> </p> </li>
+<li id="GUID-A1745B0E-E46F-5541-BE62-CE7B23864767"><p>then initiates the request,
+which may complete any time later.</p> </li>
+</ul> <p>There are several typical cases:</p> <ul>
+<li id="GUID-E82051C8-83B0-5263-8359-40A3DB47D694"><p>the request completes
+normally some time after the request function has returned.</p> </li>
+<li id="GUID-C061E1FA-2B91-5A1F-B2CA-9FA2AD668412"><p>the request completes
+during the request function call, either because the request completes immediately,
+or because of an error such as bad parameters meaning that the request cannot
+even be initiated.</p> </li>
+<li id="GUID-EEDCAE49-4BAE-52FE-B33D-0AD288671624"><p>some other type of abnormal
+completion such as cancellation, which can occur either during the request
+function call or later.</p> </li>
+</ul> </section>
+<section id="GUID-73EEA278-054A-4393-8264-5DBD2DB88A4A"><title>Thread request semaphore</title> <p>When a request completes,
+the client thread’s request semaphore is signalled to indicate completion.</p> <p>Each
+thread has a single request semaphore. A thread which uses asynchronous services
+must have a program whose main loop waits on the thread’s request semaphore
+for any outstanding request to complete.</p> <p>When any request completes,
+the thread program must identify which of the outstanding requests has completed.
+It does this by checking the <codeph>TRequestStatus</codeph> object associated
+with each outstanding request and, if its value is not <codeph>KRequestPending</codeph>,
+the program knows that the request is complete and can handle the completion
+of that request.</p> </section>
+<section id="GUID-D1A4AE55-CD75-43E5-AD4D-AA5BDDEF7FD5"><title>Cancel functions</title> <p>All asynchronous service providers
+provide one or more <i>cancel functions</i>, which cancel any outstanding
+request.</p> <p>Because of the asynchronous nature of requests, a cancel function
+may be called after the request has actually completed. For this reason, a
+cancel function should be viewed as a request for <i>early completion</i>.
+If you issue a cancel, the asynchronous service provider may complete the
+request abnormally by posting <codeph>KErrCancel</codeph> in the request status
+object, or it may complete the request normally by posting an appropriate
+completion code.</p> </section>
+<section id="GUID-7C8829A7-9FDB-46FA-A9E2-692E90398371"><title>See also</title> <p><xref href="GUID-E6D9F8CA-F293-5CE6-93C4-5FEC5EBCB2E9.dita">Asynchronous
+service provider's responsibilities</xref>.</p> </section>
+</conbody></concept>
\ No newline at end of file