/** @file

* Copyright (c) 2006-2007 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:  Interface for ECom plugins

*

*/

#ifndef C_UPNPPLUGININTERFACE_H

#define C_UPNPPLUGININTERFACE_H

// INCLUDE FILES

#include <e32base.h>

// FORWARD DECLARATIONS

class CGulIcon;

// CONSTANT DEFINITIONS

const TUid interfaceUid = { 0x200075DD };

/**

 * This event is sent from plugins to the MUPnPPluginObserver

 *

 * @since S60 3.2

 */

enum TExtensionEvent

    {

    // the extension is enabled by default - no need to call explicitly

    EExtensionEnabled = 0x0001,

    // when called, disables the item in the list, cannot execute

    EExtensionDisabled = 0x0002,

    // will call GetIcon again, and redraw

    EExtensionIconChanged = 0x0010,

    // will call GetTitle again, and redraw

    EExtensionTitleChanged = 0x0020,

    // will call GetSubTitle again, and redraw

    EExtensionSecondaryTextChanged = 0x0040,

    // extension which was ExecuteL'd, has been closed.

    EExtensionClosed = 0x0100

    };

/**

 * Implemented by CUPnPPluginLoader

 *

 * @since S60 3.2

 */

class MUPnPPluginObserver

    {

public:

    /**

     * Called by plugins when it needs updating.

     *

     * @since S60 3.2

     * @param aEvent event type sent from plugin

     */

    virtual void ExtensionEvent(const TExtensionEvent& aEvent)=0;

    /**

     * Virtual destructor 

     *

     * @since S60 3.2

     */

     virtual ~MUPnPPluginObserver() {}

    };

/**

 * ECom interface class which all home connect plugins have to implement.

 *

 * IMPORTANT!!!

 * 

 * Following methdods and attribute have to be implemented in the implementing

 * class as well so that observer argument can be passed correctly.

 * Example is given from all methods.

 *

 * private:

 *    // attribute

 *    MUPnPPluginObserver* iPluginObserver;

 *    

 *    // constructor

 *    // constructor has to be inherited from the interface constructor

 *    // the following way

 *    CUPnPPluginImplementation(TAny* aEcomArguments)

 *         : CUPnPPluginInterface( aEcomArguments ) {}

 *

 *    // ConstructL

 *    // ConstructL has to set its argument to the attribute

 *    void ConstructL(MUPnPPluginObserver* aPluginObserver) 

 *      {

 *      iPluginObserver = aPluginObserver;

 *      }

 *

 * public:

 *    // NewL

 *    // This has to give its argument to the constructor and pass it to

 *    // ConstructL as well

 *    static CUPnPPluginImplementation* NewL(MUPnPPluginObserver* 

 *                                             aPluginObserver)

 *      {

 *      CUPnPPluginImplementation* self = new(ELeave) 

 *                       CUPnPPluginImplementation( aPluginObserver );

 *      CleanupStack::PushL( self );

 *      self->ConstructL( aPluginObserver );

 *      CleanupStack::Pop( self );

 *      return self;

 *      }

 *

 *

 */

class CUPnPPluginInterface : public CBase

    {

public:

    /**

     * Creates instance of ECom plugin implementation which corresponds

     * the parameter aUid.

     *

     * @since S60 3.2

     * @param aUid - Uid of the plugin implementation

     * @param aPluginObserver - Call back to CUPnPPluginLoader

     * @return Instance of CUPnPPluginInterface

     */

    static CUPnPPluginInterface* NewL(TUid aUid,

                                    MUPnPPluginObserver& aPluginObserver);

    /**

     * Informs to ECom that it has been destroyed.

     *

     * @since S60 3.2

     */

    virtual ~CUPnPPluginInterface();

    //-------------------------------------------------------------------

    // ECom interface methods

    //-------------------------------------------------------------------

    /**

     * Returns reference to the icon of the plugin

     *

     * @since S60 3.2

     * @return Reference to the icon of the plugin

     */

    virtual const CGulIcon& GetIcon()=0;

    /**

     * Returns const reference to the icon of the plugin

     *

     * @since S60 3.2

     * @return const reference to the title of the plugin

     */

    virtual const TDesC& GetTitle()=0;

    /**

     * Returns const reference to the scondary text of the plugin

     *

     * @since S60 3.2

     * @return const reference to the secondary text of the plugin

     */

    virtual const TDesC& GetSecondaryText()=0;

    /**

     * Executes the plugin

     *

     * @since S60 3.2

     */

    virtual void ExecuteL()=0;

    /**

     * Checks if the plugin needs upnp configuration (set IAP)

     *

     * @since S60 3.2

     * @return Information whether plugin needs upnp configuration

     */

    virtual TBool RequiresUpnpConfiguration()=0;

protected:

    /**

     * Constructor. Sets plugin observer.

     *

     * @since S60 3.2

     * @param aPluginObserver - reference to CUPnPPluginObserver

     */

    CUPnPPluginInterface(TAny* aEcomArguments);

private:

    /**

     * Uid of the plugin

     */

    TUid iDtor_ID_Key;

    /**

     * Pointer to the plugin observer which handles the events plugin sends

     *

     * Not owned.

     */

    MUPnPPluginObserver& iPluginObserver;

    };

// inline methods

// ----------------------------------------------------------------------------

// CUPnPPluginInterface::NewL

// Constructor

// ----------------------------------------------------------------------------

inline CUPnPPluginInterface* CUPnPPluginInterface::NewL(TUid aUid,

                                  MUPnPPluginObserver& aPluginObserver)

    {

    TAny* arg = reinterpret_cast<TAny*>(&aPluginObserver);

    TAny* interface = REComSession::CreateImplementationL(aUid,

                           _FOFF(CUPnPPluginInterface,iDtor_ID_Key),arg);

    CUPnPPluginInterface* retval =

                   REINTERPRET_CAST(CUPnPPluginInterface*,interface);

    return retval;

    }

// ----------------------------------------------------------------------------

// CUPnPPluginInterface::~CUPnPPluginInterface

// Destructor

// ----------------------------------------------------------------------------

inline CUPnPPluginInterface::~CUPnPPluginInterface()

    {

    REComSession::DestroyedImplementation( iDtor_ID_Key );

    }

// ----------------------------------------------------------------------------

// CUPnPPluginInterface::CUPnPPluginInterface

// Constructor

// ----------------------------------------------------------------------------

inline CUPnPPluginInterface::CUPnPPluginInterface(TAny* aEcomArguments)

    : iPluginObserver(*(reinterpret_cast<MUPnPPluginObserver*>

                                        (aEcomArguments)))

    {

    }

#endif // C_UPNPPLUGININTERFACE_H

// end of file