diff -r 000000000000 -r 08ec8eefde2f featuremgmt/featuremgr/inc/featureinfoplugin.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/featuremgmt/featuremgr/inc/featureinfoplugin.h Fri Jan 22 11:06:30 2010 +0200 @@ -0,0 +1,290 @@ +/* +* 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 +#include + + +// 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 iList; + }; + + /** Data package for ELoadFeatureInfoCmdId response structure */ + typedef TPckgBuf 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 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 + +#endif // FEATUREINFOPLUGIN_H + +// End of File