/*
* 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