<?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-27C3F32C-4B66-539A-8561-EF442E0F0A77"><title>Feature Manager Plugins</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document explains how to use Feature Manager plugins. </p> <section id="GUID-D41B9CDD-A7ED-5D82-87F4-960193AC3C52"><title>About Feature Manager Plugins</title> <p>The Feature Manager provides functionality to manipulate information about features present on a device by querying a server. How does the server acquire that information in the first place? One source of the information is the Feature Manager plugins, the other being <xref href="GUID-DD60D070-122D-528B-B545-248C5BA24E20.dita">feature data files</xref>. Features are associated with items of hardware, software and network connections and items are related to plugins. An example of a feature is the ability to receive a fax message over Bluetooth, this being an item of functionality associated with a network connection. The server queries the plugins about the status of their associated features and the plugins return a response. The Feature Manager updates its collection of feature data at device startup when it detects new connections and newly installed software. </p> </section> <section id="GUID-37890B84-DA0D-551C-B9D3-73BB895138D5"><title>Feature Manager Plugin interface to ECOM</title> <p>Feature Manager uses the <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECOM</xref> framework to discover feature plugins. A plugin implementation must have an interface Uid of 0x10205057 and its own unique implementation Uid. These two Uids are held in the plugin resource file. Feature Manager plugins must reside in ROM for the Feature Manager to discover them. </p> </section> <section id="GUID-1F0CE64B-2909-5414-B23A-9EEC2774910C"><title>Structure of Feature Manager Plugin</title> <p>Feature plugins are implementations of the <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref> interface. Although this class is called an interface, you implement it by creating a subclass. It has a single member object and a single member function. </p> <p>The member object is <xref href="GUID-9784517C-28D0-3A35-97D4-F55DD7532E85.dita"><apiname>iResponseCallback</apiname></xref> of class <xref href="GUID-0C29B43B-EA94-3C1F-8B55-F02CF502AF5D.dita"><apiname>MFeatureInfoPluginCallback</apiname></xref>. This object is protected and is not owned by <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref>. <xref href="GUID-0C29B43B-EA94-3C1F-8B55-F02CF502AF5D.dita"><apiname>MFeatureInfoPluginCallback</apiname></xref> is an interface which is implemented in server side code: <i>you do not implement it yourself</i>. </p> <p>The member function is <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref>. </p> <p>To create a plugin you have to implement <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref> so that <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> creates the response to a server request for information about features. You then have to return the response to the server using <xref href="GUID-9784517C-28D0-3A35-97D4-F55DD7532E85.dita"><apiname>iResponseCallback</apiname></xref>. The interface <xref href="GUID-0C29B43B-EA94-3C1F-8B55-F02CF502AF5D.dita"><apiname>MFeatureInfoPluginCallback</apiname></xref> provides a function <xref href="GUID-527C2F36-711C-384B-99CA-C9249A914E7C.dita"><apiname>ProcessResponseL</apiname></xref> which you call for this purpose. <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref> has a protected member <xref href="GUID-9784517C-28D0-3A35-97D4-F55DD7532E85.dita"><apiname>iResponseCallback</apiname></xref> of the class <xref href="GUID-0C29B43B-EA94-3C1F-8B55-F02CF502AF5D.dita"><apiname>MFeatureInfoPluginCallback</apiname></xref>: it is not part of the exposed API but you need to know of its existence. The call to <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> must return before the call to <xref href="GUID-527C2F36-711C-384B-99CA-C9249A914E7C.dita"><apiname>ProcessResponseL</apiname></xref> begins: <i>the two calls must be asynchronous</i>. (The reason for this is the way the server is implemented.) </p> <p>The arguments of <xref href="GUID-527C2F36-711C-384B-99CA-C9249A914E7C.dita"><apiname>ProcessResponseL</apiname></xref> and <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> are exactly the same. This is their purpose. </p> <ul><li id="GUID-F9C4A4B8-B4B8-5705-9FFE-82BB807A443E"><p> <xref href="GUID-A9D54790-CF5D-36FD-A925-C7823E33A467.dita"><apiname>aCommandId</apiname></xref> is a <xref href="GUID-784A9C71-77DE-34BD-BF4A-E136BA717B83.dita"><apiname>TFeatureInfoCmd</apiname></xref> representing the query sent from the server. </p> </li> <li id="GUID-14F93D1E-766B-51D1-B3CF-B146D19A27CA"><p> <xref href="GUID-960FC028-D8F1-3C2B-B968-41EF9FA8B8EB.dita"><apiname>aTransId</apiname></xref> is a <xref href="GUID-F894527F-13A6-3E6D-BA7B-187812CDF20E.dita"><apiname>TUint8</apiname></xref> representing the transaction Id, which the server requires to keep track of the asynchronous function calls. </p> </li> <li id="GUID-F907E7A9-79CA-5817-B987-D625AC023E85"><p> <xref href="GUID-33D3FD1B-06E6-38A5-9446-571A116894B0.dita"><apiname>aData</apiname></xref> is the data required by the server. In some cases it will be an empty buffer. It is declared as a <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> but in fact must be one of two specific subclasses of <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> explained below. </p> </li> </ul> <p>The third argument of <xref href="GUID-527C2F36-711C-384B-99CA-C9249A914E7C.dita"><apiname>ProcessResponseL</apiname></xref> and <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> is declared as the address of a <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref>. In fact the data type of this argument depends on the value of the argument <xref href="GUID-A9D54790-CF5D-36FD-A925-C7823E33A467.dita"><apiname>aCommandId</apiname></xref> which is a member of the enumeration of commands <xref href="GUID-784A9C71-77DE-34BD-BF4A-E136BA717B83.dita"><apiname>TFeatureInfoCmd</apiname></xref> and has three possible values. They are </p> <ul><li id="GUID-619D4A09-6BC2-5329-9939-85972C857D8C"><p> <xref href="GUID-3A4CCE53-0A74-35EE-B4CD-71F979A91A38.dita"><apiname>ENoCommandId</apiname></xref>, a null command used in testing which requires <xref href="GUID-33D3FD1B-06E6-38A5-9446-571A116894B0.dita"><apiname>aData</apiname></xref> to be an empty buffer, </p> </li> <li id="GUID-4B069A93-9352-5889-A232-2E94E38ABBEF"><p> <xref href="GUID-4DBDEDEB-6157-30FB-9390-386C29C9DA13.dita"><apiname>ELoadFeatureInfoCmdId</apiname></xref>, which represents a boolean query and requires <xref href="GUID-33D3FD1B-06E6-38A5-9446-571A116894B0.dita"><apiname>aData</apiname></xref> to be a <xref href="GUID-F55853DC-56B3-3C0E-BD6E-60BE6CDFC410.dita"><apiname>TFeatureInfoRespPckg</apiname></xref> (an array of <xref href="GUID-CAC1553D-45FC-36CF-9232-9DA00F2A6528.dita"><apiname>TFeatureInfo</apiname></xref>), and </p> </li> <li id="GUID-2A21845A-C522-5673-BD65-D68130062996"><p> <xref href="GUID-DEF34801-61A1-3C04-8D0C-B90E18A6DC3F.dita"><apiname>ELoadEnhancedFeatureInfoCmdId </apiname></xref>, which represents an enhanced query and requires <xref href="GUID-33D3FD1B-06E6-38A5-9446-571A116894B0.dita"><apiname>aData</apiname></xref> to be a <xref href="GUID-9CFD5071-E1BE-3CE4-9E8F-2AE17CC16A31.dita"><apiname>TEnhancedFeatureInfoRespPckg</apiname></xref> (an array of <xref href="GUID-1983F7CA-1816-3672-8083-8D4FDAC0BE0E.dita"><apiname>TEnhancedFeatureInfo</apiname></xref>). </p> </li> </ul> <p>A boolean query <xref href="GUID-4DBDEDEB-6157-30FB-9390-386C29C9DA13.dita"><apiname>ELoadFeatureInfoCmdId</apiname></xref> simply returns with the presence or absence of the feature on the device. An enhanced query <xref href="GUID-DEF34801-61A1-3C04-8D0C-B90E18A6DC3F.dita"><apiname>ELoadEnhancedFeatureInfoCmdId </apiname></xref> returns the presence or absence of the feature and additional information such as its name and status (e.g. "supported"). You may implement either type of query depending on the nature of the feature information which is to be published. </p> <p>A boolean query returns a <xref href="GUID-F589DC3A-70F3-3A03-845F-A351BA2F5316.dita"><apiname>TFeature</apiname></xref> object for each feature it discovers and those objects are held in an array. That array together with an error code is contained in a <xref href="GUID-CAC1553D-45FC-36CF-9232-9DA00F2A6528.dita"><apiname>TFeatureInfo</apiname></xref> object which is contained in a <xref href="GUID-F55853DC-56B3-3C0E-BD6E-60BE6CDFC410.dita"><apiname>TFeatureInfoRespPckg</apiname></xref>. That package is passed as the third argument of a boolean query. </p> <p>An enhanced query returns a <xref href="GUID-80C51259-F2C4-3877-97B4-EC0C85DE93DE.dita"><apiname>TFeatureEntry</apiname></xref> object for each feature it discovers. An array of these objects together with an error code is contained in a <xref href="GUID-1983F7CA-1816-3672-8083-8D4FDAC0BE0E.dita"><apiname>TEnhancedFeatureInfo</apiname></xref> object packaged as a <xref href="GUID-9CFD5071-E1BE-3CE4-9E8F-2AE17CC16A31.dita"><apiname>TEnhancedFeatureInfoRespPckg</apiname></xref> and returned as the third argument of an enhanced query. </p> <p> <xref href="GUID-80C51259-F2C4-3877-97B4-EC0C85DE93DE.dita"><apiname>TFeatureEntry</apiname></xref> objects are part of the main Feature Manager API: see <xref href="GUID-C8086FF0-891B-5045-AD7A-41D15EFF2252.dita">How to use the Feature Manager</xref>. </p> <p> <xref href="GUID-F589DC3A-70F3-3A03-845F-A351BA2F5316.dita"><apiname>TFeature</apiname></xref> objects are part of the Feature Manager Plugin API. They consist of </p> <ul><li id="GUID-4C88C98E-EA92-51DF-A80C-C9EE6D405F47"><p> <xref href="GUID-269D3D8C-44F9-38C8-8F72-3517ADFC9829.dita"><apiname>iFeatureId</apiname></xref>, a 32 bit Id representing the feature, and </p> </li> <li id="GUID-9A225E33-9029-5D5A-B58B-8F04741109C6"><p> <xref href="GUID-3375282F-3344-39AF-A854-AE8CC5272C3E.dita"><apiname>iValue</apiname></xref>, a boolean set to <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> if the feature is off and <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> if the feature is on. </p> </li> </ul> </section> <section id="GUID-0C3F492C-05AB-53BE-858E-884EF35A7259"><title>A suggested implementation of Feature Manager Plugin</title> <p>The following is a suggested method of implementing a Feature Manager Plugin so as to process the server command and the client response asynchronously. </p> <ul><li id="GUID-46CE7099-0900-5BBD-8011-BEEE7B5785CB"><p>Write a subclass of <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref>. </p> </li> <li id="GUID-EF2A78FE-D346-5F3B-A578-B903D3EF6AC4"><p>Write a timer class. The constructor of the timer should take arguments including an <xref href="GUID-0C29B43B-EA94-3C1F-8B55-F02CF502AF5D.dita"><apiname>MFeatureInfoPluginCallback</apiname></xref> object and the data needed to create the response. </p> </li> <li id="GUID-F8B527AB-1293-50D5-8287-B18001B18124"><p>Implement the <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> function of <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref> so that it constructs a timer just before it returns. Pass the <xref href="GUID-9784517C-28D0-3A35-97D4-F55DD7532E85.dita"><apiname>iResponseCallback</apiname></xref> member of <xref href="GUID-5A2EDFE5-E46E-3F5E-AF1C-FDA857559C91.dita"><apiname>CFeatureInfoPlugin</apiname></xref> to the constructor of the timer. </p> </li> <li id="GUID-BF08079C-2BCD-5F35-9E32-F2BDB05FA0E7"><p>Have the timer wait a sufficient period to ensure that <xref href="GUID-CBB61EAE-7160-3CC7-BE1D-3157C61F747F.dita"><apiname>ProcessCommandL</apiname></xref> has returned. </p> </li> <li id="GUID-30CEAB3B-FB5C-56DD-B2A8-7B7CE9EF90BD"><p>Have the timer assemble the response data as a package and pass it to the <xref href="GUID-4752E61E-67AC-3E94-88EB-B5CFC8DEEE20.dita"><apiname>ProcessResponseL()</apiname></xref> function of <xref href="GUID-9784517C-28D0-3A35-97D4-F55DD7532E85.dita"><apiname>iResponseCallback</apiname></xref>. </p> </li> </ul> </section> </conbody><related-links><link href="GUID-B71AC5E3-8AA8-55AD-916F-9E873926011B.dita"><linktext>Feature Manager Overview</linktext> </link> <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>