/*

* 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:  Collection helper implementation

*

*/

#ifndef CMPXCOLLECTIONHELPERIMP_H

#define CMPXCOLLECTIONHELPERIMP_H

#include "mpxcollectionhelper.h"

#include "mpxharvesterutilityobserver.h"

#include "mpxmediatorobserver.h"

// FOWARD DECLARATION

class MMPXHarvesterUtility;

class MMPXCollectionUtility;

class CMPXCollectionPath;

class CMPXMedia;

class CMPXCollectionMediator;

/**

 *  CMPXCollectionHelperImp

 *

 *  Wrapper implementation around collection utility

 *

 *  @lib mpxcollectionhelper.lib

 *  @since S60 3.1

 */

NONSHARABLE_CLASS( CMPXCollectionHelperImp ): public CBase,

                                              public MMPXCollectionHelper,

                                              public MMPXHarvesterUtilityObserver,

    {

public:

    /**

    * Two phased constructor

    */

    static CMPXCollectionHelperImp* NewL();

    /**

    * Two phased constructor

    */

    static CMPXCollectionHelperImp* NewLC();

    /**

    * Virtual destructor

    */

    virtual ~CMPXCollectionHelperImp();

protected: // From MMPXCollectionHelper

    /**

    * Asynchronously adds supported song file or a playlist file to the

    * collection and registers it with Harvester so it won't be re-parsed

    * unnecessarily during next scan/refresh.

    *

    * For a song file, its metadata will be extracted stored in the collection.

    *

    * For a playlist file, it will be parsed and added to the collection. If

    * the playlist refers to songs that already exist in the collection, any

    * song metadata provided in the playlist file will be ignored. If the

    * playlist refers to songs that do not exist in the collection, they

    * will be added to the collection with the metadata provided in the

    * playlist file, if any. However, these songs are NOT registered with

    * Harvester; hence, during next scan/refresh, these songs will be scanned

    * and updated in the collection unnecessarily and cause scan/refresh

    * performance degradation. If any metadata of these songs is changed in

    * the collection before next scan/refresh, it will be lost after

    * scan/refresh.

    *

    *   WARNING:

    *       Client must add the songs to the collection prior to adding the

    *       playlist.

    *

    * @param aFile, full path and name of the file which is a supported media

    *        type. KErrNotSupported if file type is not supported.

    *

    * @aObserver observer for the callback, HandleAddFileCompleteL. If NULL,

    * no callback is issued.

    *

    * If client is interested in the id of the song/playlist added, client

    * can retrieve it via GetL or FindAllL.

    */

    void AddL( const TDesC& aFile, MMPXCollectionHelperObserver* aObserver );

    /**

    * Add a song or a playlist synchronously

    *

    * @param aMedia, media to be added.

    *

    * To add a song to the collection, the media provided MUST

    * contain the following attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXItem

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXSong

    *

    *    KMPXMediaGeneralUri:

    *       full path of the song. Only supporting local path, i.e. path

    *       must starts with a drive letter.

    *

    *    Client must provide the metadata by filling other attributes. This

    *    song will be registered with Harvester so that it will not be

    *    unnecessarily scanned during the next scan/refresh.

    *

    * To add a playlist to the collection, the media provided MUST

    * contain the following attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXItem

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXPlaylist

    *

    *    KMPXMediaGeneralUri:

    *       Provide full path of the playlist if there is an associated

    *       physical playlist file.; otherwise, provide the path and

    *       directory where the playlist should be located (e.g. e:\playlists\).

    *       In the later case, playlist will be created in the collection

    *       as a virtual playlist and URI will be generated. If client is

    *       interested in this generated URI, client can perform a search

    *       based on the returned Id. Only supporting local path, i.e. path

    *       must starts with a drive letter.

    *

    *    KMPXMediaGeneralTitle:

    *       Title of the playlist is NOT enforced be unique within the

    *       music collection.

    *

    *    KMPXMediaArrayCount:

    *    KMPXMediaArrayContents:

    *       This playlist can be an empty playlist. If this is the case,

    *       KMPXMediaArrayContents will be a CMPXMediaArray that doesn't

    *       contain any media and KMPXMediaArrayCount will be 0.

    *

    *       Each CMPXMedia contained in the media array represents

    *       a song. Each song must contain the following attributes:

    *           KMPXMediaGeneralType:

    *               must be EMPXItem

    *

    *           KMPXMediaGeneralCategory:

    *               must be EMPXSong

    *

    *       For songs that already exist in the collection, client

    *       must provide either KMPXMediaGeneralId or KMPXMediaGeneralUri.

    *

    *       For songs that do not exist in the collection, client

    *       must provide KMPXMediaGeneralUri and its metadata.

    *       These songs will be added to the music collection when

    *       the playlist is added. These songs added to the collection

    *       are NOT registered with Harvester; hence, during next

    *       scan/refresh, these songs will be scanned and updated in

    *       the collection unnecessarily and cause scan/refresh

    *       performance degradation. If any metadata of these songs is

    *       changed in the collection before next scan/refresh, it will

    *       be lost after scan/refresh.

    *

    *       WARNING:

    *       Client must add the songs to the collection prior to adding

    *       the playlist.

    *

    *    WARNING:

    *    This playlist is NOT registered with Harvester. If client

    *    creates a physical playlist file, Harvester will re-parse

    *    and update the playlist in the collection during the next

    *    scan/refresh unnecessarily and cause scan/refresh performance

    *    degradation. If this playlist is edited, the physical

    *    playlist file is NOT updated to reflect the changes.

    *

    * This API does not support adding songs to a saved playlist.

    *

    * This method will leave with KErrArgument if any mandatory

    * is missing.

    *

    * If client is interested in the id of the song/playlist added,

    * client can retrieve it via this aMedia upon return of this

    * method. e.g.

    *

    *    TMPXItemId mediaId = aMedia->ValueTObjectL<TMPXItemId>(KMPXMediaGeneralId);

    */

    void AddL( CMPXMedia* aMedia );

    /**

    * Remove a song or a playlist from the collection. The correlating

    * file is not removed from the file system but this file is

    * de-registered with Harvester; hence, if the file isn't deleted

    * from the file system before the next scan/refresh, it will be

    * added back to the collection when scan/refresh is performed.

    *

    * @param aFile, file to remove.

    * @param aItemCat, category of the media to be removed. Either

    *        EMPXSong or EMPXPlaylist. Other categories, e.g. EMPXArtist,

    *        EMPXAlbum, EMPXGenre, and EMPXComposer cannot be removed

    *        from the collection with this method, they need to be removed

    *        from the collection via collection path.

    */

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

    /**

    * Remove all medias from the music collection regardless which drive

    * the medias are located and clear harvester's file registry. If the

    * media correlates to a file, the correlating file is not deleted from

    * the file system. If the file still exist during the next scan/refresh,

    * it will be added back to the collection.

    *

    *

    */

    void RemoveAllL();

    /**

    * Delete all records that have been marked as deleted.

    *

    * This API is dedicated to MTP and will leave with KErrNotSupported for

    * this implementation.

    */

    void CleanupDeletedMediasL();

    /**

    * Updates a media in the collection synchronously. For performance

    * consideration, it is recommended that client only sets the attribute

    * that needs to be updated.

    *

    * @param aMedia, media to be updated.

    *

    *        To update a song in the collection, the media provided MUST

    *        contain the following attributes:

    *           KMPXMediaGeneralType:

    *               must be EMPXItem

    *

    *           KMPXMediaGeneralCategory:

    *               must be EMPXSong

    *

    *           KMPXMediaGeneralUri:

    *               full path of the song. Only supporting local path,

    *               i.e. path must starts with a drive letter.

    *

    *        Additionally, this media should provide one or more of the

    *        following attributes for update:

    *               KMPXMediaGeneralTitle

    *               KMPXMediaGeneralComment

    *               KMPXMediaGeneralSynchronized

    *               KMPXMediaGeneralDeleted

    *               KMPXMediaGeneralModified

    *               KMPXMediaGeneralCopyright

    *               KMPXMediaGeneralDuration

    *               KMPXMediaGeneralFlags

    *               KMPXMediaGeneralPlayCount

    *               KMPXMediaGeneralLastPlaybackTime

    *           KMPXMediaIdMusic:

    *               KMPXMediaMusicArtist

    *               KMPXMediaMusicAlbum

    *               KMPXMediaMusicAlbumTrack

    *               KMPXMediaMusicGenre

    *               KMPXMediaMusicComposer

    *               KMPXMediaMusicYear

    *               KMPXMediaMusicRating

    *               KMPXMediaMusicAlbumArtFileName

    *               KMPXMediaMusicURL

    *           KMPXMediaIdAudio:

    *               KMPXMediaAudioSamplerate

    *               KMPXMediaAudioBitrate

    *               KMPXMediaAudioNumberOfChannels

    *           KMPXMediaIdDrm:

    *               KMPXMediaDrmType

    *           KMPXMediaIdMTP:

    *               KMPXMediaMTPDrmStatus

    *

    *        To update a playlist in the collection, the media provided MUST

    *        contain the following attributes:

    *           KMPXMediaGeneralType:

    *               must be EMPXItem

    *

    *           KMPXMediaGeneralCategory:

    *               must be EMPXPlaylist

    *

    *           KMPXMediaGeneralUri:

    *               full path of the playlist. Only supporting local path,

    *               i.e. path must starts with a drive letter.

    *

    *        If the media contains KMPXMediaArrayContents attribute, the

    *        content of the playlist will be overwritten with the new media

    *        array. If this attribute contains a CMPXMediaArray of 0 element,

    *        all songs in this playlist will be removed from the playlist

    *        (songs will remain in the collection and file system).

    *        e.g.

    *        1) "Playlist" originally contains "Song1", "Song2", and "Song3".

    *           If KMPXMediaArrayContents contains a CMPXMediaArray that

    *           contains "Song3" and "Song4", "Playlist" will be updated to

    *           contain "Song3" and "Song4".

    *        2) "Playlist" originally contains "Song1", "Song2", and "Song3".

    *           If KMPXMediaArrayContents contains a CMPXMediaArray that

    *           contains 0 element, "Playlist" will be updated so that it

    *           doesn't contain any songs. "Song1", "Song2", and "Song3"

    *           will remain in the collection.

    *

    *       If the media contains any of the following attributes, the

    *       playlist will be updated accordingly:

    *               KMPXMediaGeneralTitle

    *               KMPXMediaGeneralSynchronized

    *               KMPXMediaGeneralDeleted (DEPRECATED)

    *               KMPXMediaGeneralModified (DEPRECATED)

    *

    *       NOTE: If a client wishes to change the playlist title and modify

    *             its contents (i.e. the songs it includes), client needs to

    *             perform two separate SetL operations; one to update the

    *             playlist title providing KMPXMediaGeneralTitle attribute

    *             and the other to update its contents by providing

    *             KMPXMediaArrayContents.

    *

    */

    void SetL( CMPXMedia*& aMedia );

    /**

    * Changes the URI of a song or a playlist.

    *

    * @param aOldUri exiting URI of the song or playlist

    * @param aNewUri of the song or playlist

    *

    *   If a client requests the URI of a song to be changed, the corresponding

    *   song file will NOT be moved to the new location. Harvester's file registration

    *   will be updated, as well as the collection. Client MUST ensure that there

    *   is not already a file at the specified new location in the file system

    *   (Same restrictions as RFs::Rename) and the collection.

    *

    *   WARNING: For virtual playlists (i.e. playlists created from the device.

    *            They are referred to as virtual because there is no physical

    *            playlist file created), client MUST ensure the new URI doesn't

    *            clash with any existing playlist in the collection, as well as

    *            in the file system. Changing their filenames is NOT recommended.

    *            If a client wishes to change the extension of the virtual playlist,

    *            it's recommended the extension is changed to an extension that's

    *            not supported by any playlist plugin exists in the system.

    *

    *   Upon successful completion of this operation, the Id of the song/playlist

    *   will be changed in the collection. If client is interested in the Id of

    *   this media hereafter, GetL or FindAllL can be performed (search by new URI).

    *

    * @param aItemCat category of the file, either EMPXSong or EMPXPlaylist;

    *        otherwise, this method leaves with KErrArgument.

    */

    void RenameL( const TDesC& aOldUri,

                  const TDesC& aNewUri,

                  TMPXGeneralCategory aItemCat );

    /**

    * Gets the media for the song or playlist via its URI

    *

    * @param aFile, path of the song/playlist

    * @param aAttrs, what attributes to get back.

    *        Supported attributes for songs are:

    *           KMPXMediaIdGeneral:

    *               KMPXMediaGeneralId

    *               KMPXMediaGeneralTitle

    *               KMPXMediaGeneralUri

    *               KMPXMediaGeneralDrive

    *               KMPXMediaGeneralDuration

    *               KMPXMediaGeneralDate

    *               KMPXMediaGeneralComment

    *               KMPXMediaGeneralMimeType

    *               KMPXMediaGeneralSynchronized

    *               KMPXMediaGeneralDeleted

    *               KMPXMediaGeneralModified

    *               KMPXMediaGeneralCopyright

    *               KMPXMediaGeneralFlags

    *               KMPXMediaGeneralPlayCount

    *               KMPXMediaGeneralLastPlaybackTime

    *           KMPXMediaIdMusic:

    *               KMPXMediaMusicArtist

    *               KMPXMediaMusicAlbum

    *               KMPXMediaMusicAlbumTrack

    *               KMPXMediaMusicGenre

    *               KMPXMediaMusicComposer

    *               KMPXMediaMusicYear

    *               KMPXMediaMusicRating

    *               KMPXMediaMusicAlbumArtFileName

    *               KMPXMediaMusicURL

    *           KMPXMediaIdAudio:

    *               KMPXMediaAudioSamplerate

    *               KMPXMediaAudioBitrate

    *               KMPXMediaAudioNumberOfChannels

    *               KMPXMediaAudioCodec

    *           KMPXMediaIdMTP:

    *               KMPXMediaMTPDrmStatus

    *

    *        Supported attributes for playlists are:

    *           KMPXMediaIdGeneral:

    *               KMPXMediaGeneralId

    *               KMPXMediaGeneralCollectionId

    *               KMPXMediaGeneralTitle

    *               KMPXMediaGeneralUri

    *               KMPXMediaGeneralDrive

    *               KMPXMediaGeneralSynchronized

    *               KMPXMediaGeneralDeleted (DEPRECATED)

    *               KMPXMediaGeneralModified (DEPRECATED)

    *               KMPXMediaGeneralFlags

    *               KMPXMediaGeneralCount

    *               KMPXMediaGeneralDate

    *

    * @param aItemCat category of the file, either EMPXSong or

    *        EMPXPlaylist; otherwise, this method leaves with

    *        KErrArgument.

    *

    * @return media object representing the given file with

    *         the requested attributes. Note that the playlist

    *         media object does not contain songs included in

    *         the playlist. If client is interested in finding

    *         the songs in the playlist, FindAllL can be used

    *         (please see #2 in FindAllL).

    */

    CMPXMedia* GetL( const TDesC& aFile,

                     const TArray<TMPXAttribute>& aAttrs,

                     TMPXGeneralCategory aItemCat );

    /**

    * Gets the media for the song or playlist via its URI

    *

    * This implementation do not support this method.

    */

    const CMPXMedia& GetL( const TDesC& aFile,

                           TMPXGeneralCategory aItemCat );

    /**

    * Find media(s) in music collection.

    *

    * @param aCriteria, criteria to search upon

    *

    * 1) To find all songs in the collection, here are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXGroup

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXSong

    *

    *    If the following optional attributes are provided, the search results

    *    are narrowed down further: (these attributes can be combined)

    *       KMPXMediaGeneralTitle

    *           ==> songs with the specified title

    *       KMPXMediaGeneralDrive

    *           ==> songs in the specified drive

    *       KMPXMediaGeneralSynchronized

    *           ==> songs that are/are not synchronized through MTP

    *       KMPXMediaGeneralDeleted

    *           ==> songs that are/are not marked as deleted since the last MTP

    *               session

    *       KMPXMediaGeneralModified

    *           ==> songs that are/are not modified since the last MTP session

    *

    * 2) To find all songs for a particular artist/album/genre/composer/playlist

    *    in the collection, here are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXGroup

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXSong

    *

    *    KMPXMediaIdGeneralId:

    *       the Id of the artist/album/genre/composer/playlist

    *

    *    NOTE: Songs in an album are sorted by album track, then title, except

    *          for songs in the unknown album. Songs in the unknown album are

    *          sorted by title.

    *

    * 3) To find all songs for a particular album of an artist in the collection,

    *    here are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXGroup

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXSong

    *

    *    KMPXMediaIdGeneralId:

    *       the Id of the album

    *

    *    KMPXMediaGeneralContainerId:

    *       the Id of the artist

    *

    *    NOTE: These songs are sorted by album track, then title, except

    *          for songs in the unknown album. Songs in the unknown album are

    *          sorted by title.

    *

    * 4)To find a particular song, here are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXItem

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXSong

    *

    *    And one or all of the following attributes:

    *       KMPXMediaGeneralUri

    *       KPXMediaIdGeneralId

    *

    * 5) To find all artists/albums/genres/composers/playlists in the

    *    collection, here are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXGroup

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXArtist for artists

    *               EMPXAlbum for albums

    *               EMPXGenre for genres

    *               EMPXComposer for composers

    *               EMPXPlaylist for playlists

    *

    *    If the following optional attributes are provided for playlists,

    *    the search results are narrowed down further: (these attributes

    *    can be combined)

    *       KMPXMediaGeneralDrive

    *           ==> playlists in the specified drive

    *       KMPXMediaGeneralSynchronized

    *           ==> playlists that are/are not synchronized through MTP

    *       KMPXMediaGeneralDeleted (DEPRECATED)

    *           ==> playlists that are/are not marked as deleted since the last MTP

    *               session

    *       KMPXMediaGeneralModified (DEPRECATED)

    *           ==> playlists that are/are not modified since the last MTP session

    *