/*

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

*

*/

#ifndef CMPXPLAYBACKPLUGIN_H

#define CMPXPLAYBACKPLUGIN_H

// INCLUDES

#include <ecom/ecom.h>

#include <mpxplaybackframeworkdefs.h>

#include <mpxattribute.h>

#include <mpxattributespecs.h>

#include <mpxcommand.h>

// FORWARD DECLARATIONS

class MMPXPlaybackPluginObserver;

// CONSTANTS

const TUid KMPXPlaybackInterfaceUid={0x101FFC05};

// CLASS DECLARATION

/**

*  Interface to play media.

*

*  @lib mpxcommon.lib

*/

NONSHARABLE_CLASS(CMPXPlaybackPlugin): public CBase

    {

public: // Constructors and destructor

    /**

    * Two-phased constructor.

    *

    * @since S60 3.2.3

    * @param aUid uid of interface implementation

    * @param aObs observer

    * @return object of constructed

    */

    inline static CMPXPlaybackPlugin* NewL(TUid aUid,

                                      MMPXPlaybackPluginObserver& aObs);

    /**

    * Two-phased constructor.

    *

    * @since S60 3.2.3

    * @param aUid uid of interface implementation

    * @return object of constructed

    */

    inline static CMPXPlaybackPlugin* NewL(TUid aUid);

    /**

    * Destructor.

    *

    * @since S60 3.2.3

    */

    inline virtual ~CMPXPlaybackPlugin();

public:

    /**

     * Implementation uid of plugin.

     *

     * @since S60 3.2.3

     */

    inline const TUid& Uid();

    /**

    * Set observer.

    *

    * @since S60 3.2.3

    * @param aObs observer

    */

    virtual inline void SetObserver(MMPXPlaybackPluginObserver& aObs);

    /**

    * Initializes a song for playback.

    *

    * @since S60 3.2.3

    * @param aSong the song path

    */

    virtual void InitialiseL(const TDesC& aSong)=0;

    /**

    * Initializes a song for playback.

    *

    * @since S60 3.2.3

    * @param aFile file handle of a song

    */

    virtual void InitialiseL(RFile& aSong)=0;

    /** 

    * Executes a command on the selected song.

    *

    * @since S60 3.2.3

    * @param aCmd a command

    * @param aData data (optional)

    * @deprecated Use method CMPXPlaybackPlugin::CommandL(

    *     CMPXCommand& aCmd) instead.

    */

    virtual void CommandL(TMPXPlaybackCommand aCmd, TInt aData=0)=0;

    /**

     * Executes a command.

     *

     * @since S60 3.2.3

     * @param aCmd a command

     */

     virtual void CommandL(CMPXCommand& /*aCmd*/)

         {/*Note: All clients need to implement this */}

    /**

    * Sets a property of the plugin.

    *

    * @since S60 3.2.3

    * @param aProperty a playback property

    * @param aValue the value of the property

    */

    virtual void SetL(TMPXPlaybackProperty aProperty, TInt aValue)=0;

    /** 

     * Gets a property of the plugin (async).

     *

     * Plugin has to implement either ValueL or PropertyL. But the plugin can not

     * implement both of the functions. Otherwise, there will be circular function call.

     *

     * @since S60 3.2.3

     * @param aProperty a property

     * @deprecated Use method CMPXPlaybackPlugin::PropertyL(

     *        TMPXPlaybackProperty aProperty) instead.

     * Note: please call PropertyL in the downloadproxy plugin.

     */

    virtual void ValueL(TMPXPlaybackProperty aProperty) const

         {

         // Call the propertyL of the plugin which does not implement the ValueL

         PropertyL(aProperty);

         }

     /**

      * Gets a property of the plugin (async).

      * Result will be called back in HandleProperty.

      *

      * @since S60 3.2.3

      * @param aProperty a property

      */

    virtual void PropertyL(TMPXPlaybackProperty aProperty) const

         {

         //Note: change into pure virtual when all plugins implement the api

         //Default map to ValueL of the plugin which does not implement the PropertyL

         ValueL(aProperty);

         }

    /**

    * Gets a list of sub players.

    *

    * @since S60 3.2.3

    * @return a list of names of sub players

    */

    virtual void SubPlayerNamesL()=0;

    /**

    * Select a sub player.

    *

    * @since S60 3.2.3

    * @param aIndex index to the sub player

    */

    virtual void SelectSubPlayerL(TInt aIndex)=0;

    /**

    * Returns current sub player name.

    *

    * @since S60 3.2.3

    * @return friendly name of the current the sub player

    */

    virtual const TDesC& SubPlayerName()=0;

    /**

    * Current sub player index.

    *

    * @since S60 3.2.3

    * @return index to the sub player

    */

    virtual TInt SubPlayerIndex() const=0;

    /**

    * Implement the version with CMPXAttributeSpecs instead.

    * This will be removed in a future release.

    *

    * Extended properties of the current file (async).

    *

    * @since S60 3.2.3

    * @param aAttrs attributes requested

    * @deprecated Use method CMPXPlaybackPlugin::MediaL(

    *       const TArray<TMPXAttribute>& aAttrs,

    *       CMPXAttributeSpecs* aSpecs ) instead.

    */

    virtual void MediaL(const TArray<TMPXAttribute>& aAttrs)=0;

    /**

    * Should make this pure virtual in the future when

    * the previous API is removed and all client has implement

    * this API.

    *

    * Extended properties of the current file (async).

    *

    * @since S60 3.2.3

    * @param aAttrs attributes requested

    * @param aSpecs attribute spec, ownership not passed

    */

    virtual void MediaL(

        const TArray<TMPXAttribute>& aAttrs,

        CMPXAttributeSpecs* /*aSpecs*/ )

        {

        MediaL( aAttrs );

        };

    /**

    * Cancel outstanding request.

    *

    * @since S60 3.2.3

    */

    virtual void CancelRequest()=0;

protected:

    MMPXPlaybackPluginObserver*  iObs; // Not owned

private: // Data

    // identifies the actual plugin instance

    TUid iDtorKey;

    TUid iUid; //Implementation uid of the plugin

    };

#include "mpxplaybackplugin.inl"

#endif      // CMPXPLAYBACKPLUGIN_H