Feature Manager Plugins

About Feature Manager Plugins

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 feature data files. 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.

Feature Manager Plugin interface to ECOM

Feature Manager uses the ECOM 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.

Structure of Feature Manager Plugin

Feature plugins are implementations of the CFeatureInfoPlugin 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.

The member object is iResponseCallback of class MFeatureInfoPluginCallback. This object is protected and is not owned by CFeatureInfoPlugin. MFeatureInfoPluginCallback is an interface which is implemented in server side code: you do not implement it yourself.

The member function is ProcessCommandL.

To create a plugin you have to implement CFeatureInfoPlugin so that ProcessCommandL creates the response to a server request for information about features. You then have to return the response to the server using iResponseCallback. The interface MFeatureInfoPluginCallback provides a function ProcessResponseL which you call for this purpose. CFeatureInfoPlugin has a protected member iResponseCallback of the class MFeatureInfoPluginCallback: it is not part of the exposed API but you need to know of its existence. The call to ProcessCommandL must return before the call to ProcessResponseL begins: the two calls must be asynchronous. (The reason for this is the way the server is implemented.)

The arguments of ProcessResponseL and ProcessCommandL are exactly the same. This is their purpose.

• aCommandId is a TFeatureInfoCmd representing the query sent from the server.

• aTransId is a TUint8 representing the transaction Id, which the server requires to keep track of the asynchronous function calls.

• aData is the data required by the server. In some cases it will be an empty buffer. It is declared as a TDesC8 but in fact must be one of two specific subclasses of TDesC8 explained below.

The third argument of ProcessResponseL and ProcessCommandL is declared as the address of a TDesC8. In fact the data type of this argument depends on the value of the argument aCommandId which is a member of the enumeration of commands TFeatureInfoCmd and has three possible values. They are

• ENoCommandId, a null command used in testing which requires aData to be an empty buffer,

• ELoadFeatureInfoCmdId, which represents a boolean query and requires aData to be a TFeatureInfoRespPckg (an array of TFeatureInfo), and

• ELoadEnhancedFeatureInfoCmdId , which represents an enhanced query and requires aData to be a TEnhancedFeatureInfoRespPckg (an array of TEnhancedFeatureInfo).

A boolean query ELoadFeatureInfoCmdId simply returns with the presence or absence of the feature on the device. An enhanced query ELoadEnhancedFeatureInfoCmdId 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.

A boolean query returns a TFeature 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 TFeatureInfo object which is contained in a TFeatureInfoRespPckg. That package is passed as the third argument of a boolean query.

An enhanced query returns a TFeatureEntry object for each feature it discovers. An array of these objects together with an error code is contained in a TEnhancedFeatureInfo object packaged as a TEnhancedFeatureInfoRespPckg and returned as the third argument of an enhanced query.

TFeatureEntry objects are part of the main Feature Manager API: see How to use the Feature Manager.

TFeature objects are part of the Feature Manager Plugin API. They consist of

• iFeatureId, a 32 bit Id representing the feature, and

• iValue, a boolean set to EFalse if the feature is off and ETrue if the feature is on.

A suggested implementation of Feature Manager Plugin

The following is a suggested method of implementing a Feature Manager Plugin so as to process the server command and the client response asynchronously.

• Write a subclass of CFeatureInfoPlugin.

• Write a timer class. The constructor of the timer should take arguments including an MFeatureInfoPluginCallback object and the data needed to create the response.

• Implement the ProcessCommandL function of CFeatureInfoPlugin so that it constructs a timer just before it returns. Pass the iResponseCallback member of CFeatureInfoPlugin to the constructor of the timer.

• Have the timer wait a sufficient period to ensure that ProcessCommandL has returned.

• Have the timer assemble the response data as a package and pass it to the ProcessResponseL() function of iResponseCallback.