| class RFeatureControl |
The Feature Control API provides methods that can be used to query which features are supported on the device. The API also provides methods to get status flags that define that behaviour of the feature flag and data associated with the feature.
The Feature Control API provides methods to enable and disable features at runtime e.g. when new software is installed or uninstalled. The API provides also methods for setting feature data, adding a new feature to the device and listing all supported features on the device.
It is only possible to enable or disable a feature or set feature data at runtime if that feature is modifiable (this is defined by the status 32 bit word associated with the feature flag). It is also possible to enable or disable a feature UID that is not even defined in the device yet. When adding a new feature to the device status flags and data of the feature must be set.
The meaning of the bits of the 32-bit feature status flags are as follows:
0 Supported If set, feature is supported and available for use; if not, feature is not supported.
1 Upgradeable If set, feature is upgradeable. The feature is known to the device but it must be upgraded to enable it. If a feature is blacklisted, its upgradeable flag is unset.
2 Modifiable If set, the feature is modifiable and may be enabled/disabled at run-time. The initial flag values for such a feature flag are defined in a ROM image obey file.
3 Blacklisted If set, the feature has been blacklisted, and may not be changed at run-time. This also prevents a feature from being upgraded.
4 Uninitialised If set, the status flag Supported is unknown at build-time and is initialised at run-time by system software. The Feature Manager will ignore the Supported flag in the file. A run-time call to RFeatureControl will be needed to set the feature's supported flag. Look ups of uninitialised features result in a KErrNotReady error code.
5 Persisted If set, this flag is saved to the system drive when modified preserving its value across reboots/power downs
6 ..23 Reserved for future use, always zero.
24..31 Reserved for internal use.
Enumeration TFeatureFlags defined in featurecmn.h should be used for accessing feature status flags e.g. flags.IsSet( EFeatureUpgradeable ), flags.IsSet( EFeatureModifiable ).
Feature data is 32-bit word for client read and write. Feature data can contain any data that needs to be associated with the Feature Flag. Feature data can only be set if the feature is modifiable or a new feature.
The use of the Feature Manager API to set the supported status of a feature, it in no way means that the functionality itself is modified on the device. All the corresponding DLLs, including feature functionality and resources still remain on the device. To properly support runtime activation/deactivation of the feature, all feature APIs need to implement runtime checking of the feature status in their code.
The API consists of the RFeatureControl class which is used together with feature UIDs defined in featureUIDs.h, TFeatureFlags, TFeatureEntry and RFeatureUidArray defined in featurecmn.h.
Usage:
Before calling any other methods the client must call the Open() method that connects to the Feature Manager Server. When the client has finished using the RFeatureControl it should disconnect using the Close() method.
| Public Member Functions | |
|---|---|
| RFeatureControl() | |
| IMPORT_C TInt | AddFeature(TFeatureEntry &) |
| IMPORT_C void | Close() |
| IMPORT_C TInt | Connect() |
| IMPORT_C TInt | DeleteFeature(TUid) |
| IMPORT_C TInt | DisableFeature(TUid) |
| IMPORT_C TInt | EnableFeature(TUid) |
| IMPORT_C TInt | FeatureSupported(TUid) |
| IMPORT_C TInt | FeatureSupported(TFeatureEntry &) |
| IMPORT_C TInt | FeaturesSupported(RFeatureArray &) |
| IMPORT_C TInt | ListSupportedFeatures(RFeatureUidArray &) |
| IMPORT_C TInt | Open() |
| IMPORT_C TInt | SWIEnd() |
| IMPORT_C TInt | SWIStart() |
| IMPORT_C TInt | SetFeature(TUid, TBool, TUint32) |
| IMPORT_C TInt | SetFeature(TUid, TUint32) |
| Private Attributes | |
|---|---|
| TBool | iInitialized |
| TUint32 | iReserved1 |
| TUint32 | iReserved2 |
| IMPORT_C TInt | AddFeature | ( | TFeatureEntry & | aFeature | ) |
Adds a new feature and sets status flags and data of the feature. Note: When adding a new feature to the device status flags and data of the feature must be set. WriteDeviceData capability required.
| TFeatureEntry & aFeature | A reference to a client owned TFeatureEntry object. Must contain UID, status flags and data of the feature. |
| IMPORT_C TInt | Connect | ( | ) |
Connect() must be called before calling any other methods of RFeatureControl. It connects to the Feature Manager Server. After usage Close() function must be called.
Use Open() instead.
| IMPORT_C TInt | DeleteFeature | ( | TUid | aFeature | ) |
Deletes a feature. Note: WriteDeviceData capability required.
| TUid aFeature | Feature UID. |
| IMPORT_C TInt | DisableFeature | ( | TUid | aFeature | ) |
Disables the specified feature. WriteDeviceData capability required.
| TUid aFeature | Feature UID. |
| IMPORT_C TInt | EnableFeature | ( | TUid | aFeature | ) |
Enables the specified feature. WriteDeviceData capability required.
| TUid aFeature | Feature UID. |
| IMPORT_C TInt | FeatureSupported | ( | TUid | aFeature | ) |
This method returns the supported status on the device of the feature specified in the aFeature parameter.
| TUid aFeature | Feature UID. |
| IMPORT_C TInt | FeatureSupported | ( | TFeatureEntry & | aFeature | ) |
This method returns the supported status on the device of the feature described by the aFeature parameter. The feature UID should be set in TFeatureEntry class before the FeatureSupported method is called. If FeatureSupported returns successufully the TFeatureEntry parameter will also have been populated with the feature's status flags and the data word associates with the feature.
| TFeatureEntry & aFeature | A reference to a a client owned TFeatureEntry object. Must contain UID of the queried feature. After returning contains status flags and data of the feature. |
| IMPORT_C TInt | FeaturesSupported | ( | RFeatureArray & | aFeatures | ) |
This method allows the user to pass an array of type TFeatureEntry to Feature Manager. In this way the user can retrieve the supported status and associated information for the features whose UIDs have been set in TFeatureEntry classes. In order for the client to know whether feature is just disabled or does not exist at all it must check this from response feature array. If the feature exists the EFeatureSupported status bit will contain the support status. If the feature does not exist it will be removed from array after the query. For this reason instead of hard coding array accesses for features the Find method should always be used to query feature index in array after query.
| RFeatureArray & aFeatures | A reference to a a client owned RFeatureArray array. Must contain UIDs of the queried features. |
| IMPORT_C TInt | ListSupportedFeatures | ( | RFeatureUidArray & | aSupportedFeatures | ) |
Lists all supported features.
| RFeatureUidArray & aSupportedFeatures | A reference to a client owned RFeatureUidArray array which will be filled with the UIDs of supported features. |
| IMPORT_C TInt | Open | ( | ) |
Open() must be called before calling any other methods of RFeatureControl. After usage Close() function must be called.
| IMPORT_C TInt | SWIEnd | ( | ) |
Mandates Feature Manager to stop caching and prepare to commit the cached feature manipulations performed by the executable launched by SWI during installation into Feature Manager. The cached features are committed only after that installation of the executable is successfully completed. This API must be called before a timeout managed by Feature Manager times out. Otherwise the cached features will be dumped.
| IMPORT_C TInt | SWIStart | ( | ) |
Calling this method informs Feature Manager that a software installer (SWI) launched executable is going to set, add, delete, enable or disable features in Feature Manager. This mandates Feature Manager to cache all modification calls issued by that executable until a call to SWIEnd is made to commit them to Feature Manager. This prevents against situations where the installation is user-aborted without being able to roll back direct feature manipulations.
| IMPORT_C TInt | SetFeature | ( | TUid | aFeature, |
| TBool | aEnabled, | |||
| TUint32 | aData | |||
| ) | ||||
Enables or disables the specified feature and sets feature data. WriteDeviceData capability required.
| IMPORT_C TInt | SetFeature | ( | TUid | aFeature, |
| TUint32 | aData | |||
| ) | ||||
Sets feature data. WriteDeviceData capability required.
| TUint32 | iReserved1 | [private] |
Reserved for future use. Initialised to 0 on construction.
| TUint32 | iReserved2 | [private] |
Reserved for future use. Initialised to 0 on construction.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.