/*

* 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