Optional Features Notification API

Interface class and linkage

A Notify API is provided by the RFeatureRegistryNotify class, declared in featreg.h, supplied by featreg.dll and linked through featreg.lib.

Subscribing for notification of feature changes

The RFeatureRegistryNotify class has the following member functions that allow you to subscribe for notification of changes in the Feature Registry:

inline RFeatureRegistryNotify();
TInt Open();
void Subscribe(TRequestStatus &aNotifyStatus);
void Cancel();
void Close();
    

To use the API requires an instance of the RFeatureRegistryNotify class to be Opened and Subscribed to. It will usually be employed in Active Objects in an Active Scheduler. At any time while the instance is open, call Cancel() to ensure the object is not subscribed for notification. If it previously was subscribed, the asynchronous Subscribe() request is completed with KErrCancel.

When a Subscribe() request completes successfully, will know that the Feature Registry has changed. You must re-query the features you are interested in, to determine whether the change affected affects you.

To ensure changes are not missed, always re-subscribe before querying the Feature Registry.

Note:

• Most clients do not require run-time notification of feature changes. The vast majority of features are not removable, and most applications can be restarted if a feature needs to be rediscovered. The potential use of this API are long-running system tasks that monitor a variety of features, and applications that use software that becomes supported or unsupported as add-on devices are attached and detached (that is, plug and play devices).

• While the class RFeatureRegistryNotify is currently marked as internal to Symbian, the intention is to reclassify it as publishedAll in a later release of Symbian platform. Therefore, contrary to expectations, this class can be used as described.

Preconditions for feature notification

It is not expected that many clients will require run-time notification of feature changes. The vast majority of features are not removable, and most applications can be restarted if a feature needs to be rediscovered. This API is likely to be used by long-running system tasks that monitor a variety of features, and applications that use software that becomes supported or unsupported as add-on devices are attached and detached (that is, plug and play devices).

Notification is for any change in the Feature Registry. The recipient must determine if the status of any feature they are interested in has changed.

The current implementation of Feature Registry is a constant ROM-based configuration file. The API is provided for forward compatibility. Applications can be written now anticipating run-time feature changes in a future implementation. Alternatively, applications can be written in the future once run-time updates do occur, and the API will be present – but will never notify – on older devices so there will be no compatibility issues.

It is possible for Symbian and licensees to force notification for testing purposes. This is a side-effect of the current implementation, is @internalComponent and not guaranteed to work into the future. Running featregsetup.exe (a binary included with the component) currently forces notification.