--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-9F9D6764-D86E-5665-B51A-04A4D3949FB4.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-9F9D6764-D86E-5665-B51A-04A4D3949FB4" xml:lang="en"><title>Optional
+Features Notification API</title><shortdesc>This document details linkage to the notification API and how to
+subscribe for notification of feature changes. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-55F2A846-8A70-5F4D-B297-7678F82B56DC"><title>Interface class
+and linkage</title> <p>A Notify API is provided by the <xref href="GUID-4A0F7FCB-C3ED-3F0E-AB1D-5D96D5625595.dita"><apiname>RFeatureRegistryNotify</apiname></xref> class,
+declared in <filepath>featreg.h</filepath>, supplied by <filepath>featreg.dll</filepath> and
+linked through <filepath>featreg.lib</filepath>. </p> </section>
+<section id="GUID-5C18F9BD-DA86-5DD3-8286-6B3097869BA3"><title>Subscribing
+for notification of feature changes</title> <p>The <xref href="GUID-4A0F7FCB-C3ED-3F0E-AB1D-5D96D5625595.dita"><apiname>RFeatureRegistryNotify</apiname></xref> class
+has the following member functions that allow you to subscribe for notification
+of changes in the Feature Registry: </p> <codeblock id="GUID-55B5F119-E275-5105-9B32-61ABFA3C927A" xml:space="preserve">inline RFeatureRegistryNotify();
+TInt Open();
+void Subscribe(TRequestStatus &aNotifyStatus);
+void Cancel();
+void Close();
+ </codeblock> <p>To use the API requires an instance of the <codeph>RFeatureRegistryNotify</codeph> 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 <xref href="GUID-B61994E7-B88B-38FE-86AE-1B9834F1816D.dita"><apiname>Cancel()</apiname></xref> to
+ensure the object is not subscribed for notification. If it previously was
+subscribed, the asynchronous <xref href="GUID-D7A5E7E3-5EA0-3DBC-A34A-072E4705930D.dita"><apiname>Subscribe()</apiname></xref> request is completed
+with <xref href="GUID-6F4A88DA-F54E-3848-9C32-942D6F5F4F3E.dita"><apiname>KErrCancel</apiname></xref>. </p> <p>When a <codeph>Subscribe()</codeph> 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. </p> <p>To ensure changes are not missed, always
+re-subscribe before querying the Feature Registry. </p> <p> <b>Note: </b> </p> <ul>
+<li id="GUID-FF101FF0-0330-548D-9B4B-7663D8514CC7"><p>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). </p> </li>
+<li id="GUID-DC33F66D-77A1-5CC2-A8A7-F47B0E7DFE69"><p>While the class <xref href="GUID-4A0F7FCB-C3ED-3F0E-AB1D-5D96D5625595.dita"><apiname>RFeatureRegistryNotify</apiname></xref> is
+currently marked as internal to Symbian, the intention is to reclassify it
+as <b>publishedAll</b> in a later release of Symbian platform. Therefore,
+contrary to expectations, this class <i>can</i> be used as described. </p> </li>
+</ul> </section>
+<section id="GUID-AF622B78-9C99-5696-A3F5-89716A568FB5"><title>Preconditions
+for feature notification</title> <p>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). </p> <p>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. </p> <p>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. </p> <p>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 <filepath>featregsetup.exe</filepath> (a binary included with
+the component) currently forces notification. </p> </section>
+</conbody><related-links>
+<link href="GUID-B01EDE29-0861-52B0-97BE-8B41E580817F.dita"><linktext>Identifying
+ Optional Features</linktext></link>
+<link href="GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9.dita"><linktext>Optional
+Features Query API</linktext></link>
+<link href="GUID-F55EAA3A-5D30-5983-9053-7C3935D99802.dita"><linktext>Feature Registry
+ Overview</linktext></link>
+</related-links></concept>
\ No newline at end of file