<?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-1568493D-0384-5FBD-816B-60A4817CEF0C"><title>Feature Manager Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Feature Manager component is a set of classes used to manipulate feature flags. </p> <section id="GUID-66C95D4D-FC7C-5EFE-973B-9E8A4C4A9D37"><title>About Feature Manager</title> <p>Third party developers using the SDK only have the ability to report the availability of features. </p> <p>Feature Manager supersedes the component Feature Registry in earlier versions of Symbian platform. Feature Manager has the capacity to modify feature flags at runtime. Feature Registry lacked this capacity and is now deprecated. </p> </section> <section><title>What is a feature?</title> <p>A feature can be any item of functionality supplied with a phone. Examples of features include: </p> <ul><li id="GUID-8261F6C0-96CE-5289-AE5A-E01186381264"><p>the presence or absence of particular hardware, for instance the presence of an MMC slot, </p> </li> <li id="GUID-9E687D45-9E86-5714-909E-7BF0237F9C29"><p>the presence or absence of a particular software component, DLL or individual function, or </p> </li> <li id="GUID-CAA18099-322C-562B-B2DE-2DA89DA5DD8D"><p>the presence or absence of a network connection. </p> </li> </ul> </section> <section><title>How is a feature included?</title> <p>A feature may be included on a phone in various ways: </p> <ul><li id="GUID-1C060016-4961-5B7D-B3B7-98D6E7054770"><p>at phone build time, </p> </li> <li id="GUID-8B617BE1-E593-5866-A142-51C3AFC5A694"><p>when software is installed after the build, or </p> </li> <li id="GUID-7BAC9528-9E7C-577E-AD49-9D8949CCF7E8"><p>when functionality such as a connection is discovered at run time. </p> </li> </ul> <p>Features may be queried, enabled, disabled and modified. </p> </section> <section><title>What functionality is supplied with Feature Manager?</title> <p>Two subsets of functionality are published: a minimal one for third parties is supplied with the SDK, and a fuller one is published to Symbian partners. The third party SDK requires the <xref href="GUID-2C9E6E72-2858-37A1-9D43-4E8086569520.dita"><apiname>CFeatureDiscovery</apiname></xref> class to be used, while partners also have the <xref href="GUID-F6AAAC24-4A62-383A-86C6-2E46335C3FD4.dita"><apiname>RFeatureControl</apiname></xref>. WriteDeviceData capability is required to use <xref href="GUID-F6AAAC24-4A62-383A-86C6-2E46335C3FD4.dita"><apiname>RFeatureControl</apiname></xref> to modify feature flags. </p> </section> <section><title>How are features represented?</title> <p>Every feature is assigned a unique Uid which the Feature Manager API uses to access it. Full data about a feature is held in the class <codeph>TFeatureEntry</codeph>, which contains the Uid, the status of the feature, and feature data. </p> <p>The status of a feature is the availability of the feature. A feature may be: </p> <ul><li id="GUID-6E9A9A6A-A19C-5C91-8B81-55A0131B5D29"><p>supported, meaning that the feature is present or supported on the device, </p> </li> <li id="GUID-261E84FE-2D0A-5064-A3C5-30B0B68DDC1A"><p>modifiable, meaning that the feature may be modified using the API, </p> </li> <li id="GUID-57C9C783-C20B-514A-A369-4A55B44AB61F"><p>blacklisted, meaning that the feature is frozen and may not be overridden in later ROM section, or via a plugin, or through the API, </p> </li> <li id="GUID-1D89C433-7B80-595F-8FDE-E549321748DC"><p>uninitialised, meaning that the supported status was not set at device creation, and </p> </li> <li id="GUID-5AC6A30E-BCD4-5E00-A859-284E2CEBF10F"><p>persisted, meaning that the feature will be persisted so as to be restored on restart. </p> </li> </ul> <p>The status of a feature is represented by a 32-bit integer whose bits are boolean flags named in the enumeration <codeph>TFeatureFlags</codeph>. Some combinations of features cannot be true simultaneously either at build time or run time: for instance <codeph>EFeatureUninitialised</codeph> is incompatible with <codeph>EFeatureModifiable</codeph> or <codeph>EFeaturePersisted</codeph>. </p> <p>Feature data is user-defined data referring to the feature. Feature data is held in a 32-bit integer which is usually a reference to a repository or database. </p> <p>A group of features is represented by an array. The individual features may be identified simply by their Uids, in which case you use the data type <xref href="GUID-E8FE48BB-6832-3B20-9814-72BE01198EEF.dita"><apiname>RFeatureUidArray</apiname></xref>, which is an array of <codeph>TUid</codeph>. They may also be represented as <xref href="GUID-80C51259-F2C4-3877-97B4-EC0C85DE93DE.dita"><apiname>TFeatureEntry</apiname></xref> objects, in which case you use the data type <xref href="GUID-144E257F-A162-3680-B1C5-C28BEAA902BC.dita"><apiname>RFeatureArray</apiname></xref>, which is an array of <xref href="GUID-80C51259-F2C4-3877-97B4-EC0C85DE93DE.dita"><apiname>TFeatureEntry</apiname></xref> objects. </p> </section> <section><title>How are features queried and modified?</title> <p>Feature Manager provides two classes which you use to interface to the feature tags database to query the existence and status of a feature: </p> <ul><li id="GUID-6C2888F0-9BDB-5AF0-9AB3-2CCB17CE3369"><p> <codeph>CFeatureDiscovery</codeph>  </p> </li> <li id="GUID-055FCE12-03D9-5DAE-9686-51A12C2DA3E0"><p> <codeph>RFeatureControl</codeph>  </p> </li> </ul> <p> <codeph>CFeatureDiscovery</codeph> is an active object which can only be used to query features and is supplied to third-party developers. <codeph>RFeatureControl</codeph> is used to query features and to modify their status and associated data: it is only supplied to Symbian partners. Both classes use Uids and <codeph>TFeatureEntry</codeph> to access feature data. <codeph>RFeatureControl</codeph> is always used dynamically: that is you must construt an instance and call its functions within the lifetime of that instance. <codeph>RFeatureControl</codeph> has more powerful functionality but <codeph>CFeatureDiscovery</codeph> allows static calls which can be more efficient. <codeph>CFeatureDiscovery</codeph> must only be used by clients which can support leaving code: otherwise they must use <codeph>RFeatureControl</codeph>. </p> </section> <section><title>Notification of change to features</title> <p>The capability to modify feature status and feature data at runtime creates the need for notification of such changes. <codeph>CFeatureNotifier</codeph> provides functions to set up and cancel notification of various types of change to a given feature. The interface <codeph>MFeatureObserver</codeph> defines functionality for handling changes: the exact way in which change is handled depends on the implementation. The notification functions of <codeph>RFeatureControl</codeph> are called from within an implementation of <codeph>MFeatureObserver</codeph>. </p> </section> </conbody><related-links><link href="GUID-3FB773BA-C648-5C0A-9022-3F9882C6724A.dita"><linktext>Feature Manager Client
                Overview</linktext> </link> <link href="GUID-40B9136A-B91B-5FF4-A44D-CA6925F19B14.dita"><linktext>Feature Discovery Overview</linktext> </link> <link href="GUID-EF3DB813-B0B9-5099-9E57-561A32111BF0.dita"><linktext>Feature Manager Server Guide</linktext> </link> </related-links></concept>