<?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&amp;</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>