/*

* Copyright (c) 2006-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:

* This file contains the class declarations for the plugin service and callback APIs.

*

*/

/**

 @file

 @publishedPartner

 @released

*/

#ifndef HWRMPLUGINSERVICE_H

#define HWRMPLUGINSERVICE_H

// INCLUDES

#include <e32base.h>

/** ECOM Plugin interface UID 

@publishedPartner

@released

*/

const TUid KCHWRMPluginServiceInterfaceUid = { 0x10205028 };

/**

*  Callback interface for the HWRM plugins.

*  Used to return data and/or error codes from an asynchronous plugin calls.

*  invoked by the HWRM server.

* 

@publishedPartner

@released

*/

class MHWRMPluginCallback

    {

    public:

        /**

        * Method to return data in response to a message from a HWRM plugin.

        * Related ProcessCommandL call must return before this method can

        * be called.

        *

        * @param aCommandId Command ID for which the response comes

        * @param aTransId   Unique transcation identifier of the original command

        * @param aData      Data returned from call. 

        *                   Data package contents are defined by command.

        * @leave Standard Symbian leaves if there are any problems handling response.

        */

        virtual void ProcessResponseL( const TInt aCommandId,

                                       const TUint8 aTransId, 

                                       TDesC8& aData ) = 0;

        /**

        * Method to notify events to a HWRM plugin.

        * Note: No implementation yet.

        *

        * @param aIndId An indication ID

        * @param aData  Data associated with the event ID. 

        *

        */

        virtual void EventL( const TUint32 aIndId,

                             TDesC8& aData ) = 0;

    };

/**

*  Plugin interface class to be implemented by adaptation.

*  Responsible for invoking the adaptation implementation of

*  each command and cancelling the command.

*

@publishedPartner

@released

*/

class CHWRMPluginService : public CBase

    {

    public:  // construction and destruction

        /**

        * Constructor method for instance.

        * Uses ECom to find correct instance.

        *

        * @param aMatch Determines the API that the loaded plugin implements.

        * @param aResponseCallback Pointer to plugin callback handler.

        * @leave Standard Symbian leaves.

        */

        inline static CHWRMPluginService* NewL(const TDesC8& aMatch,

                                               MHWRMPluginCallback* aResponseCallback);

        /**

        * Destructor

        */

        inline virtual ~CHWRMPluginService();       

    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. Plugin must be able to handle another

        * ProcessCommandL before ProcessResponseL is called for previous

        * call(s) (i.e. multiple clients are attempting to access resource

        * simultaneously). 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 KErrGeneral or command specific leaves.

        */

        virtual void ProcessCommandL( const TInt aCommandId,

                                      const TUint8 aTransId,

                                      TDesC8& aData ) = 0;

        /**

        * Method to cancel a particular command. The corresponding

        * ProcessResponseL will not be called for cancelled commands,

        * whether cancel was successful or not. 

        *

        * @param aTransId   Transaction ID

        * @param aCommandId Command ID to optionally double check with the 

        *                   transaction ID

        * @leave Standard Symbian leaves. HWRM will consider

        *            transaction canceled even if this method leaves. 

        */

        virtual void CancelCommandL( const TUint8 aTransId, 

                                     const TInt aCommandId) = 0;

   protected:

        /**

        * Destructor identifier to be used with ECom framework.

        */

        TUid iDestructorIDKey;

        /**

        * Callback pointer to be used with responses to commands.

        * This pointer is not owned by this class.

        */

        MHWRMPluginCallback* iResponseCallback;  // not owned

    };

#include <hwrm/hwrmpluginservice.inl>

#endif      // HWRMPLUGINSERVICE_H   

// End of File