1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Collection Ui Helper interface class

    15 *

    16 */

    17 

    18 #ifndef MMPXCOLLECTIONUIHELPER_H

    19 #define MMPXCOLLECTIONUIHELPER_H

    20 

    21 #include <mpxmediageneraldefs.h>

    22 #include <mpxcommonframeworkdefs.h>

    23 #include <mpxmediageneraldefs.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class CMPXCollectionPath;

    27 class CMPXCollectionPlaylist;

    28 class CMPXMedia;

    29 class MMPXCHelperObserver;

    30 class MMPXCHelperEmbeddedOpenObserver;

    31 

    32 /**

    33  *  Abstract class for collection ui helper. Performs operation on playlist object. 

    34  *  Enables client to add, rename, etc a song to a playlist or add a particular property.

    35  *

    36  *  @lib mpxcollectionhelper.lib

    37  */

    38 NONSHARABLE_CLASS( MMPXCollectionUiHelper )

    39     {

    40 public:

    41 

    42     /**  Auto playlist type */

    43     enum TMPXAutoPlaylistType

    44         {

    45         EMPXRecentlyPlayedPlaylist,

    46 		EMPXMostPlayedPlaylist,

    47         EMPXRecentlyAddedPlaylist

    48         };

    49 

    50     /**

    51     * Add a media. Currently only adding a playlist is

    52     * supported.

    53 	* @since S60 3.2.3

    54     * @param aMedia media to be added to the

    55     *        system. media type and category

    56     *        are mandatory attributes. Depending

    57     *        on the operation additional attributes

    58     *        may be required.

    59     * @param aObserver observer to callback on completion 

    60     *        of the request

    61     */

    62     virtual void AddL( const CMPXMedia& aMedia,

    63                        MMPXCHelperObserver* aObserver ) = 0;

    64 

    65     /**

    66     * Update a file with the particular media property.

    67 	* @since S60 3.2.3

    68     * @param aMedia media to update.

    69     * @param aObserver observer to callback on completion 

    70     *        of the request

    71     */

    72     virtual void SetL( CMPXMedia*& aMedia,

    73                        MMPXCHelperObserver* aObserver ) = 0;

    74 

    75     /**

    76     * Updates a list of properties.

    77 	* @since S60 3.2.3

    78     * @param aMediaArray list of media items.

    79     * @param aPath collection path.

    80     * @param aIndices an array of indicides to a collection path.

    81     * @note this is not implemented because there is no use case

    82     */

    83     virtual void SetL( TArray<CMPXMedia*>& aMediaArray,

    84                        CMPXCollectionPath& aPath,

    85                        RArray<TInt>& aIndices) = 0;

    86 

    87     /**

    88     * Rename a media.

    89 	* @since S60 3.2.3

    90     * @param aMedia media to be renamed.

    91     * @param aObserver an observer for callback when

    92     *        operation is complete

    93     */

    94     virtual void RenameL( const CMPXMedia& aMedia,

    95                           MMPXCHelperObserver* aObserver ) = 0;

    96 

    97     /**

    98     * Delete a file based on the collection path.

    99 	* @since S60 3.2.3

   100     * @param aPath collection path with selections to delete.

   101     * @param aObserver observer callback when operation is complete

   102     */

   103     virtual void DeleteL( CMPXCollectionPath& aPath,

   104                           MMPXCHelperObserver* aObserver ) = 0;

   105 

   106     /**

   107     * Move an item from one collection to another.

   108 	* @since S60 3.2.3

   109     * @param aMedia media for the item to delete.

   110     * @param aNewCollection collection uid defined in collectionplugin.hrh.

   111     * @param aObserver observer for the event

   112     */

   113     virtual void MoveL( CMPXMedia*& aMedia,

   114                         TUid aNewCollection,

   115                         MMPXCHelperObserver* aObserver = NULL ) = 0;  //lint !e1735

   116     /**

   117     * Open the collection in embedded mode with a Media Object.

   118 	* @since S60 3.2.3

   119     * @param aUid Host Process UID to identify this embedded instance.

   120     * @param aMedia Media Object to open.

   121     * @param aObserver observer to the open operation.

   122     * @param aPluginInfo additional argument to pass to the plugin resolver

   123     */

   124     virtual void OpenL( const TUid& aHostId, CMPXMedia& aMedia,

   125                         MMPXCHelperEmbeddedOpenObserver* aObserver,

   126                         TInt aPluginInfo = 0 ) = 0; //lint !e1735

   127 

   128     /**

   129     * Open the collection in embedded mode with a File Handle.

   130 	* @since S60 3.2.3

   131     * @param aHostId Host Process UID to identify this embedded instance.

   132     * @param aFile File handle that we have to process.

   133     * @param aObserver observer to the open operation.

   134     * @param aPluginInfo additional argument to pass to the plugin resolver

   135     */

   136     virtual void OpenL( const TUid& aHostId, const TDesC& aFile,

   137                         MMPXCHelperEmbeddedOpenObserver* aObserver,

   138                         TInt aPluginInfo = 0 ) = 0; //lint !e1735

   139 

   140     /**

   141     * Queries about the playlist file extension of the currently selected playlist

   142     * plugin.

   143 	* @since S60 3.2.3

   144     * @return File extension of the playlist type which includes the period

   145     *         ownership transferred

   146     */

   147     virtual HBufC* PlaylistFileExtensionLC() = 0;

   148 

   149     /**

   150     * Export the specified playlist to a file.

   151 	* @since S60 3.2.3

   152     * @param aPlaylistId id of the playlist to be exported.

   153     * @param aDestinationDriveAndPath, specifies where the playlist file should

   154     *        be created. If the file already exists, it will be overwritten.    

   155     * @param aObserver observer for the callback. URI of the exported playlist

   156     *        will be returned as a HBufC* which client takes over the

   157     *        ownership.

   158     * @leave KErrArgument leave if the playlist object does not exist

   159     */

   160     virtual void ExportPlaylistL(TMPXItemId aPlaylistId,

   161                                  const TDesC& aDestinationDriveAndPath,

   162                                  MMPXCHelperObserver* aObserver) = 0;

   163 

   164 

   165     /**

   166     * Reorder a song in the playlist.

   167 	* @since S60 3.2.3

   168     * @param aPlaylistId id of the playlist which contains the song to be reordered.

   169     * @param aSongId id of the song to be reordered.

   170     * @param aOriginalOrdinal the original ordinal of the song within the playlist.

   171     *        Ordinal starts from 0.

   172     * @param aNewOrdinal the new ordinal of the song within the playlist. Ordinal

   173     *        starts from 0.

   174     * @param aObs observer for the callback.

   175     * @leave KErrArgument leave if the playlist object does not exist

   176     */

   177     virtual void ReorderPlaylistL(const TMPXItemId& aPlaylistId,

   178                                   const TMPXItemId& aSongId,

   179                                   TUint aOriginalOrdinal,

   180                                   TUint aNewOrdinal,

   181                                   MMPXCHelperObserver* aObserver) = 0;

   182 

   183     /**

   184     * Gets the collection path to the main music menu.

   185     * Call OpenL() with this path to open music menu.

   186 	* @since S60 3.2.3

   187     * @return CMPXCollectionPath* ownership transferred

   188     */

   189     virtual CMPXCollectionPath* MusicMenuPathL() = 0;

   190 

   191     /**

   192     * Gets the collection path to the podcast menu.

   193     * Call OpenL() with this path to open podcast menu.

   194 	* @since S60 3.2.3

   195     * @return CMPXCollectionPath* ownership transferred

   196     */

   197     virtual CMPXCollectionPath* PodCastMenuPathL() = 0;

   198 

   199     /**

   200     * Gets the collection path to the main all songs view.

   201     * Call OpenL() with this path to open music all songs view.

   202 	* @since S60 3.2.3

   203     * @return CMPXCollectionPath* ownership transferred

   204     */

   205     virtual CMPXCollectionPath* MusicAllSongsPathL() = 0;

   206 

   207     /**

   208     * Gets the collection path to the music playlist view.

   209     * Call OpenL() with this path to open music playlist menu.

   210 	* @since S60 3.2.3

   211     * @return CMPXCollectionPath* ownership transferred

   212     */

   213     virtual CMPXCollectionPath* MusicPlaylistPathL() = 0;

   214 

   215     /**

   216     * Gets the collection path to the music playlist view

   217     * Call OpenL() with this path to open music playlist menu

   218     * @since S60 5.0

   219     * @param aPlaylistType type of auto playlist

   220     * @return CMPXCollectionPath*, ownership transferred

   221     */

   222     virtual CMPXCollectionPath* MusicPlaylistPathL( TMPXAutoPlaylistType aPlaylistType ) = 0;

   223 

   224     /**

   225     * Creates a default playlist path to open. Hardcoded to Music Collection / All songs.

   226 	* @since S60 3.2.3

   227     * @return CollectionPath* ownership transferred

   228     */

   229     virtual CMPXCollectionPath* CreateDefaultPlaylistPathLC() = 0;

   230 

   231     /**

   232     * Cancels any async requests if any.

   233 	* @since S60 3.2.3

   234     * @note Only DeleteL() is supported at the moment

   235     */

   236     virtual void Cancel() = 0;

   237 

   238     /**

   239     * Free this object.

   240 	* @since S60 3.2.3

   241     */

   242     virtual void Close() = 0;

   243 

   244     /**

   245     * Test if the specified title exists in the specified category.

   246 	* @since S60 3.2.3

   247     * @param aCategory specifies the category for testing.

   248     * @param aTitle specifies the title for testing.

   249     * @return ETrue if the specified title exists in the specified

   250     *         category; otherwise EFalse

   251     */

   252     virtual TBool TitleExistsL( TMPXGeneralCategory aCategory,

   253                                 const TDesC& aTitle,			

   254                               	TMPXGeneralType aType = EMPXItem ) = 0;

   255 

   256     /**

   257     * Open the collection in embedded mode with a File Handle.

   258 	* @since S60 3.2.3

   259     * @param aFile File handle that we have to process.

   260     * @param aObserver observer to the open operation

   261     */

   262     virtual void OpenL( RFile& aFile,

   263                         MMPXCHelperEmbeddedOpenObserver* aObserver ) = 0;

   264 

   265     /**

   266     * Returns the file name used for virtual playlist handling.

   267 	* @since S60 3.2.3

   268     * @return The file name to be used to externalize collection path for the playlist

   269     *         that needs to be handled. Ownership transfered.

   270     */

   271     virtual HBufC* ExternalCollectionPathHandlingFileNameLC() = 0;

   272     

   273     /**

   274     * Add a media. This is exactly the same as AddL except

   275     * the songs in the media are added incrementally (in chunks).

   276     * This function is not pure virtual in case some clients did 

   277     * not implement this (binary compatibility).

   278     * @since S60 3.2.3

   279     * @param aMedia media to be added to the

   280     *        system. Media type and category

   281     *        are mandatory attributes. Depending

   282     *        on the operation additional attributes

   283     *        may be required.

   284     * @param aObserver observer to callback on completion 

   285     *        of the request.

   286     * @param aSize number of songs to add in each chunk

   287     */

   288     virtual void IncAddL( const CMPXMedia& /*aMedia*/,

   289                           MMPXCHelperObserver* /*aObserver*/,

   290                           const TInt /*aSize*/ ) {};

   291     };

   292 

   293 #endif // MMPXCOLLECTIONUIHELPER_H