|
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-220E5E6A-B55D-57BB-AC1A-CE06EB01F661" xml:lang="en"><title>How |
|
13 to construct an active object</title><shortdesc>This document describes how to construct an active object to encapsulate |
|
14 a service provider.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The following examples outline the practical framework required when implementing |
|
16 an active object</p> |
|
17 <section id="GUID-72356539-28E2-53C4-BB8C-A181FD1DF0B3"><title>Active objects |
|
18 framework</title> <p>The following example code demonstrates how to construct |
|
19 the framework for a simple active object which encapsulates a service-provider.</p> <p>First |
|
20 define and implement the service-provider class. The following code shows |
|
21 the typical features:</p> <codeblock id="GUID-F2E43707-9A97-5B5E-8356-8359FBA955A2" xml:space="preserve">class CExampleServiceProvider |
|
22 { |
|
23 public: |
|
24 ... |
|
25 void RequestTheService(TRequestStatus& aStatus); |
|
26 void CancelTheRequest(); |
|
27 private: |
|
28 TInt iResult ; |
|
29 };</codeblock> <p>Now define and implement the active object which wraps |
|
30 around the service provider. The following code shows the main features of |
|
31 an active object class.</p> <ul> |
|
32 <li id="GUID-E3F867F0-4172-5477-AB38-624687856385"><p>Provide a constructor.</p> </li> |
|
33 <li id="GUID-1F0BD2F9-6B34-52A3-B5D8-241D070639EE"><p>Provide a <codeph>RunL()</codeph> function |
|
34 to handle the completion of an asynchronous request.</p> </li> |
|
35 <li id="GUID-49FCE50F-CEF6-5637-9A41-721C85841E8B"><p>Provide a <codeph>DoCancel()</codeph> function |
|
36 to implement a cancellation request.</p> </li> |
|
37 <li id="GUID-F91E76BD-238B-58AA-8948-34881A302FC0"><p>Provide a <codeph>RunError()</codeph> function |
|
38 to implement recovery and cleanup if the <codeph>RunL()</codeph> function |
|
39 leaves. Note that this is not available in v5.</p> </li> |
|
40 </ul> <codeblock id="GUID-E38A48A2-F62D-518C-BE66-E8CA841EBEA1" xml:space="preserve">class CExampleActiveObject : public CActive; |
|
41 { |
|
42 public: |
|
43 CExampleActiveObject(CExampleServiceProvider* aServiceProvider); |
|
44 ~CExampleActiveObject; |
|
45 void IssueRequest(); |
|
46 private: |
|
47 void DoCancel(); |
|
48 void RunL(); |
|
49 TInt RunError(TInt aError); |
|
50 private: |
|
51 CExampleServiceProvider* iServiceProvider ; |
|
52 };</codeblock> <p>When the class codes a <codeph>DoCancel()</codeph> then |
|
53 the destructor must call the <codeph>Cancel()</codeph> member function of |
|
54 the active object.</p> </section> |
|
55 <section id="GUID-C12409DF-5921-5C4A-92A1-1C93CADC44DF"><title>How to construct |
|
56 an active object</title> <p>The following code shows the typical elements |
|
57 required when constructing an active object.</p> <codeblock id="GUID-6696494D-3FFB-5BE5-973D-6B661FE5B6BB" xml:space="preserve">CExampleActiveObject::CExampleActiveObject(CExampleServiceProvider* aServiceProvider) : CActive(EPriorityStandard) |
|
58 { |
|
59 iServiceProvider = aServiceProvider; // Store pointer to service provider |
|
60 CActiveScheduler::Add(this) ; // add to active scheduler |
|
61 }</codeblock> <ul> |
|
62 <li id="GUID-C8A38D47-424C-5E46-B687-DFDE920C1C05"><p>Set the active object’s |
|
63 priority using one of the <codeph>CActive::Tpriority</codeph> enumeration |
|
64 values.</p> </li> |
|
65 <li id="GUID-0BA9E845-4911-52C8-9DC6-AC6EDC2927F0"><p>Retain a handle to the |
|
66 required service provider, so that request functions can pass on a request |
|
67 to the asynchronous service provider.</p> </li> |
|
68 <li id="GUID-6455A36F-0274-5901-8935-065BBDB77457"><p>Use <codeph>add()</codeph> to |
|
69 add the active object to the active scheduler, in order to ensure that its |
|
70 requests are handled.</p> </li> |
|
71 </ul> <p>In practice there are many variations on this basic construction |
|
72 theme.</p> <ul> |
|
73 <li id="GUID-F90B7B68-87AF-5B4E-B991-47CBEA834638"><p>Most active objects |
|
74 set the priority within the constructor and this is almost always the <codeph>EPriorityStandard</codeph> or |
|
75 zero value. In some cases, the choice of priority value is decided by the |
|
76 caller or by the constructor of a class further derived from this one.</p> </li> |
|
77 <li id="GUID-E9340ED6-61EB-51CF-8B65-9FC0027BB8E1"><p>In many situations, |
|
78 the service provider is constructed by the active object itself, instead of |
|
79 being passed in. Often this is done as part of a two stage construction process. |
|
80 For example, the <codeph>CTimer</codeph> active object has a simple constructor |
|
81 and a function <codeph>ConstructL()</codeph> which completes the construction |
|
82 of the object:</p> </li> |
|
83 </ul> <codeblock id="GUID-EEE316CB-BA6B-56CD-BA2E-141FB1BCD6AF" xml:space="preserve">CTimer::CTimer(TInt aPriority) |
|
84 : CActive(aPriority) |
|
85 { |
|
86 }</codeblock> <codeblock id="GUID-8314023A-D749-5544-9D0E-1DE76F5A2263" xml:space="preserve">void CTimer::ConstructL() |
|
87 { |
|
88 TInt r=iTimer.CreateLocal(); |
|
89 if (r!=KErrNone) |
|
90 { |
|
91 User::Leave(r); |
|
92 } |
|
93 }</codeblock> </section> |
|
94 </conbody></concept> |