/*
* 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:  provides playlist handling services for UPnP framework
*
*/


#ifndef C_UPNPPLAYLISTSERVICE_H
#define C_UPNPPLAYLISTSERVICE_H

// INCLUDES
#include <e32base.h>
#include <mpxcommonframeworkdefs.h> // for TMPXItemId

// FORWARD DECLARATIONS
class MMPXCollectionUtility;
class TMPXAttributeData;
class CMPXMedia;
class CUpnpItem;
class CUPnPMpxHelper;

// constants
const TInt KMaxPlaylistId = 32; // Maximum playlist ID length
const TInt KTempBufferSize = 255; // from DLNA

/**
 * A class providing abstract playlist handling services.
 * @lib upnpmusicadapter.lib
 * @since S60 v3.1
 */
class CUPnPPlaylistServices
    :public CBase
    {

public: // construction / destruction

    /**
     * Static constructor
     */
    IMPORT_C static CUPnPPlaylistServices* NewL();

    /**
     * desctuctor
     */
    virtual ~CUPnPPlaylistServices();

public: // component services

    /**
     * Lists all playlists in the music library.
     * Returns a list of playlist ID's and a names.
     * ID can be used to open or modify the playlist.
     * @param aPlaylistIds array to receive playlist ID's
     * @param aPlaylistNames array to receive playlist names
     */
    IMPORT_C void ListPlaylistsL(
        CDesCArray& aPlaylistIds,
        CDesCArray& aPlaylistNames );

    /**
     * Retrieves contents of given playlist.
     * @param aPlaylistId ID of the playlist
     * @param aContentMedia array to receive the content file paths
     */
    IMPORT_C void OpenPlaylistL(
        const TDesC& aPlaylistId,
        CDesCArray& aContentMedia );

    /**
     * Creates a record of a music track into the music library.
     * The media is assumed to exist already.
     * @param aTrackPath path to the track media
     * @param aTrackMetadata the upnp item for track metadata
     */
    IMPORT_C void CreateTrackL(
        const TDesC& aTrackPath,
        const CUpnpItem& aTrackMetadata );

    /**
     * Creates a playlist by given data into the music library.
     * The tracks should be introduced to MPX using CreateTrackL
     * prior to calling this method.
     * @param aPlaylistName the name of the playlist
     * @param aTrackPaths array of playlist content file paths
     * @param aPlaylistId receives the playlist ID (KMaxPlaylistId)
     *                    Can also be NULL, if ID is not needed.
     */
    IMPORT_C void CreatePlaylistL(
        const TDesC& aPlaylistName,
        const MDesCArray& aTrackPaths,
        TDes* aPlaylistId );

    /**
     * Adds a file into an existing playlist.
     * The track should be introduced to MPX using CreateTrackL
     * prior to calling this method.
     * @param aPlaylistId ID of the playlist
     * @param aTrackPath path to the track media
     */
    IMPORT_C void AddMediaToPlaylistL(
        const TDesC& aPlaylistId,
        const TDesC& aTrackPath );

    /**
     * Deletes a record of a music track from the music library.
     * Note that this does not delete the actual media.
     * @param aTrackPath the actual file path
     */
    IMPORT_C void DeleteTrackL(
        const TDesC& aTrackPath );

    /**
     * Deletes a record of a playlist from the music library.
     * Note that this does not delete the actual media.
     * @param aPlaylistId ID of the playlist
     */
    IMPORT_C void DeletePlaylistL(
        const TDesC& aPlaylistId );

    /**
     * Checks if the given track exists in the music library.
     * Note: does not check the existence of the actual media
     * @param aTrackPath the actual file path
     */
    IMPORT_C TBool IsValidTrackL(
        const TDesC& aTrackPath );

    /**
     * Checks if the given playlist exists in the music library.
     * Note: does not check the existence of the actual media
     * @param aPlaylistId ID of the playlist
     */
    IMPORT_C TBool IsValidPlaylistL(
        const TDesC& aPlaylistName );


protected: // private methods

    /**
     * category to be used in FindItemL
     */
    enum TFindCategory {
        ESongs,
        ESongByUri,
        EPlaylists,
        EPlaylistById,
        EPlaylistByTitle
    };

    /**
     * Finds a playlist according to given criteria.
     * @param find category (as in TMPXGeneralCategory)
     * @param aKey find key, depends on the category
     * @param aAttribute1 attribute to get (optional)
     * @param aAttribute2 attribute to get (optional)
     * @param aAttribute3 attribute to get (optional)
     * @return the playlist media, or NULL if not found
     */
    CMPXMedia* FindItemL(
        TFindCategory aCategory,
        const TDesC& aKey,
        const TMPXAttributeData* aAttribute1 = 0,
        const TMPXAttributeData* aAttribute2 = 0,
        const TMPXAttributeData* aAttribute3 = 0 );

    /**
     * Fetch a playlist content by id
     * @param aId playlist id
     * @return the playlist media, or NULL if not found
     */
    CMPXMedia* FetchPlaylistContentL( const TDesC& aId );

    /**
     * Converts an ID from TMPXItemId form to descriptor form.
     * conversion is guaranteed symmetric to Desc2Id()
     * @param aId the id in TMPXItemId form
     * @return the id string representation
     */
    const TDesC& Id2Desc( const TMPXItemId& aId );

    /**
     * Converts an ID from descriptor form to TMPXItemId form.
     * conversion is guaranteed symmetric to Id2Desc()
     * @param aDesc the id as a descriptor
     * @return the id extracted from the string
     */
    TMPXItemId Desc2Id( const TDesC& aDesc );

    /**
     * Finds an element within CUpnpItem
     * returns the element value converted to unicode,
     * pushed to cleanup stack.
     * @param aSource the source CUpnpItem
     * @param aSourceField the element name within source
     * @return the vield value, or 0 if element not found.
     */
    HBufC16* GetElementLC( const CUpnpItem& aSource,
        const TDesC8& aSourceField ) const;

private:

    /**
     * default constructor
     */
    CUPnPPlaylistServices();

    /**
     * 2nd phase constructor
     */
    void ConstructL();

private: // data

    /**
     * Collection utility of MPX framework
     */
    MMPXCollectionUtility*      iCollectionUtility;

    /**
     * internal helper for some MPX operations
     */
    CUPnPMpxHelper*             iMpxHelper;


    /**
     * temp buffer used in Id2Desc
     */
    TBuf<KTempBufferSize>       iTempBuffer;

    /**
     * ID of item currently processed asynchronously
     */
    TMPXItemId                  iCurrentId;

    /**
     * tells if collection plugin exists
     */
    TInt                        iStatus;
    };


#endif // C_UPNPPLAYLISTSERVICE_H