--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-BF796290-E9BC-5A18-AC59-9848823FBE34.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,61 @@
+<?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-BF796290-E9BC-5A18-AC59-9848823FBE34" xml:lang="en"><title>Using
+CActive</title><shortdesc>This document describes the use of the <codeph>CActive</codeph> class
+to implement asynchronous services and requests.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-A9EA0646-0C98-54B8-A88D-35E759400D55"><title>Writing derived
+classes</title> <p>A <codeph>CActive</codeph> -derived class must fulfil a
+number of requirements, including providing a constructor and a number of
+functions.</p> <p>To write a class which encapsulates an asynchronous service:</p> <ul>
+<li id="GUID-31F66997-600E-554A-9DE2-038C419DC37D"><p>define and implement
+a C++ constructor through which the priority of the active object can be specified.
+A typical implementation calls the <codeph>CActive</codeph> constructor through
+a constructor initialization list.</p> </li>
+<li id="GUID-83C464D7-2950-5C24-9469-210AE6A86A53"><p>define data members
+representing the asynchronous service provider; the number and meaning of
+these members depends on the services offered by the service provider</p> </li>
+<li id="GUID-731C8F60-1410-5E85-99FD-CC58312A2690"><p>define and implement
+a second-phase <codeph>ConstructL()</codeph> member function, if this is necessary
+to initialize contact with the asynchronous service provider.</p> </li>
+<li id="GUID-C316327D-8C8E-515F-9E9C-CDBD208EF437"><p>define and implement
+a <codeph>DoCancel()</codeph> member function to handle a cancel request to
+the service provider. This function is defined as pure virtual in <codeph>CActive</codeph> and
+any class derived from <codeph>CActive</codeph> must define and implement
+it.</p> </li>
+<li id="GUID-413E95E4-7E2B-565B-BF49-1DC51F29BD0F"><p>define and implement
+one or more service request functions which forward requests to the service
+provider</p> </li>
+</ul> <p>To write a class which handles the completion of an asynchronous
+request, a <codeph>RunL()</codeph> function should be provided. The function
+is defined as pure virtual in <codeph>CActive</codeph> and any class derived
+from <codeph>CActive</codeph> must define and implement it. <codeph>RunL()</codeph>:</p> <ul>
+<li id="GUID-274B7335-4DFF-5B22-A752-5DD1828575A8"><p>handles completion of
+a request, if appropriate</p> </li>
+<li id="GUID-633B97B6-2B1C-59FA-8221-C52A0B6DEEFB"><p>if appropriate, renews
+the request, or initiates other requests, or decides to terminate the series
+of requests handled by the active object</p> </li>
+</ul> <p>In some cases, a derived-class's <codeph>RunL()</codeph> will do
+some pre-handling of the request, and then invoke one or more appropriate
+virtual functions to handle particular types of completion. A further-derived
+class must provide virtual functions to specify the way various types of completion
+are handled.</p> <p>In the general case, the derivation of a concrete active
+object from the <codeph>CActive</codeph> base class may involve</p> <ul>
+<li id="GUID-922E8B94-6EE8-550C-929F-1EACDE81C977"><p>a derivation for encapsulating
+the service</p> </li>
+<li id="GUID-FBE75575-543C-59D1-9830-1FE3BBE36F7A"><p>a derivation for encapsulating
+the abstract handling of completion</p> </li>
+<li id="GUID-EF3D5B9C-C3BD-5DCA-9014-D42EC7A9471F"><p>further derivations
+for making that handling more concrete</p> </li>
+</ul> <p>Depending on the circumstances, some of these stages of derivation
+may be amalgamated into one stage; or stages may be refined into even finer
+derivation stages.</p> </section>
+</conbody></concept>
\ No newline at end of file