/*

* Copyright (c) 2007 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:  Collection helper abstract interface

*

*/

#ifndef MMPXCOLLECTIONHELPER_H

#define MMPXCOLLECTIONHELPER_H

#include <mpxmediageneraldefs.h>

#include <mpxcollectionhelperobserver.h>

// FORWARD DECLARATIONS

class CMPXMedia;

class TMPXAttribute;

/**

 *  Abstract class for collection helper. Use this class to add or remove songs and playlists from

 *  Music Player and Podcast app.

 *

 *  @lib mpxcollectionhelper.lib

 */

class MMPXCollectionHelper

    {

public:

    /**

    * Add an item based on file path and use the harvester to parse the file.

    * On completion MMPXCollectionHelperObserver::HandleAddFileCompleteL() 

    * is called back.

    *

 	  * @since S60 3.2.3

    * @param aFile full path and name of the file.

    * @param aObserver observer for the add operation

    */

    virtual void AddL( const TDesC& aFile, 

                       MMPXCollectionHelperObserver* aObserver ) = 0;

    /**

    * Add an item (song or playlist) with some media properties registers with playlists.

 	  * @since S60 3.2.3

    * @param aMedia media property to add.

    * @leave KErrArgument leave if the given media doesn't contain the correct attributes

    */

    virtual void AddL( CMPXMedia* aMedia ) = 0;

    /**

    * Remove a song, playlist, m3u file from the collection and from the harvester database.

 	  * @since S60 3.2.3

    * @param aFile file to remove.

    * @param aItemCat type of the item (optional).

    * @leave KErrArgument leave if the file to be removed does not exist

    */

    virtual void RemoveL( const TDesC& aFile, TMPXGeneralCategory aItemCat = EMPXSong) = 0; //lint !e1735

    /**

    * Remove all entries from the music, podcast and harvester databases.

 	  * @since S60 3.2.3

    */

    virtual void RemoveAllL() = 0;

    /**

    * Delete all records that have been marked as deleted.

 	  * @since S60 3.2.3

    * @leave KErrNotSupported Virtual Void function that will leave if called and not implemented

    */

    virtual void CleanupDeletedMediasL() = 0;

    /**

    * Updates the metadata for a file based on the path.

 	  * @since S60 3.2.3

    * @param aMedia media item to update.

    * @leave KErrArgument leave if the given media doesn't contain the correct attributes

    * 		or leave if not updating a song or a playlist

    */

    virtual void SetL( CMPXMedia*& aMedia ) = 0;

    /**

    * Renames a file.

 	  * @since S60 3.2.3

    * @param aOldUri existing URI of the file to be renamed.

    * @param aNewUri new URI of the file.

    * @param aItemCat category of the file either EMPXSong

    *        or EMPXPlaylist.

    * @leave KErrArgument leave if not updating a song or a playlist

    */

    virtual void RenameL( const TDesC& aOldUri,

                          const TDesC& aNewUri,

                          TMPXGeneralCategory aItemCat = EMPXSong ) = 0; //lint !e1735

    /**

    * Gets the metadata for a file.

 	  * @since S60 3.2.3

    * @param aFile path to the file.

    * @param aAttrs attributes to return.

    * @param aItemCat category of the file either EMPXSong

    *        or EMPXPlaylist.

    * @return Media object representing the given file with

    *         the requested attributes.    

    * @leave KErrArgument leave if not updating a song or a playlist.

    * @leave KErrNoMemory leave if search array is empty.

    * @leave KErrNotFound leave if array indexcount is 0.

    * @leave KErrCorrupt default case if the above conditions are not satisfied 

    * 		and object is not found

    */

    virtual CMPXMedia* GetL( const TDesC& aFile, 

                             const TArray<TMPXAttribute>& aAttrs,

                             TMPXGeneralCategory aItemCat = EMPXSong ) = 0; //lint !e1735

    /**

    * Gets the metadata for a file.

 	  * @since S60 3.2.3

    * @param aFile path to the file.

    * @param aItemCat category of the file either EMPXSong

    *        or EMPXPlaylist.

    * @return Media object representing the given file.

    * @leave KErrNotSupported Virtual const function that will leave if called and not implemented

    */

    virtual const CMPXMedia& GetL( const TDesC& aFile, 

                                   TMPXGeneralCategory aItemCat = EMPXSong ) = 0; //lint !e1735

    /**

    * Generic find function.

 	  * @since S60 3.2.3

    * @param aCriteria criterias to search upon.

    * @param aAttrs attributes to return.

    * @return Search results. found media(s) are accessible

    *         through KMPXMediaIdContainer/EMPXMediaArrayContents

    *         attribute    

    */

    virtual CMPXMedia* FindAllL( CMPXMedia& aCriteria, 

                                 const TArray<TMPXAttribute>& aAttrs) = 0;

    /**

    * Close the helper. 

    * @since S60 3.2.3

    */                

    virtual void Close() = 0;

    };

#endif // MMPXCOLLECTIONHELPER_H