<?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-56841E07-1A4A-5572-BF3F-F80069FD5D59" xml:lang="en"><title>How

to start active objects</title><shortdesc>This document describes how to start active objects.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The following example code shows how active objects are started. While

the example shows the creation of an active scheduler, in UI applications,

an active scheduler is always provided. </p>

<ul>

<li id="GUID-4E857369-075A-5337-9152-0475DE0D41E9"><p>Create an instance of

the active scheduler, <codeph>exampleScheduler</codeph>. This is an instance

of a class derived from <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> and provides an <codeph>Error()</codeph> function

to handle leaves occurring in the active object <codeph>RunL()</codeph> function(s). </p> </li>

<li id="GUID-857D957B-E5C5-5C37-BEEA-F10B42B208B5"><p>Push <codeph>exampleScheduler</codeph> onto

the cleanup stack and install as the current active scheduler. </p> </li>

<li id="GUID-38C2AC92-6DFF-50A1-BE24-163ABBCD66BA"><p>Create an active object, <codeph>myActiveObject</codeph>,

and pass a pointer to the service provider as the parameter. Note that often,

the service provider may be constructed as part of the active object's own

construction processing. </p> </li>

<li id="GUID-2C390F94-0AF5-585C-BAB4-A8142DF87F56"><p>Issue a request using <codeph>IssueRequest()</codeph>. </p> </li>

<li id="GUID-A39EB27D-91AE-5932-ADCE-7E75ECCB042F"><p>Use <codeph>CActiveScheduler::Start()</codeph> to

start the active scheduler’s wait loop. At least one outstanding request is

necessary before the wait loop is started, otherwise the thread hangs. All

further request issuing and servicing occurs within this function. The wait

loop continues until one of the active objects’ <codeph>RunL()</codeph> requests

termination using <codeph>CActiveScheduler::Stop()</codeph>. </p> </li>

<li id="GUID-ADCBB62D-0A83-5D5B-915C-7F30D863943C"><p>Pop the active object,

the active scheduler and the example service provider from the clean-up stack,

and destroy. The code assumes that the active object does not take ownership

of the <codeph>CExampleServiceProvider</codeph> object and is not responsible

for its destruction. </p> </li>

</ul>

<codeblock id="GUID-1895F4F4-0EDF-5ADC-B3D7-FC792719299C" xml:space="preserve">LOCAL_C void doExampleL()

    {

        // Create and install the active scheduler

    CActiveScheduler* exampleScheduler=new (ELeave) CExampleScheduler;

    CleanupStack::PushL(exampleScheduler);

    CActiveScheduler::Install(exampleScheduler);

        // Create the service provider. Often, the

        // service provider is part of the active object

    CExampleServiceProvider* myServiceProvider=new (ELeave) CExampleServiceProvider;

    CleanupStack::PushL(myServiceProvider);

        // Create the active object and issue the

        // first asynchronous request

    CExampleActiveObject * myActiveObject=new (ELeave) CExampleActiveObject(myServiceProvider);

    CleanupStack::PushL(myActiveObject);

    myActiveObject->IssueRequest();

        // Now we can start the active scheduler

    CActiveScheduler::Start();

        // Remove the exampleScheduler and other

        // objects from cleanup stack and destroy them

    CleanupStack::PopAndDestroy(3);

    }</codeblock>