<?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-1294F540-FDA7-5050-BAFB-3C9888491B98" xml:lang="en"><title>Asynchronous
Services Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-6F9E9225-A8E2-41C9-B7B5-A89E2800445C"><title>Purpose</title> <p>Provides low-level and high-level idioms
by which one thread or process in Symbian platform can request services from
another.</p> <p>Client programs typically use these idioms when accessing
system services such as windowing, or telephony. This process is so fundamental
that the basic structure of nearly all Symbian platform applications is based
on its encapsulation in the active object framework.</p> </section>
<section id="GUID-CA918B24-FFC7-47C1-A683-F8AE01192ED3"><title>Architectural relationships</title> <p>Asynchronous services
are used throughout Symbian platform, most commonly as encapsulated in the
client/server architecture. Some APIs may in turn wrap client/server relationships
in framework classes, so that it is not immediately obvious that a client
program is using asynchronous services. The most important case of this is
the UI application framework, which wraps client requests to be informed of
user interface events.</p> </section>
<section id="GUID-78BD76F0-7785-4238-A17F-40B7117BEB39"><title>Description</title> <p><b>General
properties</b> </p> <p>Client programs must often request access to services
provided by other threads or processes. For example, most application programs
will request the system's window server process to inform it of keyboard input.
A thread or process that provides such services is called an <i>asynchronous
service provider</i>.</p> <p>When a function call to an asynchronous service
provider returns, it means only that the request has been despatched. The
asynchronous service provider informs the requester that it has actually completed
the request through a signalling mechanism.</p> <ul>
<li id="GUID-E6B20563-4114-5896-A80E-1D2195631346"><p>Low-level asynchronous
service handling shows the basic asynchronous services concepts.</p> </li>
<li id="GUID-A84879C4-703D-5681-934D-D7649440A67F"><p>High-level asynchronous
service handling shows the Symbian platform framework that encapsulates asynchronous
service handling.</p> </li>
</ul> <p><b>Low-level
asynchronous service handling</b> </p> <p>Low-level asynchronous service handling
has two key concepts, asynchronous request status, and thread request semaphore.</p> <p><b>Asynchronous request status</b> </p> <p>An asynchronous request status
indicates the completion status of a request to a service provider. When a
thread makes a request, it passes an asynchronous request status as a parameter.
When the provider completes the request, it stores a success or error code
in the request status.</p> <p>The asynchronous request status is provided
by <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref>.</p> <p><b>Thread
request semaphore</b> </p> <p>A thread request semaphore is the means by which
a provider signals a requester that it has completed a request. Client code
can then determine which request has completed, and call an appropriate function
to handle completion of the request. </p> <p>Functions to signal a thread
request semaphore, and to wait until it has been signalled are provided by
the System Static Functions API <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User</apiname></xref> class.</p> <p><b>High-level asynchronous service handling</b> </p> <p>High-level asynchronous
service handling has two key concepts, active object, and active scheduler.</p> <p><b>Active object</b> </p> <p>An active object encapsulates the general behavior
of making requests to asynchronous service provider, and handling the completion
of requests. Particular asynchronous service provider typically supply active
object based classes as interfaces by which clients to access them. </p> <p>The
active object interface is provided by <xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita"><apiname>CActive</apiname></xref>.</p> <p><b>Active scheduler</b> </p> <p>A thread which uses asynchronous services
must have a main loop that waits on the thread’s request semaphore for any
outstanding requests to complete. The active scheduler encapsulates this wait
loop. An active scheduler is provided for all GUI programs. A high-level view
of a GUI application is therefore is that it is a set of active objects to
handle request completion events fed it by its active scheduler.</p> <p>The
active scheduler interface is provided by <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref>.</p> </section>
<section id="GUID-67C2E21D-8F63-4637-832F-9EBD4B2FF4AF"><title>See also</title> <p><xref href="GUID-D0D27AEA-FDDB-5F6F-94F6-ADDF5910DC47.dita">Client/Server
Overview</xref> </p> <p><xref href="GUID-E865E677-1219-500C-89CF-0A2835B91834.dita">Semaphores
Overview</xref> </p> <p><xref href="GUID-FF8F5D97-7D37-5F6B-84A3-C064E2FD53E0.dita">System
Static Functions Overview</xref> </p> </section>
</conbody></concept>