--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-220E5E6A-B55D-57BB-AC1A-CE06EB01F661.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,94 @@
+<?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-220E5E6A-B55D-57BB-AC1A-CE06EB01F661" xml:lang="en"><title>How
+to construct an active object</title><shortdesc>This document describes how to construct an active object to encapsulate
+a service provider.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The following examples outline the practical framework required when implementing
+an active object</p>
+<section id="GUID-72356539-28E2-53C4-BB8C-A181FD1DF0B3"><title>Active objects
+framework</title> <p>The following example code demonstrates how to construct
+the framework for a simple active object which encapsulates a service-provider.</p> <p>First
+define and implement the service-provider class. The following code shows
+the typical features:</p> <codeblock id="GUID-F2E43707-9A97-5B5E-8356-8359FBA955A2" xml:space="preserve">class CExampleServiceProvider
+    {
+public:
+    ...
+    void RequestTheService(TRequestStatus&amp; aStatus);
+    void CancelTheRequest();
+private:
+    TInt iResult ;
+    };</codeblock> <p>Now define and implement the active object which wraps
+around the service provider. The following code shows the main features of
+an active object class.</p> <ul>
+<li id="GUID-E3F867F0-4172-5477-AB38-624687856385"><p>Provide a constructor.</p> </li>
+<li id="GUID-1F0BD2F9-6B34-52A3-B5D8-241D070639EE"><p>Provide a <codeph>RunL()</codeph> function
+to handle the completion of an asynchronous request.</p> </li>
+<li id="GUID-49FCE50F-CEF6-5637-9A41-721C85841E8B"><p>Provide a <codeph>DoCancel()</codeph> function
+to implement a cancellation request.</p> </li>
+<li id="GUID-F91E76BD-238B-58AA-8948-34881A302FC0"><p>Provide a <codeph>RunError()</codeph> function
+to implement recovery and cleanup if the <codeph>RunL()</codeph> function
+leaves. Note that this is not available in v5.</p> </li>
+</ul> <codeblock id="GUID-E38A48A2-F62D-518C-BE66-E8CA841EBEA1" xml:space="preserve">class CExampleActiveObject : public CActive;
+    {
+public:
+    CExampleActiveObject(CExampleServiceProvider* aServiceProvider);
+    ~CExampleActiveObject;
+    void IssueRequest();
+private:
+    void DoCancel();
+    void RunL();
+    TInt RunError(TInt aError);
+private:
+    CExampleServiceProvider* iServiceProvider ;
+    };</codeblock> <p>When the class codes a <codeph>DoCancel()</codeph> then
+the destructor must call the <codeph>Cancel()</codeph> member function of
+the active object.</p> </section>
+<section id="GUID-C12409DF-5921-5C4A-92A1-1C93CADC44DF"><title>How to construct
+an active object</title> <p>The following code shows the typical elements
+required when constructing an active object.</p> <codeblock id="GUID-6696494D-3FFB-5BE5-973D-6B661FE5B6BB" xml:space="preserve">CExampleActiveObject::CExampleActiveObject(CExampleServiceProvider* aServiceProvider) : CActive(EPriorityStandard)
+    {
+    iServiceProvider = aServiceProvider; // Store pointer to service provider
+    CActiveScheduler::Add(this) ;        // add to active scheduler
+    }</codeblock> <ul>
+<li id="GUID-C8A38D47-424C-5E46-B687-DFDE920C1C05"><p>Set the active object’s
+priority using one of the <codeph>CActive::Tpriority</codeph> enumeration
+values.</p> </li>
+<li id="GUID-0BA9E845-4911-52C8-9DC6-AC6EDC2927F0"><p>Retain a handle to the
+required service provider, so that request functions can pass on a request
+to the asynchronous service provider.</p> </li>
+<li id="GUID-6455A36F-0274-5901-8935-065BBDB77457"><p>Use <codeph>add()</codeph> to
+add the active object to the active scheduler, in order to ensure that its
+requests are handled.</p> </li>
+</ul> <p>In practice there are many variations on this basic construction
+theme.</p> <ul>
+<li id="GUID-F90B7B68-87AF-5B4E-B991-47CBEA834638"><p>Most active objects
+set the priority within the constructor and this is almost always the <codeph>EPriorityStandard</codeph> or
+zero value. In some cases, the choice of priority value is decided by the
+caller or by the constructor of a class further derived from this one.</p> </li>
+<li id="GUID-E9340ED6-61EB-51CF-8B65-9FC0027BB8E1"><p>In many situations,
+the service provider is constructed by the active object itself, instead of
+being passed in. Often this is done as part of a two stage construction process.
+For example, the <codeph>CTimer</codeph> active object has a simple constructor
+and a function <codeph>ConstructL()</codeph> which completes the construction
+of the object:</p> </li>
+</ul> <codeblock id="GUID-EEE316CB-BA6B-56CD-BA2E-141FB1BCD6AF" xml:space="preserve">CTimer::CTimer(TInt aPriority)
+    : CActive(aPriority)
+    {
+    }</codeblock> <codeblock id="GUID-8314023A-D749-5544-9D0E-1DE76F5A2263" xml:space="preserve">void CTimer::ConstructL()
+    {
+    TInt r=iTimer.CreateLocal();
+    if (r!=KErrNone)
+        {
+        User::Leave(r);
+        }
+    }</codeblock> </section>
+</conbody></concept>
\ No newline at end of file