/*
* 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 MMPXMediatorObserver
{
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
*
* 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)
* KMPXMediaGeneralFlags
* KMPXMediaGeneralCount
* KMPXMediaGeneralDate
*
* Supported attributes for artists/albums/genres/composers are:
* KMPXMediaIdGeneral:
* KMPXMediaGeneralId
* KMPXMediaGeneralTitle
*
* @return search results. The returned media contains the following
* attributes:
* KMPXMediaGeneralType:
* EMPXGroup
*
* KMPXMediaGeneralCategory:
* the category of the found media(s), e.g. EMPXSong for
* scenarios 1-4.
*
* KMPXMediaArrayCount:
* the number of matching media(s). 0 if no match found.
*
* KMPXMediaArrayContents:
* this array contains the found media(s). If client
* was looking for songs, each media in the array
* represents a song, similarly for artists, albums, genres,
* composers, and playlists. Each media contains
* KMPXMediaGeneralType:
* EMPXItem
* KMPXMediaGeneralCategory:
* category of the found media
*
* The rest of the attributes returned are as specified
* by the aAttrs parameter.
*/
CMPXMedia* FindAllL( CMPXMedia& aCriteria,
const TArray<TMPXAttribute>& aAttrs );
/**
* Frees this object
*/
void Close();
protected: // From Base Class
/**
* From MMPXHarvesterUtilityObserver
*/
void HandlePlaylistExportCompletedL( CMPXMedia* aProp,
TInt aErr );
/**
* From MMPXHarvesterUtilityObserver
*/
void HandlePlaylistImportCompletedL( CMPXMedia* aProp,
TInt aErr );
/**
* From MMPXHarvesterUtilityObserver
*/
void HandleFileAddCompletedL( CMPXMedia* aProp,
TInt aErr );
/**
* From MMPXHarvesterUtilityObserver
*/
void HandleDeleteCompletedL( TInt aErr );
/**
* From MMPXMediatorObserver
*/
void HandleMediatorPathUpdatedL( CMPXMedia*& aMedia,
TUid aOldPath );
/**
* From MMPXHarvesterUtilityObserver
*/
void HandleFileImportCompletedL( CMPXMedia* aMedia, TInt aErr );
/**
* From MMPXHarvesterUtilityObserver
*/
void HandleFileGetMediaCompletedL( CMPXMedia* aMedia, TInt aErr );
private:
/**
* Adds the file to the collection, constructs the collection path
* @param aMedia media item to add to the collection
*/
void DoAddToCollectionL( CMPXMedia* aMedia );
protected:
/**
* Private Constructor
*/
CMPXCollectionHelperImp();
/**
* 2nd Phased constructor
*/
void ConstructL();
protected: // data
MMPXHarvesterUtility* iHvsUtility;
MMPXCollectionUtility* iCollectionUtil;
CMPXCollectionMediator* iMediator;
MMPXCollectionHelperObserver* iObserver; // not owned
TUid iMusicCollectionId;
TBool iInitialized;
};
#endif // CMPXCOLLECTIONHELPERIMP_H