2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
22 #ifndef FEATURECONTROL_H
23 #define FEATURECONTROL_H
28 #include <featmgr/featurecmn.h>
30 // FORWARD DECLARATIONS
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.
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.
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
59 The meaning of the bits of the 32-bit feature status flags are as follows:
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
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.
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 ).
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.
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.
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.
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.
113 NONSHARABLE_CLASS(RFeatureControl)
117 C++ default constructor.
119 IMPORT_C RFeatureControl();
122 Connect() must be called before calling any other methods of
124 It connects to the Feature Manager Server.
125 After usage Close() function must be called.
127 @return Error Code. One of the Symbian error codes.
129 @deprecated Use Open() instead.
131 IMPORT_C TInt Connect();
134 Open() must be called before calling any other methods of
136 After usage Close() function must be called.
138 @return Error Code. One of the Symbian error codes.
140 IMPORT_C TInt Open();
143 Remember to call Close after using RFeatureControl.
145 IMPORT_C void Close();
148 This method returns the supported status on the device of the feature
149 specified in the aFeature parameter.
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.
160 IMPORT_C TInt FeatureSupported( TUid aFeature );
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.
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
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.
182 IMPORT_C TInt FeatureSupported( TFeatureEntry& aFeature );
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.
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.
203 IMPORT_C TInt FeaturesSupported( RFeatureArray& aFeatures );
206 Enables the specified feature. WriteDeviceData capability required.
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.
218 IMPORT_C TInt EnableFeature( TUid aFeature );
221 Disables the specified feature. WriteDeviceData capability required.
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.
233 IMPORT_C TInt DisableFeature( TUid aFeature );
236 Enables or disables the specified feature and sets feature data.
237 WriteDeviceData capability required.
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.
251 IMPORT_C TInt SetFeature( TUid aFeature, TBool aEnabled, TUint32 aData );
254 Sets feature data. WriteDeviceData capability required.
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.
267 IMPORT_C TInt SetFeature( TUid aFeature, TUint32 aData );
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.
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
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
285 KErrNoMemory if out-of-memory occured during caching.
286 Otherwise one of the Symbian error codes.
291 IMPORT_C TInt AddFeature( TFeatureEntry& aFeature );
295 Note: WriteDeviceData capability required.
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.
311 IMPORT_C TInt DeleteFeature( TUid aFeature );
314 Lists all supported features.
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.
326 IMPORT_C TInt ListSupportedFeatures( RFeatureUidArray& aSupportedFeatures );
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.
336 @return Error code. KErrNone if Feature Manager has accepted the request to use
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.
342 IMPORT_C TInt SWIStart();
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.
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
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.
366 IMPORT_C TInt SWIEnd();
371 Used for resource counting.
376 Reserved for future use. Initialised to 0 on construction.
381 Reserved for future use. Initialised to 0 on construction.
389 // replace <featureUID> with a real UID )
391 #include <featmgr/featurecontrol.h>
392 #include <featmgr/featureinfo.h> // for feature definitions
394 CMyClass::MyMethodL()
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();
402 if ( err == KErrNone )
404 // Query multiple features statuses (single IPC-call, so less overhead)
407 CleanupClosePushL(uids);
409 uids.AppendL( KFeatureUid1 );
410 uids.AppendL( KFeatureUid2 );
411 TInt err = control.FeaturesSupported( uids );
413 if ( err == KErrNone )
417 index = uids.Find( KFeatureUid1 );
418 if(index == KErrNotFound)
420 // Feature does not exist (result is analogous if KFeatureUid1
421 // is not appended in uids array before query).
425 iFeature1Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
428 index = uids.Find( KFeatureUid2 );
429 if(index == KErrNotFound)
431 // Feature does not exist (result is analogous if KFeatureUid2
432 // is not appended in uids array before query).
436 TBool feature2Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
437 TUint32 data = uids[index].FeatureData();
438 // Do something with support-information and data
442 CleanupStack::PopAndDestroy(&uids);
445 // Query single feature status
447 err = control.FeatureSupported( KFeatureUid3 );
448 if( err == KFeatureSupported )
450 // do something with enabled feature
454 // Query single feature status and data
456 TFeatureEntry entry( KFeatureUid4 );
457 err = control.FeatureSupported( entry );
458 if( err == KFeatureSupported )
460 TUint32 data = entry.FeatureData();
461 // do something with enabled feature's data
463 else if( err == KFeatureUnsupported )
465 // do or do not something with disabled feature's data
469 // Enable some feature.
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> );
482 // List all supported features.
484 // A client owned RFeatureUidArray array which will be filled with
485 // the UIDs of supported features.
486 RFeatureUidArray supportedFeatures;
488 // ListSupportedFeatures() returns one of the Symbian error codes.
489 err = featureControl.ListSupportedFeatures( supportedFeatures );
493 // Closes the array and frees all memory allocated to the array.
494 supportedFeatures.Close();
497 // Remember to call CloseL after using RFeatureControl.
498 // It disconnects the Feature Manager server.
499 featureControl.Close();
506 #endif // FEATURECONTROL_H