<?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-BF796290-E9BC-5A18-AC59-9848823FBE34" xml:lang="en"><title>Using
CActive</title><shortdesc>This document describes the use of the <codeph>CActive</codeph> class
to implement asynchronous services and requests.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-A9EA0646-0C98-54B8-A88D-35E759400D55"><title>Writing derived
classes</title> <p>A <codeph>CActive</codeph> -derived class must fulfil a
number of requirements, including providing a constructor and a number of
functions.</p> <p>To write a class which encapsulates an asynchronous service:</p> <ul>
<li id="GUID-31F66997-600E-554A-9DE2-038C419DC37D"><p>define and implement
a C++ constructor through which the priority of the active object can be specified.
A typical implementation calls the <codeph>CActive</codeph> constructor through
a constructor initialization list.</p> </li>
<li id="GUID-83C464D7-2950-5C24-9469-210AE6A86A53"><p>define data members
representing the asynchronous service provider; the number and meaning of
these members depends on the services offered by the service provider</p> </li>
<li id="GUID-731C8F60-1410-5E85-99FD-CC58312A2690"><p>define and implement
a second-phase <codeph>ConstructL()</codeph> member function, if this is necessary
to initialize contact with the asynchronous service provider.</p> </li>
<li id="GUID-C316327D-8C8E-515F-9E9C-CDBD208EF437"><p>define and implement
a <codeph>DoCancel()</codeph> member function to handle a cancel request to
the service provider. This function is defined as pure virtual in <codeph>CActive</codeph> and
any class derived from <codeph>CActive</codeph> must define and implement
it.</p> </li>
<li id="GUID-413E95E4-7E2B-565B-BF49-1DC51F29BD0F"><p>define and implement
one or more service request functions which forward requests to the service
provider</p> </li>
</ul> <p>To write a class which handles the completion of an asynchronous
request, a <codeph>RunL()</codeph> function should be provided. The function
is defined as pure virtual in <codeph>CActive</codeph> and any class derived
from <codeph>CActive</codeph> must define and implement it. <codeph>RunL()</codeph>:</p> <ul>
<li id="GUID-274B7335-4DFF-5B22-A752-5DD1828575A8"><p>handles completion of
a request, if appropriate</p> </li>
<li id="GUID-633B97B6-2B1C-59FA-8221-C52A0B6DEEFB"><p>if appropriate, renews
the request, or initiates other requests, or decides to terminate the series
of requests handled by the active object</p> </li>
</ul> <p>In some cases, a derived-class's <codeph>RunL()</codeph> will do
some pre-handling of the request, and then invoke one or more appropriate
virtual functions to handle particular types of completion. A further-derived
class must provide virtual functions to specify the way various types of completion
are handled.</p> <p>In the general case, the derivation of a concrete active
object from the <codeph>CActive</codeph> base class may involve</p> <ul>
<li id="GUID-922E8B94-6EE8-550C-929F-1EACDE81C977"><p>a derivation for encapsulating
the service</p> </li>
<li id="GUID-FBE75575-543C-59D1-9830-1FE3BBE36F7A"><p>a derivation for encapsulating
the abstract handling of completion</p> </li>
<li id="GUID-EF3D5B9C-C3BD-5DCA-9014-D42EC7A9471F"><p>further derivations
for making that handling more concrete</p> </li>
</ul> <p>Depending on the circumstances, some of these stages of derivation
may be amalgamated into one stage; or stages may be refined into even finer
derivation stages.</p> </section>
</conbody></concept>