/*

* 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:  Playlist plugin interface

*

*/

#ifndef MPXPLAYLISTPLUGIN_H

#define MPXPLAYLISTPLUGIN_H

#include <ecom/ecom.h>

#include <charconv.h>

#include <mpxmedia.h>

// FORWARD DECLARATIONS

class MMPXPlaylistPluginObserver;

/**

*  CMPXPlaylistPlugin: Defines the playlist plugin interface.

*

*  A playlist plugin is instantiated and owned by CMPXPlaylistPluginHandler.

*  But the client of the services a playlist plugin provides is

*  CMPXPlaylistEngine.

*

*/

NONSHARABLE_CLASS(CMPXPlaylistPlugin): public CBase

    {

public:

    /**

    * Factory method to instantiate a playlist plugin with the matching UID

    *

    * @param aUid uid of interface implementation

    * @param aObserver a playlist plugin observer

    * @param aFs a handle to file session

    * @param aTopCharacterSet top character set for the current locale

    * @param aAvailableCharacterSet available character set in the sytem

    * @return constructed object

    */

    inline static CMPXPlaylistPlugin* NewL(

        TUid aUid, 

        MMPXPlaylistPluginObserver& aObserver,

        RFs& aFs,

        const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aTopCharacterSet,

        const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aAvailableCharacterSet);

    /**

    * Destructor

    */

    virtual ~CMPXPlaylistPlugin();

public: 

    /** 

    * Internalize a playlist. A MMPXPlaylistPluginObserver::HandlePlaylistL

    * callback will be generated on completion.

    *

    * Parameters are guaranteed by the caller (i.e. CMPXPlaylistEngine) to

    * exist until plugin completes this request.

    *

    * @param aStatus caller's request status

    * @param aPlaylistUri URI of the playlist to be internalized

    */

    virtual void InternalizePlaylistL(

        TRequestStatus& aStatus,

        const TDesC& aPlaylistUri) = 0;

    /** 

    * Externalize a playlist. a MMPXPlaylistPluginObserver::HandlePlaylistL

    * callback will be generated on completion.

    *

    * Parameters are guaranteed by the caller (i.e. CMPXPlaylistEngine) to

    * exist until plugin completes this request.

    *

    * @param aStatus caller's request status

    * @param aPlaylist a playlist to be externalized. This media contains

    *        the following attributes:

    *

    *            KMPXMediaGeneralTitle

    *            KMPXMediaGeneralType:

    *               This contains the value of EMPXItem

    *            KMPXMediaGeneralCategory:

    *               This contains the value of EMPXPlaylist

    *            KMPXMediaArrayContents

    *            KMPXMediaArrayCount

    *

    *        Each media item in the playlist is guaranteed to contain the

    *        following attributes:

    *

    *            KMPXMediaGeneralType:

    *               This contains the value of EMPXItem

    *            KMPXMediaGeneralCategory:

    *               This contains the value of EMPXSong

    *

    *            The rest of attributes may or may not be present. Client

    *            is recommended to call RequiredAttributes before making

    *            a request to export the playlist and provide attributes

    *            required for each media item in the playlist. However,

    *            not every client will be able to comply and supply the

    *            required attributes, specifically client may store the

    *            information about the media item in a memory card and

    *            memory card has been removed from the device. Each

    *            playlist plugin MUST be capable of handling the media

    *            item containing only the URI in addition to its type and

    *            category.

    *

    * @param aFilePath File path for where the playlist should be placed

    */

    virtual void ExternalizePlaylistL(

        TRequestStatus& aStatus,

        const CMPXMedia& aPlaylist,

        const TDesC& aFilePath) = 0;

    /**

    * Required attributes for the media items in the playlist in order to

    * externalize them to a playlist. Client is recommended to call this

    * method and provide the required attributes for each media item in

    * the playlist before externalizing the playlist.

    *

    * @return an array of attributes required in order to externalize

    * a playlist media into a playlist file.

    */

    virtual const TArray<TMPXAttribute> RequiredAttributes() const = 0;

    /**

    * Optional attributes for the media items in the playlist for externalizing

    * them to a playlist.

    *

    * @return an array of attributes which are optional when externalizing

    * a playlist media into a playlist file

    */

    virtual const TArray<TMPXAttribute> OptionalAttributes() const = 0;

    /**

    * Returns the file extension the plugin handles

    *

    * @return file extension which includes the period.

    */

    virtual const TDesC& FileExtension() const = 0;

    /**

    * Cancel request

    */        

    virtual void Cancel() = 0;

protected:

    MMPXPlaylistPluginObserver*  iObserver; // not owned

    RFs*                         iFs;       // not owned

    const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iTopCharacterSet;      // not owned

    const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iAvailableCharacterSet;// not owned

private:

    // identifies the actual plugin instance

    TUid iDtorKey;

    };

#include "mpxplaylistplugin.inl"

#endif      // MPXPLAYLISTPLUGIN_H