/*
* 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