|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-9F9D6764-D86E-5665-B51A-04A4D3949FB4" xml:lang="en"><title>Optional |
|
13 Features Notification API</title><shortdesc>This document details linkage to the notification API and how to |
|
14 subscribe for notification of feature changes. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-55F2A846-8A70-5F4D-B297-7678F82B56DC"><title>Interface class |
|
16 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, |
|
17 declared in <filepath>featreg.h</filepath>, supplied by <filepath>featreg.dll</filepath> and |
|
18 linked through <filepath>featreg.lib</filepath>. </p> </section> |
|
19 <section id="GUID-5C18F9BD-DA86-5DD3-8286-6B3097869BA3"><title>Subscribing |
|
20 for notification of feature changes</title> <p>The <xref href="GUID-4A0F7FCB-C3ED-3F0E-AB1D-5D96D5625595.dita"><apiname>RFeatureRegistryNotify</apiname></xref> class |
|
21 has the following member functions that allow you to subscribe for notification |
|
22 of changes in the Feature Registry: </p> <codeblock id="GUID-55B5F119-E275-5105-9B32-61ABFA3C927A" xml:space="preserve">inline RFeatureRegistryNotify(); |
|
23 TInt Open(); |
|
24 void Subscribe(TRequestStatus &aNotifyStatus); |
|
25 void Cancel(); |
|
26 void Close(); |
|
27 </codeblock> <p>To use the API requires an instance of the <codeph>RFeatureRegistryNotify</codeph> class |
|
28 to be Opened and Subscribed to. It will usually be employed in Active Objects |
|
29 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 |
|
30 ensure the object is not subscribed for notification. If it previously was |
|
31 subscribed, the asynchronous <xref href="GUID-D7A5E7E3-5EA0-3DBC-A34A-072E4705930D.dita"><apiname>Subscribe()</apiname></xref> request is completed |
|
32 with <xref href="GUID-6F4A88DA-F54E-3848-9C32-942D6F5F4F3E.dita"><apiname>KErrCancel</apiname></xref>. </p> <p>When a <codeph>Subscribe()</codeph> request |
|
33 completes successfully, will know that the Feature Registry has changed. You |
|
34 must re-query the features you are interested in, to determine whether the |
|
35 change affected affects you. </p> <p>To ensure changes are not missed, always |
|
36 re-subscribe before querying the Feature Registry. </p> <p> <b>Note: </b> </p> <ul> |
|
37 <li id="GUID-FF101FF0-0330-548D-9B4B-7663D8514CC7"><p>Most clients do not |
|
38 require run-time notification of feature changes. The vast majority of features |
|
39 are not removable, and most applications can be restarted if a feature needs |
|
40 to be rediscovered. The potential use of this API are long-running system |
|
41 tasks that monitor a variety of features, and applications that use software |
|
42 that becomes supported or unsupported as add-on devices are attached and detached |
|
43 (that is, plug and play devices). </p> </li> |
|
44 <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 |
|
45 currently marked as internal to Symbian, the intention is to reclassify it |
|
46 as <b>publishedAll</b> in a later release of Symbian platform. Therefore, |
|
47 contrary to expectations, this class <i>can</i> be used as described. </p> </li> |
|
48 </ul> </section> |
|
49 <section id="GUID-AF622B78-9C99-5696-A3F5-89716A568FB5"><title>Preconditions |
|
50 for feature notification</title> <p>It is not expected that many clients will |
|
51 require run-time notification of feature changes. The vast majority of features |
|
52 are not removable, and most applications can be restarted if a feature needs |
|
53 to be rediscovered. This API is likely to be used by long-running system tasks |
|
54 that monitor a variety of features, and applications that use software that |
|
55 becomes supported or unsupported as add-on devices are attached and detached |
|
56 (that is, plug and play devices). </p> <p>Notification is for any change in |
|
57 the Feature Registry. The recipient must determine if the status of any feature |
|
58 they are interested in has changed. </p> <p>The current implementation of |
|
59 Feature Registry is a constant ROM-based configuration file. The API is provided |
|
60 for forward compatibility. Applications can be written now anticipating run-time |
|
61 feature changes in a future implementation. Alternatively, applications can |
|
62 be written in the future once run-time updates do occur, and the API will |
|
63 be present – but will never notify – on older devices so there will be no |
|
64 compatibility issues. </p> <p>It is possible for Symbian and licensees to |
|
65 force notification for testing purposes. This is a side-effect of the current |
|
66 implementation, is @internalComponent and not guaranteed to work into the |
|
67 future. Running <filepath>featregsetup.exe</filepath> (a binary included with |
|
68 the component) currently forces notification. </p> </section> |
|
69 </conbody><related-links> |
|
70 <link href="GUID-B01EDE29-0861-52B0-97BE-8B41E580817F.dita"><linktext>Identifying |
|
71 Optional Features</linktext></link> |
|
72 <link href="GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9.dita"><linktext>Optional |
|
73 Features Query API</linktext></link> |
|
74 <link href="GUID-F55EAA3A-5D30-5983-9053-7C3935D99802.dita"><linktext>Feature Registry |
|
75 Overview</linktext></link> |
|
76 </related-links></concept> |