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