Optional -Features Notification API

Optional -Features Notification APIThis document details linkage to the notification API and how to -subscribe for notification of feature changes. -

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.

-Identifying - Optional Features -Optional -Features Query API -Feature Registry - Overview + + + + + +Optional +Features Notification APIThis document details linkage to the notification API and how to +subscribe for notification of feature changes. +

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.

+Identifying + Optional Features +Optional +Features Query API +Feature Registry + Overview

\ No newline at end of file