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