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