|
1 /* |
|
2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef FEATUREINFOPLUGIN_H |
|
21 #define FEATUREINFOPLUGIN_H |
|
22 |
|
23 /** |
|
24 @file |
|
25 @publishedPartner |
|
26 @released |
|
27 |
|
28 This header file holds the definitions for the Feature Manager adaptation |
|
29 interface - Feature Info Plug-in API. |
|
30 It holds interface and command definitions and the related command and response |
|
31 types and structures used over this interface. |
|
32 */ |
|
33 |
|
34 |
|
35 // INCLUDES |
|
36 |
|
37 #include <e32base.h> |
|
38 #include <featmgr/featurecmn.h> |
|
39 |
|
40 |
|
41 // CONSTANTS |
|
42 |
|
43 /** |
|
44 This constant holds the ECOM Instantiation Interface UID. This interface UID |
|
45 identifies plug-in implementations that derive from CFeatureInfoPlugin. |
|
46 This interface is used by the Feature Manager server when it is started up. |
|
47 @see CFeatureInfoPlugin |
|
48 */ |
|
49 const TUid KFeatureInfoPluginInterfaceUid = { 0x10205057 }; |
|
50 |
|
51 |
|
52 // TYPES & STRUCTURES |
|
53 |
|
54 /** |
|
55 FeatureInfoCommand namespace groups the command ID enumerations, structures |
|
56 and types used over the CFeatureInfoPlugin interface. |
|
57 */ |
|
58 namespace FeatureInfoCommand |
|
59 { |
|
60 |
|
61 /** |
|
62 Command definitions |
|
63 All commands contain a command Id and a set of parameters. The command |
|
64 Ids are defined first then the parameters for each command. |
|
65 |
|
66 The CFeatureInfoPlug ininterface is asynchronous. A command Id is sent to |
|
67 the plugin through CFeatureInfoPlugin::ProcessCommandL(). If the command is |
|
68 supported by the plug-in it schedules an active object to do the work and |
|
69 call MFeatureInfoPluginCallback::ProcessResponseL() to complete the command. |
|
70 If the command is not supported, the plug-in should leave with |
|
71 KErrNotSupported. |
|
72 |
|
73 The field Input means the parameter for the command. |
|
74 The field Output means the parameter for the response. |
|
75 @see CFeatureInfoPlugin |
|
76 @see MFeatureInfoPluginCallback |
|
77 */ |
|
78 enum TFeatureInfoCmd |
|
79 { |
|
80 /** |
|
81 No command. May be used for sanity checks, but |
|
82 never as an actual command ID. |
|
83 Input None |
|
84 Output None |
|
85 */ |
|
86 ENoCommandId = 1000, |
|
87 |
|
88 /** |
|
89 FM uses this command to request feature information of read-only |
|
90 features, aka simple features, known to the plug-in. Implementations |
|
91 should used this command to return such features, if any are known. |
|
92 If no such features are known to the plug-in it should leave with |
|
93 KErrNotSupported, hence this command is optional. |
|
94 Features contained in a response to this command should not appear |
|
95 in ELoadEnhancedFeatureInfoCmdId responses, for efficiency. |
|
96 Input None |
|
97 Output TFeatureInfoRespPckg |
|
98 */ |
|
99 ELoadFeatureInfoCmdId, |
|
100 |
|
101 /** |
|
102 FM uses this command to request feature information of |
|
103 features that have custom flags and user-data, that are known to the |
|
104 plug-in. Implementations should use this command to return such |
|
105 features, if any are known. If no such features are known to the |
|
106 plug-in it should leave with KErrNotSupported, hence this command is |
|
107 optional. |
|
108 Features contained in a response to this command should not appear |
|
109 in ELoadFeatureInfoCmdId responses, for efficiency. |
|
110 Input None |
|
111 Output TEnhancedFeatureInfoRespPckg |
|
112 */ |
|
113 ELoadEnhancedFeatureInfoCmdId |
|
114 }; |
|
115 |
|
116 /** |
|
117 Data structure used to list the features in data structure TFeatureInfo. |
|
118 Used in ELoadFeatureInfoCmdId commands. |
|
119 */ |
|
120 struct TFeature |
|
121 { |
|
122 // UID of the feature, as found in a system header file. |
|
123 TUint32 iFeatureID; |
|
124 |
|
125 // Value of the 'Supported?' feature flag. |
|
126 // If feature has been turned OFF from a product the value is set to |
|
127 // EFalse and if it has been turned ON the value is set to ETrue. |
|
128 TBool iValue; |
|
129 }; |
|
130 |
|
131 /** |
|
132 Data structure used to pass data with ELoadFeatureInfoCmdId response. |
|
133 Used in ELoadFeatureInfoCmdId commands. It contains the return code for |
|
134 the command iErrorCode and is typically: |
|
135 No leave, just returns - iList contains feature entries. |
|
136 KErrNotSuppoted - no features to report for this command. |
|
137 ... - other system wide error. |
|
138 */ |
|
139 struct TFeatureInfo |
|
140 { |
|
141 // System wide error code. |
|
142 TInt iErrorCode; |
|
143 |
|
144 // List of read-only feature entries. |
|
145 RArray<TFeature> iList; |
|
146 }; |
|
147 |
|
148 /** Data package for ELoadFeatureInfoCmdId response structure */ |
|
149 typedef TPckgBuf<TFeatureInfo> TFeatureInfoRespPckg; |
|
150 |
|
151 /** |
|
152 Data structure used to pass data with ELoadEnhancedFeatureInfoCmdId |
|
153 response. Used in ELoadEnhancedFeatureInfoCmdId commands. It contains the |
|
154 return code for the command iErrorCode and is typically: |
|
155 No leave, just returns - iList contains feature entries. |
|
156 KErrNotSuppoted - no features to report for this command. |
|
157 ... - other system wide error. |
|
158 @see RFeatureArray |
|
159 */ |
|
160 struct TEnhancedFeatureInfo |
|
161 { |
|
162 // System wide error code. |
|
163 TInt iErrorCode; |
|
164 |
|
165 // List of enhanced feature records. |
|
166 // List consists of TFeatureEntry entries. Plugin should initialize |
|
167 // feature ID and feature support status flag and optionally any other |
|
168 // feature flags as specified in TFeatureFlags. If feature has |
|
169 // associated user-data, it should be initialized for response as well. |
|
170 // If there is no user-data value this must be set to 0. |
|
171 // For type definitions see featurecmn.h |
|
172 RFeatureArray iList; |
|
173 }; |
|
174 |
|
175 /** Data package for ELoadEnhancedFeatureInfoCmdId response structure */ |
|
176 typedef TPckgBuf<TEnhancedFeatureInfo> TEnhancedFeatureInfoRespPckg; |
|
177 |
|
178 } // end namespace |
|
179 |
|
180 |
|
181 // CLASS DECLARATION |
|
182 |
|
183 /** |
|
184 This M-class is an interface class implemented by FM server to receive |
|
185 feature information responses from adaptation plug-ins i.e. they call the |
|
186 server back with the data. Reference supplied to the plugin implementation |
|
187 at construction and available in iResponseCallback. |
|
188 |
|
189 @see CFeatureInfoPlugin |
|
190 */ |
|
191 class MFeatureInfoPluginCallback |
|
192 { |
|
193 public: |
|
194 /** |
|
195 Method to return data in response to a message from |
|
196 a Feature Info plugin. The related ProcessCommandL call |
|
197 must return before this method can be called. |
|
198 |
|
199 @param aCommandId Command ID for which the response comes |
|
200 @param aTransId Transcation identifier of |
|
201 the original command |
|
202 @param aData Data returned from call. |
|
203 Data package contents are defined by command. |
|
204 Can be deleted right after |
|
205 ProcessResponseL has returned. |
|
206 */ |
|
207 virtual void ProcessResponseL( |
|
208 const FeatureInfoCommand::TFeatureInfoCmd aCommandId, |
|
209 const TUint8 aTransId, |
|
210 TDesC8& aData ) = 0; |
|
211 }; |
|
212 |
|
213 |
|
214 /** |
|
215 Feature Manager ECOM Plugin interface class to be implemented by adaptation. |
|
216 As it is an adaptation interface implementations are only loaded from ROM. |
|
217 |
|
218 Implementations of this interface are created by the Feature Manager server |
|
219 during start up in it's main thread where an Active Scheduler is installed. |
|
220 Implementations must perform minmial work in ProcessCommandL() and return. |
|
221 Plugin work and calls to ProcessResponseL() must be performed asynchronsly in |
|
222 an active object callback running in the server's main thread. |
|
223 |
|
224 For the command Ids and types used with this interface see definitions in the |
|
225 FeatureInfoCommand namespace. |
|
226 |
|
227 @see MFeatureInfoPluginCallback |
|
228 @see KFeatureInfoPluginInterfaceUid |
|
229 */ |
|
230 class CFeatureInfoPlugin : public CBase |
|
231 { |
|
232 public: // construction and destruction |
|
233 |
|
234 /** |
|
235 Constructor method for instance. |
|
236 Uses ECom to find correct instance. |
|
237 |
|
238 @param aImplementationUid UID of the interface |
|
239 implementation to instantiate. |
|
240 @param aResponseCallback Reference to plugin callback handler. |
|
241 */ |
|
242 inline static CFeatureInfoPlugin* NewL(TUid aImplementationUid, |
|
243 MFeatureInfoPluginCallback& aResponseCallback); |
|
244 |
|
245 /** |
|
246 Destructor |
|
247 */ |
|
248 inline virtual ~CFeatureInfoPlugin(); |
|
249 |
|
250 public: |
|
251 /** |
|
252 Method to invoke a particular command in the plugin. |
|
253 Response to method is returned via separate ProcessResponseL |
|
254 call. Call to ProcessResponseL is done after the call to |
|
255 ProcessCommandL returns. |
|
256 Leaves with error code KErrNotSupported if command ID is not |
|
257 supported by the plug-in. If ProcessCommandL leaves, no corresponding |
|
258 ProcessResponseL is expected. |
|
259 |
|
260 @param aCommandId Command ID |
|
261 @param aTransId Transaction ID |
|
262 @param aData Data associated with command. |
|
263 Data package contents are defined by command. |
|
264 Some commands require no data and pass |
|
265 empty buffer as aData. |
|
266 @leave KErrNotSupported aCommandId not supported by plug-in. |
|
267 */ |
|
268 virtual void ProcessCommandL( |
|
269 const FeatureInfoCommand::TFeatureInfoCmd aCommandId, |
|
270 const TUint8 aTransId, |
|
271 TDesC8& aData ) = 0; |
|
272 |
|
273 |
|
274 protected: |
|
275 /** |
|
276 Callback pointer to be used with responses to commands. |
|
277 This pointer is not owned by this class. |
|
278 */ |
|
279 MFeatureInfoPluginCallback* iResponseCallback; // not owned |
|
280 |
|
281 private: |
|
282 /** Destructor identifier to be used with ECom framework. */ |
|
283 TUid iDestructorIDKey; |
|
284 }; |
|
285 |
|
286 #include <featmgr/featureinfoplugin.inl> |
|
287 |
|
288 #endif // FEATUREINFOPLUGIN_H |
|
289 |
|
290 // End of File |