--- /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 <mpxmediageneraldefs.h>
+#include <mpxcommonframeworkdefs.h>
+#include <mpxmediageneraldefs.h>
+
+// 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<CMPXMedia*>& aMediaArray,
+ CMPXCollectionPath& aPath,
+ RArray<TInt>& 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