diff -r 000000000000 -r a2952bb97e68 mmappfw_plat/collection_helper_api/inc/mpxcollectionuihelper.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappfw_plat/collection_helper_api/inc/mpxcollectionuihelper.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,293 @@ +/* +* 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 Ui Helper interface class +* +*/ + +#ifndef MMPXCOLLECTIONUIHELPER_H +#define MMPXCOLLECTIONUIHELPER_H + +#include +#include +#include + +// FORWARD DECLARATIONS +class CMPXCollectionPath; +class CMPXCollectionPlaylist; +class CMPXMedia; +class MMPXCHelperObserver; +class MMPXCHelperEmbeddedOpenObserver; + +/** + * Abstract class for collection ui helper. Performs operation on playlist object. + * Enables client to add, rename, etc a song to a playlist or add a particular property. + * + * @lib mpxcollectionhelper.lib + */ +NONSHARABLE_CLASS( MMPXCollectionUiHelper ) + { +public: + + /** Auto playlist type */ + enum TMPXAutoPlaylistType + { + EMPXRecentlyPlayedPlaylist, + EMPXMostPlayedPlaylist, + EMPXRecentlyAddedPlaylist + }; + + /** + * Add a media. Currently only adding a playlist is + * supported. + * @since S60 3.2.3 + * @param aMedia media to be added to the + * system. media type and category + * are mandatory attributes. Depending + * on the operation additional attributes + * may be required. + * @param aObserver observer to callback on completion + * of the request + */ + virtual void AddL( const CMPXMedia& aMedia, + MMPXCHelperObserver* aObserver ) = 0; + + /** + * Update a file with the particular media property. + * @since S60 3.2.3 + * @param aMedia media to update. + * @param aObserver observer to callback on completion + * of the request + */ + virtual void SetL( CMPXMedia*& aMedia, + MMPXCHelperObserver* aObserver ) = 0; + + /** + * Updates a list of properties. + * @since S60 3.2.3 + * @param aMediaArray list of media items. + * @param aPath collection path. + * @param aIndices an array of indicides to a collection path. + * @note this is not implemented because there is no use case + */ + virtual void SetL( TArray& aMediaArray, + CMPXCollectionPath& aPath, + RArray& aIndices) = 0; + + /** + * Rename a media. + * @since S60 3.2.3 + * @param aMedia media to be renamed. + * @param aObserver an observer for callback when + * operation is complete + */ + virtual void RenameL( const CMPXMedia& aMedia, + MMPXCHelperObserver* aObserver ) = 0; + + /** + * Delete a file based on the collection path. + * @since S60 3.2.3 + * @param aPath collection path with selections to delete. + * @param aObserver observer callback when operation is complete + */ + virtual void DeleteL( CMPXCollectionPath& aPath, + MMPXCHelperObserver* aObserver ) = 0; + + /** + * Move an item from one collection to another. + * @since S60 3.2.3 + * @param aMedia media for the item to delete. + * @param aNewCollection collection uid defined in collectionplugin.hrh. + * @param aObserver observer for the event + */ + virtual void MoveL( CMPXMedia*& aMedia, + TUid aNewCollection, + MMPXCHelperObserver* aObserver = NULL ) = 0; //lint !e1735 + /** + * Open the collection in embedded mode with a Media Object. + * @since S60 3.2.3 + * @param aUid Host Process UID to identify this embedded instance. + * @param aMedia Media Object to open. + * @param aObserver observer to the open operation. + * @param aPluginInfo additional argument to pass to the plugin resolver + */ + virtual void OpenL( const TUid& aHostId, CMPXMedia& aMedia, + MMPXCHelperEmbeddedOpenObserver* aObserver, + TInt aPluginInfo = 0 ) = 0; //lint !e1735 + + /** + * Open the collection in embedded mode with a File Handle. + * @since S60 3.2.3 + * @param aHostId Host Process UID to identify this embedded instance. + * @param aFile File handle that we have to process. + * @param aObserver observer to the open operation. + * @param aPluginInfo additional argument to pass to the plugin resolver + */ + virtual void OpenL( const TUid& aHostId, const TDesC& aFile, + MMPXCHelperEmbeddedOpenObserver* aObserver, + TInt aPluginInfo = 0 ) = 0; //lint !e1735 + + /** + * Queries about the playlist file extension of the currently selected playlist + * plugin. + * @since S60 3.2.3 + * @return File extension of the playlist type which includes the period + * ownership transferred + */ + virtual HBufC* PlaylistFileExtensionLC() = 0; + + /** + * Export the specified playlist to a file. + * @since S60 3.2.3 + * @param aPlaylistId id of the playlist to be exported. + * @param aDestinationDriveAndPath, specifies where the playlist file should + * be created. If the file already exists, it will be overwritten. + * @param aObserver observer for the callback. URI of the exported playlist + * will be returned as a HBufC* which client takes over the + * ownership. + * @leave KErrArgument leave if the playlist object does not exist + */ + virtual void ExportPlaylistL(TMPXItemId aPlaylistId, + const TDesC& aDestinationDriveAndPath, + MMPXCHelperObserver* aObserver) = 0; + + + /** + * Reorder a song in the playlist. + * @since S60 3.2.3 + * @param aPlaylistId id of the playlist which contains the song to be reordered. + * @param aSongId id of the song to be reordered. + * @param aOriginalOrdinal the original ordinal of the song within the playlist. + * Ordinal starts from 0. + * @param aNewOrdinal the new ordinal of the song within the playlist. Ordinal + * starts from 0. + * @param aObs observer for the callback. + * @leave KErrArgument leave if the playlist object does not exist + */ + virtual void ReorderPlaylistL(const TMPXItemId& aPlaylistId, + const TMPXItemId& aSongId, + TUint aOriginalOrdinal, + TUint aNewOrdinal, + MMPXCHelperObserver* aObserver) = 0; + + /** + * Gets the collection path to the main music menu. + * Call OpenL() with this path to open music menu. + * @since S60 3.2.3 + * @return CMPXCollectionPath* ownership transferred + */ + virtual CMPXCollectionPath* MusicMenuPathL() = 0; + + /** + * Gets the collection path to the podcast menu. + * Call OpenL() with this path to open podcast menu. + * @since S60 3.2.3 + * @return CMPXCollectionPath* ownership transferred + */ + virtual CMPXCollectionPath* PodCastMenuPathL() = 0; + + /** + * Gets the collection path to the main all songs view. + * Call OpenL() with this path to open music all songs view. + * @since S60 3.2.3 + * @return CMPXCollectionPath* ownership transferred + */ + virtual CMPXCollectionPath* MusicAllSongsPathL() = 0; + + /** + * Gets the collection path to the music playlist view. + * Call OpenL() with this path to open music playlist menu. + * @since S60 3.2.3 + * @return CMPXCollectionPath* ownership transferred + */ + virtual CMPXCollectionPath* MusicPlaylistPathL() = 0; + + /** + * Gets the collection path to the music playlist view + * Call OpenL() with this path to open music playlist menu + * @since S60 5.0 + * @param aPlaylistType type of auto playlist + * @return CMPXCollectionPath*, ownership transferred + */ + virtual CMPXCollectionPath* MusicPlaylistPathL( TMPXAutoPlaylistType aPlaylistType ) = 0; + + /** + * Creates a default playlist path to open. Hardcoded to Music Collection / All songs. + * @since S60 3.2.3 + * @return CollectionPath* ownership transferred + */ + virtual CMPXCollectionPath* CreateDefaultPlaylistPathLC() = 0; + + /** + * Cancels any async requests if any. + * @since S60 3.2.3 + * @note Only DeleteL() is supported at the moment + */ + virtual void Cancel() = 0; + + /** + * Free this object. + * @since S60 3.2.3 + */ + virtual void Close() = 0; + + /** + * Test if the specified title exists in the specified category. + * @since S60 3.2.3 + * @param aCategory specifies the category for testing. + * @param aTitle specifies the title for testing. + * @return ETrue if the specified title exists in the specified + * category; otherwise EFalse + */ + virtual TBool TitleExistsL( TMPXGeneralCategory aCategory, + const TDesC& aTitle, + TMPXGeneralType aType = EMPXItem ) = 0; + + /** + * Open the collection in embedded mode with a File Handle. + * @since S60 3.2.3 + * @param aFile File handle that we have to process. + * @param aObserver observer to the open operation + */ + virtual void OpenL( RFile& aFile, + MMPXCHelperEmbeddedOpenObserver* aObserver ) = 0; + + /** + * Returns the file name used for virtual playlist handling. + * @since S60 3.2.3 + * @return The file name to be used to externalize collection path for the playlist + * that needs to be handled. Ownership transfered. + */ + virtual HBufC* ExternalCollectionPathHandlingFileNameLC() = 0; + + /** + * Add a media. This is exactly the same as AddL except + * the songs in the media are added incrementally (in chunks). + * This function is not pure virtual in case some clients did + * not implement this (binary compatibility). + * @since S60 3.2.3 + * @param aMedia media to be added to the + * system. Media type and category + * are mandatory attributes. Depending + * on the operation additional attributes + * may be required. + * @param aObserver observer to callback on completion + * of the request. + * @param aSize number of songs to add in each chunk + */ + virtual void IncAddL( const CMPXMedia& /*aMedia*/, + MMPXCHelperObserver* /*aObserver*/, + const TInt /*aSize*/ ) {}; + }; + +#endif // MMPXCOLLECTIONUIHELPER_H