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