<?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-890F06C6-DE32-5EB1-BF0F-D41794F47AE1" xml:lang="en"><title>Active
objects</title><shortdesc>This document describes the functionality and class membership
of active objects.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>An active object uses an asynchronous service provider class to provide
a service. The active object hides the asynchronous service provider. The
active object must provide: </p>
<ul>
<li id="GUID-C98FC10D-0ED4-5C6E-94DF-5B44143CB780"><p>a function that requests
a service from the service provider </p> </li>
<li id="GUID-CDA4E8D8-6E4A-5058-80AF-0CCC71956A7E"><p>a function that cancels
a request for service from the service provider. </p> </li>
</ul>
<p>All active objects are derived from <codeph>CActive</codeph>. This class
provides <i>derived</i> active objects with: </p>
<ul>
<li id="GUID-F6F9FD4E-1796-54F5-B90E-1784CAAB9BA5"><p>the data member <codeph>iStatus</codeph>.
This data member is a <codeph>TRequestStatus</codeph> type object. This object
is passed to the request functions of the asynchronous service provider. The
request functions of the active object do not include a <codeph>TRequestStatus</codeph> in
their parameters. The exception to this rule occurs when the active object
acts as a secondary supplier of asynchronous services. </p> </li>
<li id="GUID-E6BBFBF2-C909-5232-B37D-DD2AB5D56287"><p>the <codeph>Cancel()</codeph> function.
This function cancels a request to the service provider. <codeph>Cancel()</codeph> does
nothing if there is no outstanding request. If a request is pending, <codeph>Cancel()</codeph> calls <codeph>DoCancel()</codeph>. <codeph>DoCancel()</codeph> is a pure virtual function that a derived class supplies. <codeph>DoCancel()</codeph> must
deal with the specific cancellation behavior that the service provider requires. <codeph>Cancel()</codeph> waits
for the request to complete and then marks the request not active. </p> </li>
<li id="GUID-48261AFE-F289-520B-9AE4-701487DC3376"><p>the <codeph>TPriority</codeph> enumeration.
This enumeration defines the set of priorities that an active object can take.
The priority of the active object is set during construction of the active
object. When the active scheduler's wait completes, it checks the active object
with the highest priority. Where active objects have the same priority, the
order of checking is not defined. </p> </li>
</ul>
<p>Classes derived from <codeph>CActive</codeph> must: </p>
<ul>
<li id="GUID-07DFA89B-0690-56C4-B332-E48306B4FE4E"><p>own an asynchronous
service provider. It may do this by containing either an instance of the required
service provider or a handle to that provider. </p> </li>
<li id="GUID-BAF677B6-C7EF-56DB-8C42-04F58C72777E"><p>provide one or more
request functions, such as <codeph>IssueRequest()</codeph>, which pass on
the request to an asynchronous service provider. </p> </li>
<li id="GUID-16AE762B-88BF-5173-AD5F-000E82EC5267"><p>implement a <codeph>DoCancel()</codeph> function
which passes on a cancel request to the asynchronous service provider </p> </li>
<li id="GUID-8EBC0A7B-BF62-5568-BD26-DCA0C53961C3"><p>provide a <codeph>RunL()</codeph> function,
which is called by the active scheduler when it detects that an active object’s
request has completed. </p> </li>
<li id="GUID-738F8086-7CCE-558E-A32C-10686214F288"><p>provide a <codeph>RunError()</codeph> function,
which is called by the active scheduler if the active object's <codeph>RunL()</codeph> function
leaves. A derived class can use the default implementation but this just propagates
the leave code up to the active scheduler. </p> </li>
</ul>
<section id="GUID-FF78FFB3-6901-45D1-A5F3-4F1C44355836"><title>See also</title> <p> <xref href="GUID-2C5D53A3-0211-5C14-BD7F-E89EB27BAD2A.dita">Active
Scheduler</xref>  </p> </section>
</conbody></concept>