diff -r 000000000000 -r a2952bb97e68 mmappcomponents/collectionhelper/inc/mpxcollectionhelperimp.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappcomponents/collectionhelper/inc/mpxcollectionhelperimp.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,729 @@ +/* +* 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(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& 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& 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