/*
* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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:
*
* Description:
*
*/
#ifndef FEATUREINFOPLUGIN_H
#define FEATUREINFOPLUGIN_H
/**
@file
@publishedPartner
@released
This header file holds the definitions for the Feature Manager adaptation
interface - Feature Info Plug-in API.
It holds interface and command definitions and the related command and response
types and structures used over this interface.
*/
// INCLUDES
#include <e32base.h>
#include <featmgr/featurecmn.h>
// CONSTANTS
/**
This constant holds the ECOM Instantiation Interface UID. This interface UID
identifies plug-in implementations that derive from CFeatureInfoPlugin.
This interface is used by the Feature Manager server when it is started up.
@see CFeatureInfoPlugin
*/
const TUid KFeatureInfoPluginInterfaceUid = { 0x10205057 };
// TYPES & STRUCTURES
/**
FeatureInfoCommand namespace groups the command ID enumerations, structures
and types used over the CFeatureInfoPlugin interface.
*/
namespace FeatureInfoCommand
{
/**
Command definitions
All commands contain a command Id and a set of parameters. The command
Ids are defined first then the parameters for each command.
The CFeatureInfoPlug ininterface is asynchronous. A command Id is sent to
the plugin through CFeatureInfoPlugin::ProcessCommandL(). If the command is
supported by the plug-in it schedules an active object to do the work and
call MFeatureInfoPluginCallback::ProcessResponseL() to complete the command.
If the command is not supported, the plug-in should leave with
KErrNotSupported.
The field Input means the parameter for the command.
The field Output means the parameter for the response.
@see CFeatureInfoPlugin
@see MFeatureInfoPluginCallback
*/
enum TFeatureInfoCmd
{
/**
No command. May be used for sanity checks, but
never as an actual command ID.
Input None
Output None
*/
ENoCommandId = 1000,
/**
FM uses this command to request feature information of read-only
features, aka simple features, known to the plug-in. Implementations
should used this command to return such features, if any are known.
If no such features are known to the plug-in it should leave with
KErrNotSupported, hence this command is optional.
Features contained in a response to this command should not appear
in ELoadEnhancedFeatureInfoCmdId responses, for efficiency.
Input None
Output TFeatureInfoRespPckg
*/
ELoadFeatureInfoCmdId,
/**
FM uses this command to request feature information of
features that have custom flags and user-data, that are known to the
plug-in. Implementations should use this command to return such
features, if any are known. If no such features are known to the
plug-in it should leave with KErrNotSupported, hence this command is
optional.
Features contained in a response to this command should not appear
in ELoadFeatureInfoCmdId responses, for efficiency.
Input None
Output TEnhancedFeatureInfoRespPckg
*/
ELoadEnhancedFeatureInfoCmdId
};
/**
Data structure used to list the features in data structure TFeatureInfo.
Used in ELoadFeatureInfoCmdId commands.
*/
struct TFeature
{
// UID of the feature, as found in a system header file.
TUint32 iFeatureID;
// Value of the 'Supported?' feature flag.
// If feature has been turned OFF from a product the value is set to
// EFalse and if it has been turned ON the value is set to ETrue.
TBool iValue;
};
/**
Data structure used to pass data with ELoadFeatureInfoCmdId response.
Used in ELoadFeatureInfoCmdId commands. It contains the return code for
the command iErrorCode and is typically:
No leave, just returns - iList contains feature entries.
KErrNotSuppoted - no features to report for this command.
... - other system wide error.
*/
struct TFeatureInfo
{
// System wide error code.
TInt iErrorCode;
// List of read-only feature entries.
RArray<TFeature> iList;
};
/** Data package for ELoadFeatureInfoCmdId response structure */
typedef TPckgBuf<TFeatureInfo> TFeatureInfoRespPckg;
/**
Data structure used to pass data with ELoadEnhancedFeatureInfoCmdId
response. Used in ELoadEnhancedFeatureInfoCmdId commands. It contains the
return code for the command iErrorCode and is typically:
No leave, just returns - iList contains feature entries.
KErrNotSuppoted - no features to report for this command.
... - other system wide error.
@see RFeatureArray
*/
struct TEnhancedFeatureInfo
{
// System wide error code.
TInt iErrorCode;
// List of enhanced feature records.
// List consists of TFeatureEntry entries. Plugin should initialize
// feature ID and feature support status flag and optionally any other
// feature flags as specified in TFeatureFlags. If feature has
// associated user-data, it should be initialized for response as well.
// If there is no user-data value this must be set to 0.
// For type definitions see featurecmn.h
RFeatureArray iList;
};
/** Data package for ELoadEnhancedFeatureInfoCmdId response structure */
typedef TPckgBuf<TEnhancedFeatureInfo> TEnhancedFeatureInfoRespPckg;
} // end namespace
// CLASS DECLARATION
/**
This M-class is an interface class implemented by FM server to receive
feature information responses from adaptation plug-ins i.e. they call the
server back with the data. Reference supplied to the plugin implementation
at construction and available in iResponseCallback.
@see CFeatureInfoPlugin
*/
class MFeatureInfoPluginCallback
{
public:
/**
Method to return data in response to a message from
a Feature Info plugin. The related ProcessCommandL call
must return before this method can be called.
@param aCommandId Command ID for which the response comes
@param aTransId Transcation identifier of
the original command
@param aData Data returned from call.
Data package contents are defined by command.
Can be deleted right after
ProcessResponseL has returned.
*/
virtual void ProcessResponseL(
const FeatureInfoCommand::TFeatureInfoCmd aCommandId,
const TUint8 aTransId,
TDesC8& aData ) = 0;
};
/**
Feature Manager ECOM Plugin interface class to be implemented by adaptation.
As it is an adaptation interface implementations are only loaded from ROM.
Implementations of this interface are created by the Feature Manager server
during start up in it's main thread where an Active Scheduler is installed.
Implementations must perform minmial work in ProcessCommandL() and return.
Plugin work and calls to ProcessResponseL() must be performed asynchronsly in
an active object callback running in the server's main thread.
For the command Ids and types used with this interface see definitions in the
FeatureInfoCommand namespace.
@see MFeatureInfoPluginCallback
@see KFeatureInfoPluginInterfaceUid
*/
class CFeatureInfoPlugin : public CBase
{
public: // construction and destruction
/**
Constructor method for instance.
Uses ECom to find correct instance.
@param aImplementationUid UID of the interface
implementation to instantiate.
@param aResponseCallback Reference to plugin callback handler.
*/
inline static CFeatureInfoPlugin* NewL(TUid aImplementationUid,
MFeatureInfoPluginCallback& aResponseCallback);
/**
Destructor
*/
inline virtual ~CFeatureInfoPlugin();
public:
/**
Method to invoke a particular command in the plugin.
Response to method is returned via separate ProcessResponseL
call. Call to ProcessResponseL is done after the call to
ProcessCommandL returns.
Leaves with error code KErrNotSupported if command ID is not
supported by the plug-in. If ProcessCommandL leaves, no corresponding
ProcessResponseL is expected.
@param aCommandId Command ID
@param aTransId Transaction ID
@param aData Data associated with command.
Data package contents are defined by command.
Some commands require no data and pass
empty buffer as aData.
@leave KErrNotSupported aCommandId not supported by plug-in.
*/
virtual void ProcessCommandL(
const FeatureInfoCommand::TFeatureInfoCmd aCommandId,
const TUint8 aTransId,
TDesC8& aData ) = 0;
protected:
/**
Callback pointer to be used with responses to commands.
This pointer is not owned by this class.
*/
MFeatureInfoPluginCallback* iResponseCallback; // not owned
private:
/** Destructor identifier to be used with ECom framework. */
TUid iDestructorIDKey;
};
#include <featmgr/featureinfoplugin.inl>
#endif // FEATUREINFOPLUGIN_H
// End of File