1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-56841E07-1A4A-5572-BF3F-F80069FD5D59" xml:lang="en"><title>How

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

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

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

    16 an active scheduler is always provided. </p>

    17 <ul>

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

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

    20 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

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

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

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

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

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

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

    27 construction processing. </p> </li>

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

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

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

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

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

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

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

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

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

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

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

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

    40 </ul>

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

    42     {

    43         // Create and install the active scheduler

    44     CActiveScheduler* exampleScheduler=new (ELeave) CExampleScheduler;

    45     CleanupStack::PushL(exampleScheduler);

    46     CActiveScheduler::Install(exampleScheduler);

    47 

    48         // Create the service provider. Often, the

    49         // service provider is part of the active object

    50     CExampleServiceProvider* myServiceProvider=new (ELeave) CExampleServiceProvider;

    51     CleanupStack::PushL(myServiceProvider);

    52 

    53         // Create the active object and issue the

    54         // first asynchronous request

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

    56     CleanupStack::PushL(myActiveObject);

    57     myActiveObject->IssueRequest();

    58 

    59         // Now we can start the active scheduler

    60     CActiveScheduler::Start();

    61 

    62         // Remove the exampleScheduler and other

    63         // objects from cleanup stack and destroy them

    64     CleanupStack::PopAndDestroy(3);

    65     }</codeblock>

    66 </conbody></concept>