/*

* 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 with Caching

*

*/

#ifndef CMPXCOLLECTIONCACHEDHELPER_H

#define CMPXCOLLECTIONCACHEDHELPER_H

#include <f32file.h>

#include <apgcli.h>

#include "mpxcollectionhelperimp.h"

#include "mpxitemid.h"

#include <mpxcollectiontype.h>

// FORWARD DECLARATION

class CMPXMediaArray;

class CMPXMetadataExtractor;

/**

 *  Extended collection helper with caching capabilities

 *

 *  @lib mpxcollectionhelper

 *  @since S60 v3.1

 */

NONSHARABLE_CLASS( CMPXCollectionCachedHelper ) : public CMPXCollectionHelperImp

    {

public:

    static CMPXCollectionCachedHelper* NewL();

    static CMPXCollectionCachedHelper* NewLC();

    virtual ~CMPXCollectionCachedHelper();

protected:

    /**

    * Add a song or a playlist to the cache. This method will leave if

    * failed to add it to the cache. If this song or playlist fails to

    * be added to the collection when the cache is committed, client is

    * NOT notified. Failure to provide the required attributes will

    * result in such a failure.    

    *

    * @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.

    *

    */

    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.

    *

    * This API implementation is dedicated to MTP. Records in the 

    * collection will be deleted instead of being marked as deleted.

    *

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

    /**

    * Delete all records that have been marked as deleted.

    *

    * This API implementation is dedicated to MTP.

    */

    void CleanupDeletedMediasL();

    /**

    * Add an updated song or playlist to the cache. This method will leave if

    * failed to add it to the cache. If this song or playlist fails to

    * be updated in the collection when the cache is committed, client is

    * NOT notified. Failure to provide the required attributes will

    * result in such a failure.    

    *

    * 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 if the media

    *        isn't currently in the cache. If the media is currently in the

    *        cache, the media will fail to be added/updated in the collection

    *        and client is NOT notified.

    */

    void RenameL( const TDesC& aOldUri,

                  const TDesC& aNewUri,

                  TMPXGeneralCategory aItemCat );

    /**

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

    *

    * WARNING: Subsequent calls to this method will void the

    *          returned object reference. For example, client

    *          should avoid the following:

    *          CMPXMedia& song1 = GetL(***);

    *          CMPXMedia& song2 = GetL(***);

    *          song1.IsSupported(***);

    *          song2.IsSupported(***);

    *

    * @param aFile, path of the song/playlist

    *

    * @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 following attributes:

    *           KMPXMediaGeneralTitle

    *           KMPXMediaGeneralDate

    *           KMPXMediaGeneralDuration

    *           KMPXMediaGeneralComment    

    *           KMPXMediaMusicArtist

    *           KMPXMediaMusicAlbum

    *           KMPXMediaMusicAlbumTrack

    *           KMPXMediaMusicComposer

    *           KMPXMediaMusicYear

    *           KMPXMediaMusicGenre

    *           KMPXMediaMTPDrmStatus

    *           KMPXMediaAudioNumberOfChannels

    *           KMPXMediaAudioBitrate

    *           KMPXMediaAudioSamplerate

    *           KMPXMediaAudioAudioCodec

    *

    *         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).

    */

    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

    *    

    *    NOTE: results returned do not contain songs included in

    *          the category. To obtain songs included in the category,

    *          please refer to 2 and/or 3.

    *

    * 6) To find a particular playlist in the collection, here are the mandatory

    *    attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXItem

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXPlaylist

    *

    *    And one or all of the following attributes:

    *       KMPXMediaGeneralUri

    *       KMPXMediaGeneralTitle

    *       KMPXMediaIdGeneralId

    *

    *    NOTE: results returned do not contain songs included in the playlist.

    *          To obtain songs included in the playlist, please refer to 2.

    *

    * 7) To find a particular artist/album/genre/composer in the collection, here

    *    are the mandatory attributes:

    *    KMPXMediaGeneralType:

    *       must be EMPXItem

    *

    *    KMPXMediaGeneralCategory:

    *       must be EMPXArtist for artist

    *               EMPXAlbum for album

    *               EMPXGenre for genre

    *               EMPXComposer for composer

    *

    *    And one or all of the following attributes:

    *       KMPXMediaGeneralTitle

    *       KMPXMediaIdGeneralId

    *    

    *    NOTE:

    *    a) results returned do not contain songs included in the category.

    *       To obtain songs included in the category, please refer to 2.

    *    b) unknown artist/album/genre/composer will be the last item in

    *       the result array

    *

    * @param aAttrs, attributes to return

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