diff -r 000000000000 -r a2952bb97e68 mmappcomponents/collectionhelper/inc/mpxcollectioncachedhelper.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappcomponents/collectionhelper/inc/mpxcollectioncachedhelper.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,716 @@ +/* +* 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 +#include +#include "mpxcollectionhelperimp.h" +#include "mpxitemid.h" +#include + +// 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) + * 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: + + /** + * Commits the transactions still left in the caching array + */ + void Commit(); + +private: + + /** + * Appends General Media Type information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendGeneralL( CMPXMedia& aSrc, CMPXMedia& aDestination ); + + /** + * Appends Music Type information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendMusicL( CMPXMedia& aSrc, CMPXMedia& aDestination ); + + /** + * Appends Audio Type information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendAudioL( CMPXMedia& aSrc, CMPXMedia& aDestination ); + + /** + * Appends DRM Type information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendDRML( CMPXMedia& aSrc, CMPXMedia& aDestination ); + + /** + * Appends array information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendContainerL( CMPXMedia& aSrc, CMPXMedia& aDestination ); + + /** + * Appends MTP information + * @param aSrc source media to copy attributes from + * @param aDestination destination media to copt attributes to + */ + void DoAppendMTPL( CMPXMedia& aSrc, CMPXMedia& aDestination ); + +#ifdef RD_MPX_COLLECTION_CACHE + + /* + * Gets the media for the song or playlist via its URI + * Note. This is used in conjunction with exported GetL + * This method does not perform cache capability but only returns + * the media object requested. + * + * @param aFile, path of the song/playlist + * + * @param aItemCat category of the file, either EMPXSong or + * EMPXPlaylist; otherwise, this method leaves with + * KErrArgument. + * + * @return void + * the result of iFoundMedia media object representing the given file with + * the following attributes: + * KMPXMediaGeneralTitle + * KMPXMediaGeneralDate + * KMPXMediaGeneralDuration + * KMPXMediaGeneralComment + * KMPXMediaMusicArtist + * KMPXMediaMusicAlbum + * KMPXMediaMusicAlbumTrack + * KMPXMediaMusicComposer + * KMPXMediaMusicYear + * KMPXMediaMusicGenre + * KMPXMediaMTPDrmStatus + * KMPXMediaAudioNumberOfChannels + * KMPXMediaAudioBitrate + * KMPXMediaAudioSamplerate + */ + void GetSongL( const TDesC& aFile, TMPXGeneralCategory aItemCat, TUid aCollectionUId ); + + /* + * Gets the artist id of the media object inthe currect context (result of GetL()) + * + * @param aCollectionUid TUid + * + * @return void + * the result of iFoundMedia media object representing the given file with + */ + TMPXItemId GetArtistIdL( const TDesC& aArtist, TUid aCollectionUId ); + + + /* + * Gets all the songs that are belongs to the same artist id supplied + * + * @param id TMPXItemId indicates the id for requesting artist + * @param aCollectionUid TUid + * @param aUnknownArtist TBool indicates if this is for unknown artist or not + * + * @return void + * the result of iCachedArtistArray media object + */ + void GetSongsL( TMPXItemId id, TUid aCollectionUId, TBool aUnknownArtist ); + +#endif //RD_MPX_COLLECTION_CACHE + + +private: + + enum TCachedOp + { + EAdd, + ESet + }; + +private: + + CMPXCollectionCachedHelper(); + + void ConstructL(); + +private: // data + + CMPXMedia* iFoundMedia; + CMPXMediaArray* iCache; + RArray iOp; +#ifdef RD_MPX_COLLECTION_CACHE + CMPXMediaArray* iCachedArtistArray; + CMPXMediaArray* iCachedUnknownArtistArray; + TBool iNotInCache; + TInt iHitFoundMedia; + TInt iNotHitInCache; + TInt iLookingInCache; + TInt iLookingInUnknowCache; +#endif //RD_MPX_COLLECTION_CACHE + CMPXMetadataExtractor* iMetadataExtractor; + RFs iFs; + RApaLsSession iAppArc; + RPointerArray iSupportedTypes; + }; + +#endif // C_MPXCOLLECTIONCACHEDHELPER_H