Feature Manager Guide

About Feature Manager

Third party developers using the SDK only have the ability to report the availability of features.

Feature Manager supersedes the component Feature Registry in earlier versions of Symbian platform. Feature Manager has the capacity to modify feature flags at runtime. Feature Registry lacked this capacity and is now deprecated.

What is a feature?

A feature can be any item of functionality supplied with a phone. Examples of features include:

• the presence or absence of particular hardware, for instance the presence of an MMC slot,

• the presence or absence of a particular software component, DLL or individual function, or

• the presence or absence of a network connection.

How is a feature included?

A feature may be included on a phone in various ways:

• at phone build time,

• when software is installed after the build, or

• when functionality such as a connection is discovered at run time.

Features may be queried, enabled, disabled and modified.

What functionality is supplied with Feature Manager?

Two subsets of functionality are published: a minimal one for third parties is supplied with the SDK, and a fuller one is published to Symbian partners. The third party SDK requires the CFeatureDiscovery class to be used, while partners also have the RFeatureControl. WriteDeviceData capability is required to use RFeatureControl to modify feature flags.

How are features represented?

Every feature is assigned a unique Uid which the Feature Manager API uses to access it. Full data about a feature is held in the class TFeatureEntry, which contains the Uid, the status of the feature, and feature data.

The status of a feature is the availability of the feature. A feature may be:

• supported, meaning that the feature is present or supported on the device,

• modifiable, meaning that the feature may be modified using the API,

• blacklisted, meaning that the feature is frozen and may not be overridden in later ROM section, or via a plugin, or through the API,

• uninitialised, meaning that the supported status was not set at device creation, and

• persisted, meaning that the feature will be persisted so as to be restored on restart.

The status of a feature is represented by a 32-bit integer whose bits are boolean flags named in the enumeration TFeatureFlags. Some combinations of features cannot be true simultaneously either at build time or run time: for instance EFeatureUninitialised is incompatible with EFeatureModifiable or EFeaturePersisted.

Feature data is user-defined data referring to the feature. Feature data is held in a 32-bit integer which is usually a reference to a repository or database.

A group of features is represented by an array. The individual features may be identified simply by their Uids, in which case you use the data type RFeatureUidArray, which is an array of TUid. They may also be represented as TFeatureEntry objects, in which case you use the data type RFeatureArray, which is an array of TFeatureEntry objects.

How are features queried and modified?

Feature Manager provides two classes which you use to interface to the feature tags database to query the existence and status of a feature:

• CFeatureDiscovery

• RFeatureControl

CFeatureDiscovery is an active object which can only be used to query features and is supplied to third-party developers. RFeatureControl is used to query features and to modify their status and associated data: it is only supplied to Symbian partners. Both classes use Uids and TFeatureEntry to access feature data. RFeatureControl is always used dynamically: that is you must construt an instance and call its functions within the lifetime of that instance. RFeatureControl has more powerful functionality but CFeatureDiscovery allows static calls which can be more efficient. CFeatureDiscovery must only be used by clients which can support leaving code: otherwise they must use RFeatureControl.

Notification of change to features

The capability to modify feature status and feature data at runtime creates the need for notification of such changes. CFeatureNotifier provides functions to set up and cancel notification of various types of change to a given feature. The interface MFeatureObserver defines functionality for handling changes: the exact way in which change is handled depends on the implementation. The notification functions of RFeatureControl are called from within an implementation of MFeatureObserver.