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