/*

* 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