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