/*

* Copyright (c) 2005, 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:  Defines a ECom plug-in interface

*

*/

#ifndef SYSAPKEYHANDLERPLUGININTERFACE_H

#define SYSAPKEYHANDLERPLUGININTERFACE_H

// INCLUDES

#include <ecom/ecom.h>

#include <e32base.h>

#include <sysapcallback.h>

//CONSTANTS

//Interface UID for KEF plugins

const TUid KSysapKeyHandlerPluginInterfaceUid = {0x10207131};

// FORWARD DECLARATIONS

//CLASS DECLARATION

/**

*  CSysapKeyHandlerPlugin class. This class serves as an interface between 

*  SysAp and the plugins.

*

*  @since S60 3.1

*/  

class CSysapKeyHandlerPlugin : public CBase

    {

    public: // Constructors and destructor

        /**

        * Description: Wraps ECom object instantitation. Will return the

        *              default interface implementation, which matches to given

        *              aUid.

        *

        * Note:        This is not a "normal" NewL method, since normally NewL

        *              methods are only defined for concrete classes.

        *              Note that also implementations of this interface

        *              provide NewL methods. They are the familiar NewL's,

        *              which create instance of classes.

        *

        * @since S60 3.1

        * @param aUid Uid of the plugin to be instantiated

        * @param aCallback pointer to object that will implement a callback interface. Cannot be NULL.

        * @return pointer to the created object.

        */

        inline static CSysapKeyHandlerPlugin* NewL( TUid aUid, MSysapCallback* aCallback );

        /**

        * Destructor

        */

        inline virtual ~CSysapKeyHandlerPlugin();

    public:

        /**

        * Handles key events

        *

        * @since S60 3.1

        * @param aKeyEvent contains information about the key event

        * @param aType contains information about the type of the key event

        * @return response

        */

        virtual TKeyResponse HandleKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType )=0;

        /**

        * Provides the key events that the plugin wants to listen to.

        * Plugins should overload this method if they are of version 2 or higher.

        * iCode, iScanCode and iModifiers MUST be defined in each TKeyEvent.

        *

        * @since S60 5.1

        * @return array of key events

        */

        virtual void ProvideKeyEventsL( RArray<TKeyEvent>& aKeyEventArray );

    protected:

        /**

        * An additional phase for derived class construction.

        * 

        * This method is called immediately after the plug-in has been loaded. 

        * Derived classes may overload this method, if they need to perform initializations

        * that require usage of the callback pointer (obtained via SysapCallback()-function).

        * 

        * @since S60 3.1

        * @leave system wide error code

        * @see CSysapKeyHandlerPlugin::SysapCallback

        */

        virtual void PostConstructL() {}

        /**

        * Returns pointer to callback object.

        * 

        * @since S60 3.1

        * @return MSysapCallback*

        * @pre plug-in hase been loaded successfully

        * @panic KErrGeneral raised if method is called during construction.

        *                    Place the initialization code that needs this function into PostConstructL().

        * @see CSysapKeyHandlerPlugin::PostConstructL

        */

        inline MSysapCallback* SysapCallback();

    private:

        /** 

        * Instance identifier key. When instance of an

        * implementation is created by ECOM framework, the

        * framework will assign UID for it. The UID is used in

        * destructor to notify framework that this instance is

        * being destroyed and resources can be released.

        */

        TUid iDtor_ID_Key;

        /**

        * Pointer to callback object.

        * Not own.

        */

        MSysapCallback* iCallback;

        };

// This includes the implementation of the instantiation functions and

// destructor

#include <sysapkeyhandlerplugininterface.inl>

#endif