|
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 |
|
21 |
|
22 #ifndef FEATURECONTROL_H |
|
23 #define FEATURECONTROL_H |
|
24 |
|
25 // INCLUDES |
|
26 #include <e32std.h> |
|
27 #include <e32svr.h> |
|
28 #include <featmgr/featurecmn.h> |
|
29 |
|
30 // FORWARD DECLARATIONS |
|
31 |
|
32 // DEFINES |
|
33 |
|
34 // CLASS DECLARATION |
|
35 |
|
36 // CONSTANTS |
|
37 |
|
38 // MACROS |
|
39 |
|
40 /** |
|
41 |
|
42 The Feature Control API provides methods that can be used to query which |
|
43 features are supported on the device. The API also provides methods to |
|
44 get status flags that define that behaviour of the feature flag and data |
|
45 associated with the feature. |
|
46 |
|
47 The Feature Control API provides methods to enable and disable features at |
|
48 runtime e.g. when new software is installed or uninstalled. The API provides |
|
49 also methods for setting feature data, adding a new feature to the device |
|
50 and listing all supported features on the device. |
|
51 |
|
52 It is only possible to enable or disable a feature or set feature data |
|
53 at runtime if that feature is modifiable (this is defined by the status |
|
54 32 bit word associated with the feature flag). It is also possible to enable or |
|
55 disable a feature UID that is not even defined in the device yet. |
|
56 When adding a new feature to the device status flags and data of the feature |
|
57 must be set. |
|
58 |
|
59 The meaning of the bits of the 32-bit feature status flags are as follows: |
|
60 |
|
61 Bit Flag Name Meaning |
|
62 - 0 Supported If set, feature is supported and available for use; |
|
63 if not, feature is not supported. |
|
64 - 1 Upgradeable If set, feature is upgradeable. The feature is known to |
|
65 the device but it must be upgraded to enable it. If a feature |
|
66 is blacklisted, its upgradeable flag is unset. |
|
67 - 2 Modifiable If set, the feature is modifiable and may be enabled/disabled at |
|
68 run-time. The initial flag values for such a feature flag are |
|
69 defined in a ROM image obey file. |
|
70 - 3 Blacklisted If set, the feature has been blacklisted, and may not be changed |
|
71 at run-time. This also prevents a feature from being upgraded. |
|
72 - 4 Uninitialised If set, the status flag Supported is unknown at build-time and is |
|
73 initialised at run-time by system software. The Feature Manager |
|
74 will ignore the Supported flag in the file. A run-time call to |
|
75 RFeatureControl will be needed to set the feature's supported |
|
76 flag. Look ups of uninitialised features result in a KErrNotReady |
|
77 error code. |
|
78 - 5 Persisted If set, this flag is saved to the system drive when modified |
|
79 preserving its value across reboots/power downs |
|
80 - 6 ..23 Reserved for future use, always zero. |
|
81 - 24..31 Reserved for internal use. |
|
82 |
|
83 Enumeration TFeatureFlags defined in featurecmn.h should be used for |
|
84 accessing feature status flags e.g. flags.IsSet( EFeatureUpgradeable ), |
|
85 flags.IsSet( EFeatureModifiable ). |
|
86 |
|
87 Feature data is 32-bit word for client read and write. Feature data can |
|
88 contain any data that needs to be associated with the Feature Flag. |
|
89 Feature data can only be set if the feature is modifiable or a new feature. |
|
90 |
|
91 The use of the Feature Manager API to set the supported status of a feature, |
|
92 it in no way means that the functionality itself is modified on the device. |
|
93 All the corresponding DLLs, including feature functionality and resources still |
|
94 remain on the device. To properly support runtime activation/deactivation |
|
95 of the feature, all feature APIs need to implement runtime checking of the |
|
96 feature status in their code. |
|
97 |
|
98 The API consists of the RFeatureControl class which is |
|
99 used together with feature UIDs defined in featureUIDs.h, TFeatureFlags, |
|
100 TFeatureEntry and RFeatureUidArray defined in featurecmn.h. |
|
101 |
|
102 |
|
103 Usage: |
|
104 |
|
105 Before calling any other methods the client must call the Open() |
|
106 method that connects to the Feature Manager Server. |
|
107 When the client has finished using the RFeatureControl it should |
|
108 disconnect using the Close() method. |
|
109 |
|
110 @publishedPartner |
|
111 @released |
|
112 */ |
|
113 NONSHARABLE_CLASS(RFeatureControl) |
|
114 { |
|
115 public: |
|
116 /** |
|
117 C++ default constructor. |
|
118 */ |
|
119 IMPORT_C RFeatureControl(); |
|
120 |
|
121 /** |
|
122 Connect() must be called before calling any other methods of |
|
123 RFeatureControl. |
|
124 It connects to the Feature Manager Server. |
|
125 After usage Close() function must be called. |
|
126 |
|
127 @return Error Code. One of the Symbian error codes. |
|
128 |
|
129 @deprecated Use Open() instead. |
|
130 */ |
|
131 IMPORT_C TInt Connect(); |
|
132 |
|
133 /** |
|
134 Open() must be called before calling any other methods of |
|
135 RFeatureControl. |
|
136 After usage Close() function must be called. |
|
137 |
|
138 @return Error Code. One of the Symbian error codes. |
|
139 */ |
|
140 IMPORT_C TInt Open(); |
|
141 |
|
142 /** |
|
143 Remember to call Close after using RFeatureControl. |
|
144 */ |
|
145 IMPORT_C void Close(); |
|
146 |
|
147 /** |
|
148 This method returns the supported status on the device of the feature |
|
149 specified in the aFeature parameter. |
|
150 |
|
151 @param aFeature Feature UID. |
|
152 @return KFeatureSupported if the feature is supported. |
|
153 KFeatureUnsupported if the feature is not supported. |
|
154 KErrNotFound if the feature does not exist. |
|
155 KErrNotReady it the feature is uninitialized. |
|
156 Otherwise one of the Symbian error codes. |
|
157 |
|
158 |
|
159 */ |
|
160 IMPORT_C TInt FeatureSupported( TUid aFeature ); |
|
161 |
|
162 /** |
|
163 This method returns the supported status on the device of the feature |
|
164 described by the aFeature parameter. The feature UID should be set in |
|
165 TFeatureEntry class before the FeatureSupported method is called. If |
|
166 FeatureSupported returns successufully the TFeatureEntry parameter will |
|
167 also have been populated with the feature's status flags and the data |
|
168 word associates with the feature. |
|
169 |
|
170 @param aFeature A reference to a a client owned TFeatureEntry object. |
|
171 Must contain UID of the queried feature. |
|
172 After returning contains status flags and data of |
|
173 the feature. |
|
174 @return KFeatureSupported if the feature is supported. |
|
175 KFeatureUnsupported if the feature is not supported. |
|
176 KErrNotFound if the feature does not exist. |
|
177 KErrNotReady if the feature is uninitialized. |
|
178 Otherwise one of the Symbian error codes. |
|
179 |
|
180 |
|
181 */ |
|
182 IMPORT_C TInt FeatureSupported( TFeatureEntry& aFeature ); |
|
183 |
|
184 /** |
|
185 This method allows the user to pass an array of type TFeatureEntry |
|
186 to Feature Manager. In this way the user can retrieve the supported status and |
|
187 associated information for the features whose UIDs have been set in |
|
188 TFeatureEntry classes. In order for the client to know whether |
|
189 feature is just disabled or does not exist at all it must check |
|
190 this from response feature array. If the feature exists the EFeatureSupported |
|
191 status bit will contain the support status. If the feature does not exist |
|
192 it will be removed from array after the query. For this reason instead of hard |
|
193 coding array accesses for features the Find method should always |
|
194 be used to query feature index in array after query. |
|
195 |
|
196 @param aFeatures A reference to a a client owned RFeatureArray array. |
|
197 Must contain UIDs of the queried features. |
|
198 @return KErrNone if fetching of features statuses successful. |
|
199 KErrArgument if query made with empty array. |
|
200 Otherwise one of the Symbian error codes. |
|
201 |
|
202 */ |
|
203 IMPORT_C TInt FeaturesSupported( RFeatureArray& aFeatures ); |
|
204 |
|
205 /** |
|
206 Enables the specified feature. WriteDeviceData capability required. |
|
207 |
|
208 @param aFeature Feature UID. |
|
209 @return Error Code. KErrNone if the feature was succesfully enabled. |
|
210 KErrAccessDenied if the feature is not modifiable. |
|
211 KErrPermissionDenied if a capability check fails. |
|
212 KErrNotFound if the feature does not exist. |
|
213 KErrArgument if the maximum number of cached features |
|
214 during a Software Installer (SWI) install/uninstall |
|
215 session has been exceeded. |
|
216 Otherwise one of the Symbian error codes. |
|
217 */ |
|
218 IMPORT_C TInt EnableFeature( TUid aFeature ); |
|
219 |
|
220 /** |
|
221 Disables the specified feature. WriteDeviceData capability required. |
|
222 |
|
223 @param aFeature Feature UID. |
|
224 @return Error Code. KErrNone if the feature was succesfully disabled. |
|
225 KErrAccessDenied if the feature is not modifiable. |
|
226 KErrPermissionDenied if a capability check fails. |
|
227 KErrNotFound if the feature does not exist. |
|
228 KErrArgument if the maximum number of cached features |
|
229 during a Software Installer (SWI) install/uninstall |
|
230 session has been exceeded. |
|
231 Otherwise one of the Symbian error codes. |
|
232 */ |
|
233 IMPORT_C TInt DisableFeature( TUid aFeature ); |
|
234 |
|
235 /** |
|
236 Enables or disables the specified feature and sets feature data. |
|
237 WriteDeviceData capability required. |
|
238 |
|
239 @param aFeature Feature UID. |
|
240 @param aEnabled ETrue if enabling the feature, EFalse if disabling. |
|
241 @param aData Feature data. |
|
242 @return Error Code. KErrNone if the feature was succesfully enabled. |
|
243 KErrAccessDenied if the feature is not modifiable. |
|
244 KErrPermissionDenied if a capability check fails. |
|
245 KErrNotFound if the feature does not exist. |
|
246 KErrArgument if the maximum number of cached features |
|
247 during a Software Installer (SWI) install/uninstall |
|
248 session has been exceeded. |
|
249 Otherwise one of the Symbian error codes. |
|
250 */ |
|
251 IMPORT_C TInt SetFeature( TUid aFeature, TBool aEnabled, TUint32 aData ); |
|
252 |
|
253 /** |
|
254 Sets feature data. WriteDeviceData capability required. |
|
255 |
|
256 @param aFeature Feature UID. |
|
257 @param aData Feature data. |
|
258 @return Error Code. KErrNone if the feature data was succesfully set. |
|
259 KErrAccessDenied if the feature is not modifiable. |
|
260 KErrPermissionDenied if a capability check fails. |
|
261 KErrNotFound if the feature does not exist. |
|
262 KErrArgument if the maximum number of cached features |
|
263 during a Software Installer (SWI) install/uninstall |
|
264 session has been exceeded. |
|
265 Otherwise one of the Symbian error codes. |
|
266 */ |
|
267 IMPORT_C TInt SetFeature( TUid aFeature, TUint32 aData ); |
|
268 |
|
269 /** |
|
270 Adds a new feature and sets status flags and data of the feature. |
|
271 Note: When adding a new feature to the device status flags and |
|
272 data of the feature must be set. WriteDeviceData capability required. |
|
273 |
|
274 @param aFeature A reference to a client owned TFeatureEntry object. |
|
275 Must contain UID, status flags and data of the feature. |
|
276 @return Error Code. KErrNone if the feature was succesfully added. |
|
277 KErrPermissionDenied if capability check fails. |
|
278 KErrAlreadyExists if the feature already exists |
|
279 in the device. |
|
280 KErrArgument if the maximum number of cached features |
|
281 during a Software Installer (SWI) install/uninstall |
|
282 session has been exceeded, or when "out of memory" |
|
283 occured in a previous call to this function during |
|
284 the caching process. |
|
285 KErrNoMemory if out-of-memory occured during caching. |
|
286 Otherwise one of the Symbian error codes. |
|
287 |
|
288 @see TFeatureEntry |
|
289 @see TFeatureFlags |
|
290 */ |
|
291 IMPORT_C TInt AddFeature( TFeatureEntry& aFeature ); |
|
292 |
|
293 /** |
|
294 Deletes a feature. |
|
295 Note: WriteDeviceData capability required. |
|
296 |
|
297 @param aFeature Feature UID. |
|
298 @return Error Code. KErrNone if the feature was successfully deleted. |
|
299 KErrAccessDenied if the feature is not runtime. |
|
300 KErrPermissionDenied if capability check fails. |
|
301 KErrNotFound if the feature does not exist. |
|
302 KErrArgument if the maximum number of cached features |
|
303 during a Software Installer (SWI) install/uninstall |
|
304 session has been exceeded. |
|
305 KErrNoMemory if out-of-memory occured during caching. |
|
306 Otherwise one of the Symbian error codes. |
|
307 |
|
308 @see TFeatureEntry |
|
309 @see TFeatureFlags |
|
310 */ |
|
311 IMPORT_C TInt DeleteFeature( TUid aFeature ); |
|
312 |
|
313 /** |
|
314 Lists all supported features. |
|
315 |
|
316 @param aSupportedFeatures A reference to a client owned RFeatureUidArray array which |
|
317 will be filled with the UIDs of supported features. |
|
318 @return Error code. KErrNone if client owned array was successfully |
|
319 filled with IDs of supported features. |
|
320 KErrServerBusy if there was ongoing enabling or |
|
321 disabling of some feature(s) and Feature Manager Server |
|
322 could not return unambiguous list of supported features. |
|
323 KErrNoMemory if out-of-memory occured during caching. |
|
324 Otherwise one of the Symbian error codes. |
|
325 */ |
|
326 IMPORT_C TInt ListSupportedFeatures( RFeatureUidArray& aSupportedFeatures ); |
|
327 |
|
328 /** |
|
329 Calling this method informs Feature Manager that a software installer (SWI) |
|
330 launched executable is going to set, add, delete, enable or disable features |
|
331 in Feature Manager. This mandates Feature Manager to cache all modification |
|
332 calls issued by that executable until a call to SWIEnd is made to commit them |
|
333 to Feature Manager. This prevents against situations where the installation is |
|
334 user-aborted without being able to roll back direct feature manipulations. |
|
335 |
|
336 @return Error code. KErrNone if Feature Manager has accepted the request to use |
|
337 the caching APIs. |
|
338 KErrInUse if the caching APIs are already in use by another |
|
339 exe launched by the SWI. |
|
340 KErrNotReady if there is no software installation in progress. |
|
341 */ |
|
342 IMPORT_C TInt SWIStart(); |
|
343 |
|
344 /** |
|
345 Mandates Feature Manager to stop caching and prepare to commit the cached |
|
346 feature manipulations performed by the executable launched by SWI during |
|
347 installation into Feature Manager. The cached features are committed only |
|
348 after that installation of the executable is successfully completed. |
|
349 This API must be called before a timeout managed by Feature Manager times |
|
350 out. Otherwise the cached features will be dumped. |
|
351 |
|
352 @return Error code. KErrNone when SWIEnd call is received by a client or when an abort occurs |
|
353 prior to the timeout managed by Feature Manager expires. |
|
354 KErrNotReady if SWIStart was not called before calling this |
|
355 function, or because the timeout managed by Feature Manager |
|
356 had timed out. |
|
357 KErrGeneral an indication that an out-of-memory condition |
|
358 was encountered during caching which will force FeatMgr to |
|
359 disregard the whole cache. |
|
360 KErrNoMemory if an out-of-memory condition was encountered |
|
361 whilst reserving memory in the features list for the new |
|
362 features t be added, or if an out-of-memory occured in a call |
|
363 to AddFeaure() during caching.. |
|
364 Otherwise one of the Symbian error codes. |
|
365 */ |
|
366 IMPORT_C TInt SWIEnd(); |
|
367 |
|
368 private: |
|
369 |
|
370 /** |
|
371 Used for resource counting. |
|
372 */ |
|
373 TBool iInitialized; |
|
374 |
|
375 /** |
|
376 Reserved for future use. Initialised to 0 on construction. |
|
377 */ |
|
378 TUint32 iReserved1; |
|
379 |
|
380 /** |
|
381 Reserved for future use. Initialised to 0 on construction. |
|
382 */ |
|
383 TUint32 iReserved2; |
|
384 |
|
385 }; |
|
386 |
|
387 /** |
|
388 @code |
|
389 // replace <featureUID> with a real UID ) |
|
390 |
|
391 #include <featmgr/featurecontrol.h> |
|
392 #include <featmgr/featureinfo.h> // for feature definitions |
|
393 |
|
394 CMyClass::MyMethodL() |
|
395 { |
|
396 // Replace KFeatureUidx with real feature uid. |
|
397 // Open() must be called before calling any other methods. |
|
398 // Disconnect is done by calling the Close() method. |
|
399 RFeatureControl featureControl; |
|
400 TInt err = featureControl.Open(); |
|
401 |
|
402 if ( err == KErrNone ) |
|
403 { |
|
404 // Query multiple features statuses (single IPC-call, so less overhead) |
|
405 |
|
406 RFeatureArray uids; |
|
407 CleanupClosePushL(uids); |
|
408 |
|
409 uids.AppendL( KFeatureUid1 ); |
|
410 uids.AppendL( KFeatureUid2 ); |
|
411 TInt err = control.FeaturesSupported( uids ); |
|
412 |
|
413 if ( err == KErrNone ) |
|
414 { |
|
415 TInt index; |
|
416 |
|
417 index = uids.Find( KFeatureUid1 ); |
|
418 if(index == KErrNotFound) |
|
419 { |
|
420 // Feature does not exist (result is analogous if KFeatureUid1 |
|
421 // is not appended in uids array before query). |
|
422 } |
|
423 else |
|
424 { |
|
425 iFeature1Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported ); |
|
426 } |
|
427 |
|
428 index = uids.Find( KFeatureUid2 ); |
|
429 if(index == KErrNotFound) |
|
430 { |
|
431 // Feature does not exist (result is analogous if KFeatureUid2 |
|
432 // is not appended in uids array before query). |
|
433 } |
|
434 else |
|
435 { |
|
436 TBool feature2Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported ); |
|
437 TUint32 data = uids[index].FeatureData(); |
|
438 // Do something with support-information and data |
|
439 ... |
|
440 } |
|
441 } |
|
442 CleanupStack::PopAndDestroy(&uids); |
|
443 |
|
444 |
|
445 // Query single feature status |
|
446 |
|
447 err = control.FeatureSupported( KFeatureUid3 ); |
|
448 if( err == KFeatureSupported ) |
|
449 { |
|
450 // do something with enabled feature |
|
451 } |
|
452 |
|
453 |
|
454 // Query single feature status and data |
|
455 |
|
456 TFeatureEntry entry( KFeatureUid4 ); |
|
457 err = control.FeatureSupported( entry ); |
|
458 if( err == KFeatureSupported ) |
|
459 { |
|
460 TUint32 data = entry.FeatureData(); |
|
461 // do something with enabled feature's data |
|
462 } |
|
463 else if( err == KFeatureUnsupported ) |
|
464 { |
|
465 // do or do not something with disabled feature's data |
|
466 } |
|
467 |
|
468 |
|
469 // Enable some feature. |
|
470 |
|
471 // EnableFeature() and DisableFeature() methods return |
|
472 // KErrNone if the feature was succesfully enabled or disabled, |
|
473 // KErrAccessDenied if the feature is not modifiable. |
|
474 // KErrPermissionDenied a capability check fails, |
|
475 // KErrNotFound if the feature does not exist and |
|
476 // otherwise one of the Symbian error codes. |
|
477 err = featureControl.EnableFeature( <featureUID> ); |
|
478 |
|
479 // do something |
|
480 |
|
481 |
|
482 // List all supported features. |
|
483 |
|
484 // A client owned RFeatureUidArray array which will be filled with |
|
485 // the UIDs of supported features. |
|
486 RFeatureUidArray supportedFeatures; |
|
487 |
|
488 // ListSupportedFeatures() returns one of the Symbian error codes. |
|
489 err = featureControl.ListSupportedFeatures( supportedFeatures ); |
|
490 |
|
491 // do something |
|
492 |
|
493 // Closes the array and frees all memory allocated to the array. |
|
494 supportedFeatures.Close(); |
|
495 |
|
496 |
|
497 // Remember to call CloseL after using RFeatureControl. |
|
498 // It disconnects the Feature Manager server. |
|
499 featureControl.Close(); |
|
500 } |
|
501 |
|
502 } |
|
503 @endcode |
|
504 */ |
|
505 |
|
506 #endif // FEATURECONTROL_H |
|
507 |
|
508 // End of File |