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