<?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 xml:lang="en" id="GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9"><title>Optional Features Query API</title><shortdesc>This document details how to query a device for the presence of single features and multiple features using the Feature Registry. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-03094475-44BD-5582-8213-70B66D76B928"><title>Single feature queries</title> <p>A single feature Query API is provided by class <xref href="GUID-4A0F7FCB-C3ED-3F0E-AB1D-5D96D5625595.dita"><apiname>RFeatureRegistryNotify</apiname></xref>, declared in <filepath>featreg.h</filepath>, supplied by <filepath>featreg.dll</filepath> and linked through <filepath>featreg.lib</filepath>. </p> <p>To inquire whether a single feature is supported on the device, use the following static function of class <xref href="GUID-9374A36C-BA56-3893-A72B-62544D2FD6AA.dita"><apiname>RFeatureRegistry</apiname></xref>: </p> <codeblock id="GUID-4E318BD0-3F0F-5895-8622-44E8F1B3C4D9" xml:space="preserve">static TInt QuerySupportS(TUid aFeatureUid);</codeblock> <p>This function returns a positive value if the feature is supported, zero if the feature is not supported, otherwise (in the exceptional case) a negative, system-wide error code if support cannot be determined. </p> <p>You can choose to deal with the error returns locally. For example, by considering the feature <i>not supported</i>: </p> <codeblock id="GUID-52E31137-03B0-532F-B509-C9EC20049BE7" xml:space="preserve">TBool haveUsb = RFeatureRegistry::QuerySupportS(NFeature::KUsb) &gt; 0;</codeblock> <p>Alternatively you can choose to <i>Leave</i> on exceptional error returns: </p> <codeblock id="GUID-41267948-4C7F-504A-ADB5-217AE7AE453A" xml:space="preserve">TBool haveUsb =
              User::LeaveIfError(RFeatureRegistry::QuerySupportS(NFeature::KUsb)) &gt; 0;
</codeblock> <p>The Feature Registry maintains an additional 32-bit data word per feature, which can be obtained using an overload of the <xref href="GUID-A206EE27-AA19-3D32-81BD-AF1D3A0D2F21.dita"><apiname>QuerySupportS</apiname></xref> function: </p> <codeblock id="GUID-D5AE4FF4-C8CD-5B1E-B234-030E7400EC88" xml:space="preserve">static TInt QuerySupportS(TUid aFeatureUid, TUint32&amp; aInfo);</codeblock> <p>The contents of this extra word are reserved for future use. </p> </section> <section id="GUID-3024D6DD-8257-5EF6-8095-B7814A081656"><title> Multiple feature queries</title> <p>The most efficient way to find out if more than one function is supported is to open and query an instance of the <xref href="GUID-9374A36C-BA56-3893-A72B-62544D2FD6AA.dita"><apiname>RFeatureRegistry</apiname></xref> class using the following non-static methods of the <codeph>RFeatureRegistry</codeph> class: </p> <codeblock id="GUID-E155717F-4A2D-54DA-85CE-4440EB0D1695" xml:space="preserve">inline RFeatureRegistry();
TInt Open();
TInt QuerySupport(TUid aFeatureUid);
TInt QuerySupport(TUid aFeatureUid, TUint32&amp; aInfo);
void Close();
</codeblock> <p> <xref href="GUID-9374A36C-BA56-3893-A72B-62544D2FD6AA.dita"><apiname>RFeatureRegistry</apiname></xref> also has an overload of non-static QuerySupport, which can return the extra word of data stored with each feature. </p> <p>An important point about the above non-static APIs is that they only guarantee to return the state of features at the time <xref href="GUID-20D0D10F-3401-3F72-8AF6-DC35F6025DC2.dita"><apiname>Open()</apiname></xref> was called. To ensure that future run-time feature changes are detected, close the instance immediately after querying it, and re-open it next time queries are to be made. This also frees up resources held by the open instance. </p> <p> <b>Note:</b> Querying features can have an impact on performance. Therefore, if you are querying frequently (for example, in a loop) it is recommended that you cache the query return. However, if the feature is seldom used (once or twice between switching the device on and off), caching is unnecessary. </p> </section> <example id="GUID-1E023B69-F2F9-5FAF-B56C-D95443DDC564"><title>Optional features query API example</title> <p>The following code illustrates how to query several features in a non-leaving context (and treating exceptional results as if the feature is not supported). </p> <codeblock id="GUID-5BA833B1-6CC3-5784-A775-82EA3851AC97" xml:space="preserve">TBool iHaveUsb;
TBool iHaveBluetooth;
...
RFeatureRegistry featReg;
const TBool opened = (featReg.Open() == KErrNone);
iHaveUsb = opened &amp;&amp; (featReg.QuerySupport(NFeature::KUsb) &gt; 0);
iHaveBluetooth = opened &amp;&amp; (featReg.QuerySupport(NFeature::KBluetooth) &gt; 0);
// can always call Close(), even if Open() failed:
featReg.Close();
</codeblock> <p>Or if choosing to <i>Leave</i> on exceptional returns: </p> <codeblock id="GUID-07463560-744A-5821-BAB7-0F72C7048E5E" xml:space="preserve">RFeatureRegistry featReg;
User::LeaveIfError(featReg.Open());
CleanupClosePushL(featReg);               // don’t forget this
iHaveUsb = User::LeaveIfError(featReg.QuerySupport(NFeature::KUsb)) &gt; 0;
iHaveBluetooth =
    User::LeaveIfError(featReg.QuerySupport(NFeature::KBluetooth)) &gt; 0;
CleanupStack::PopAndDestroy(&amp;featReg);    // this calls Close()
</codeblock> </example> <section id="GUID-F411E1E4-5A9D-5469-8E58-7E0CCD213368"><title>Preconditions for Feature Queries</title> <p>When deciding when and how often to query, you must plan carefully as feature queries will result in a performance overhead. It is recommended that you always query and cache the return value if it is to be used many times in quick succession, particularly in loops. However, if the feature is seldom used (once or twice between switching the device on and off), caching is unnecessary. </p> <p>Your UI-provider or system integration team must ensure that the Feature Registry has a valid configuration file for the environment you are using, be it an emulator or a target device or reference board. </p> <p>Where optional features are removed from a device, all effort is made to make the failure of any attempt to use the missing features as graceful as possible. Unless individual features are documented to give particular, safe responses when not supported by a device (through a stub DLL, for example), their use as a means to discover the feature cannot be considered safe unless expressly documented as such. In addition, optional features supplied as plug-ins may be more efficiently detected using the Feature Registry. Finally, even if it works now, there is no guarantee that attempts to use a removed feature in future will not have serious consequences including exceptions, leaves or panics. </p> </section> <section id="GUID-BBE1DF47-E2BC-5279-9945-FD35EBB1DEDB"><title>Errors and Panics</title> <p>If the error <xref href="GUID-64F6761A-4716-37C3-8984-FF18FC8B7B7D.dita"><apiname>KErrNoMemory</apiname></xref> is returned, this means there is insufficient memory to complete the query. If more memory becomes available subsequent queries may succeed. </p> <p>If the error <xref href="GUID-253F06EA-F14E-3A8E-BA4C-8E787B5F0670.dita"><apiname>KErrCorrupt</apiname></xref> is returned, this is serious. Your UI-provider or system integration team must ensure that the Feature Registry has a valid configuration file for the environment you are using, be it an emulator or a target device or reference board. Refer to the <xref href="GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9.dita#GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9/GUID-03094475-44BD-5582-8213-70B66D76B928">Single feature queries</xref> and <xref href="GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9.dita#GUID-747869DD-ECD1-5515-B876-0D7D753B1CD9/GUID-3024D6DD-8257-5EF6-8095-B7814A081656">Multiple feature queries</xref> sections for example code on how to allow client programs to continue under such circumstances. </p> <p>In debug builds you may get panic “FeatReg 1” when you call RFeatureRegistry functions. In release builds, the error value <xref href="GUID-253F06EA-F14E-3A8E-BA4C-8E787B5F0670.dita"><apiname>KErrCorrupt</apiname></xref> is returned instead of a panic. “1” is the enumeration for <xref href="GUID-1584D300-8FEF-3285-8FAE-C6E99DDB7B5A.dita"><apiname>EFeatRegBadConfig</apiname></xref>, declared in the exported header file <filepath>featregpan.h</filepath>. This issue only occurs within Symbian and licensee organisations, and does not apply to external developers. </p> </section> </conbody><related-links><link href="GUID-B01EDE29-0861-52B0-97BE-8B41E580817F.dita"><linktext>Identifying
                Optional Features</linktext> </link> <link href="GUID-9F9D6764-D86E-5665-B51A-04A4D3949FB4.dita"><linktext>Optional Features
                Notification API</linktext> </link> <link href="GUID-F55EAA3A-5D30-5983-9053-7C3935D99802.dita"><linktext>Feature Registry
                Overview</linktext> </link> </related-links></concept>