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:  Harvester utility library

    15 *

    16 */

    17 

    18 

    19 #ifndef MMPXHARVESTERUTILITY_H

    20 #define MMPXHARVESTERUTILITY_H

    21 

    22 #include <bamdesca.h>

    23 

    24 // FOWARD DECLARATION

    25 class CMPXMedia;

    26 class TMPXAttribute;

    27 class MMPXHarvesterUtilityObserver;

    28 

    29 /**

    30  *  Harvester Utility

    31  *

    32  *  Utility class to the harvester server

    33  *

    34  *  @lib mpxharvesterutility.lib

    35  */

    36 class MMPXHarvesterUtility

    37     {

    38 

    39 public: // New Functions

    40 

    41     /**

    42      *  Initiates a scan for new files on all drives.

    43      *  All files are added to the collection.

    44      *  Scan results are broadcasted through the collection framework.

    45      *

    46      *  @since S60 3.0

    47      */

    48     virtual void ScanL() = 0;

    49 

    50     /**

    51      *  Cancels a scan to refresh the db.

    52      *

    53      *  @since S60 3.0

    54      */

    55     virtual void CancelScanL() = 0;

    56 

    57     /**

    58      * Shutdown the server.

    59      *

    60      * @since S60 3.0

    61      * @note test function only!! shuts down the harvester server immediately

    62      */

    63     virtual void ShutdownL() = 0;

    64 

    65     /**

    66      * Add a single song.

    67      * This method is asynchronous and will call back via the observer interface.

    68      *

    69      * @since S60 3.0

    70      * @note S60 metadata utility is REALLY slow, so this has to be async

    71      * @param aFilePath path to the song to be added

    72      * @param aObs observer to the add file event

    73      */

    74     virtual void AddFileL( const TDesC& aFilePath, MMPXHarvesterUtilityObserver* aObs ) = 0;

    75 

    76     /**

    77      * Add a media property.

    78      *

    79      * @since S60 3.0

    80      * @param aMedia media to add

    81      * @return collection ID for this media

    82      */

    83     virtual TInt AddFileL( CMPXMedia*& aMedia ) = 0;

    84 

    85     /**

    86      * Remove a single song.

    87      *

    88      * @since S60 3.0

    89      * @param aFilePath path to the song to be removed

    90      * @return collection ID for the item

    91      */

    92     virtual TInt RemoveFileL( const TDesC& aFilePath ) = 0;

    93 

    94     /**

    95      * Remove a list of songs.

    96      *

    97      * @since S60 3.0

    98      * @param aArray list of songs to remove

    99      */

   100     virtual void RemoveFilesL( const MDesCArray& aFilesArray ) = 0;

   101 

   102     /**

   103      * Remove all songs from the harvester.

   104      *

   105      * @since S60 3.0

   106      */

   107     virtual void RemoveAllFilesL() = 0;

   108 

   109     /**

   110      * Recreate all databases (deletes old).

   111      * Used to handle db corruption by deleting and re-starting.

   112      *

   113      * @since S60 3.0

   114      */

   115     virtual void RecreateDatabasesL() = 0;

   116 

   117     /**

   118      * Remove a single song.

   119      * This Method is asynchronous and will call back to observer interface.

   120      *

   121      * @since S60 3.0

   122      * @param aFilePath path to the song to be removed

   123      * @param aObs observer to the delete event

   124      */

   125     virtual void DeleteFileL( const TDesC& aFilePath, MMPXHarvesterUtilityObserver* aObs ) = 0;

   126 

   127     /**

   128      * Remove a list of songs.

   129      * This method is asynchronous and will call back to observer interface.

   130      *

   131      * @since S60 3.0

   132      * @param aArray list of songs to remove

   133      * @param aObs observer to the delete event

   134      */

   135     virtual void DeleteFilesL( const MDesCArray& aArray, MMPXHarvesterUtilityObserver* aObs ) = 0;

   136 

   137     /**

   138      * Remove a list of songs.

   139      * This method is asynchronous and will call back to observer interface.

   140      *

   141      * @since S60 3.0

   142      * @param aArray list of songs to remove

   143      */

   144     virtual void DeleteFilesL( const MDesCArray& aArray ) = 0;

   145 

   146     /**

   147      * Update the collection id column in the harvester for a media.

   148      *

   149      * @since S60 3.0

   150      * @param aMedia media object containing the item to updates

   151      */

   152     virtual void UpdateFileL( CMPXMedia*& aProperty ) = 0;

   153 

   154     /**

   155      * Rename file for the given media.

   156      *

   157      * @since S60 3.0

   158      * @param aMedia media to be renamed

   159      * @return new URI of the renamed file

   160      */

   161     virtual HBufC* RenameFileLC( const CMPXMedia& aMedia ) = 0;

   162 

   163     /**

   164      * Rename file.

   165      *

   166      * @since S60 3.0

   167      * @param aOldUri existing URI

   168      * @param aNewUri new URI

   169      * @param aCollection collection Id of the collection the file belongs to

   170      */

   171     virtual void RenameFileL( const TDesC& aOldUri,

   172                               const TDesC& aNewUri,

   173                               TInt aCollection ) = 0;

   174 

   175     /**

   176      * Finds the collection ID based on a File name.

   177      *

   178      * @since S60 3.0

   179      * @param aFile file name to lookup

   180      * @return the collection ID

   181      */

   182     virtual TInt FindCollectionIdL( const TDesC& aFile ) = 0;

   183 

   184     /**

   185      * Export a Media property as a playlist (Asynchronous).

   186      * Note that this utility does not have a task queue,

   187      * The user can ONLY execute 1 async op at a time!

   188      * This method is asynchronous and will call back via the observer interface.

   189      *

   190      * @since S60 3.0

   191      * @param aProp CMPXMedia object to contain the "list" of items

   192      * @param aPath path and filename

   193      * @param aPlaylistType playlist type, default to M3U

   194      * @param aObs observer for async callback

   195      */

   196     virtual void ExportPlaylistL( const CMPXMedia& aProp,

   197                                   const TDesC& aPath,

   198                                   TInt aPlaylistType,

   199                                   MMPXHarvesterUtilityObserver* aObs ) = 0;

   200 

   201     /**

   202      * Import a playlist from a file (Asynchronous).

   203      * This method is asynchronous and will call back via the observer interface.

   204      *

   205      * @since S60 3.0

   206      */

   207     virtual void ImportPlaylistL( const TDesC& aFilename,

   208                                   MMPXHarvesterUtilityObserver* aObs ) = 0;

   209 

   210     /**

   211      * Imports a "file" in general (Async).

   212      * File is not added to any databases.

   213      *

   214      * @since S60 3.0

   215      * @param aFileName file to import

   216      * @param aObs observer for the import event

   217      */

   218     virtual void ImportFileL( const TDesC& aFilename,

   219                               MMPXHarvesterUtilityObserver* aObs ) = 0;

   220 

   221     /**

   222      * Query the required attributes for tracks for the specified playlist type.

   223      *

   224      * @since S60 3.0

   225      * @param aPlaylistType playlist type for this query

   226      * @param aRequiredAttributes out parameter, an array of required attributes

   227      *        of the specified playlist type

   228      */

   229     virtual void RequiredAttributesL( TInt aPlaylistType,

   230                               RArray<TMPXAttribute>& aRequiredAttributes ) = 0;

   231 

   232     /**

   233      * Query the optional attributes for tracks for the specified playlist type.

   234      *

   235      * @since S60 3.0

   236      * @param aPlaylistType playlist type for this query

   237      * @param aOptionalAttributes out parameter, an array of optional attributes

   238      *        of the specified playlist type

   239      */

   240     virtual void OptionalAttributesL( TInt aPlaylistType,

   241                               RArray<TMPXAttribute>& aOptionalAttributes ) = 0;

   242 

   243     /*

   244      * Query the file extension of playlist of the specified type.

   245      *

   246      * @since S60 3.0

   247      * @param aPlaylistType playlist type for this query

   248      * @return playlist file extension of the specified playlist type,

   249      *         this includes the period. ownership transferred

   250      */

   251     virtual HBufC* PlaylistFileExtensionLC( TInt aPlaylistType ) = 0;

   252 

   253     /**

   254      * Determines whether the given file is a playlist from available

   255      * playlist plugins currently in the system. The existence of the

   256      * file is not part of this validation process.

   257      *

   258      * An unsupported playlist file is tested as EFalse. But after the

   259      * appropriate playlist plugin has been installed, the client can

   260      * retest it and ETrue will be returned.

   261      *

   262      * @since S60 3.0

   263      * @param aUri URI of the media to be tested

   264      * @return ETrue if it's a playlist; otherwise EFalse.

   265      */

   266     virtual TBool IsPlaylistL( const TDesC& aUri ) = 0;

   267 

   268     /**

   269      * Sends a message to the harvester server to poll for any

   270      * system events. If there is a sytem event happening,

   271      * It will notify the rest of the MPX framework.

   272      * This is used for process start up to query for any on-going events.

   273      *

   274      * @since S60 3.0

   275      */

   276     virtual void CheckForSystemEventsL() = 0;

   277 

   278     /**

   279      * Closes the utility and deletes the object.

   280      *

   281      * @since S60 3.0

   282      */

   283     virtual void Close() = 0;

   284 

   285     /**

   286      * Get a media object for the file.

   287      * This method is asynchronous and will call back via the observer interface.

   288      *

   289      * @since S60 3.0

   290      * @note S60 metadata utility is REALLY slow, so this has to be async

   291      * @param aFilePath path to the song to be added

   292      * @param aObs observer to the add file event

   293      */

   294     virtual void GetMediaForFileL( const TDesC& aFilePath,

   295                                    MMPXHarvesterUtilityObserver* aObs ) = 0;

   296 

   297     /**

   298      * Get a collection ID for the file.

   299      *

   300      * @since S60 3.0

   301      * @param aMedia media to add

   302      * @return collection ID for this media

   303      */

   304     virtual TInt GetColUidForFileL( const TDesC& aFilePath ) = 0;

   305 

   306     /**

   307      * Remove a list of songs.

   308      * This method is asynchronous and will call back to observer interface.

   309      * Method is not pure virtual for backward compatibility.

   310      * 

   311      * @since S60 3.2.3

   312      * @param aArray list of songs to remove

   313      * @param aEndTransaction ETrue to end current database transaction 

   314      */

   315     virtual void DeleteFilesL( const MDesCArray& /*aArray*/, TBool /*aEndTransaction*/ ){};

   316 

   317     /**

   318      * Close the transaction.

   319      * This method is synchronous.

   320      * Method is not pure virtual for backward compatibility.

   321      * 

   322      * @since S60 3.2.3

   323      */

   324     virtual void CloseTransactionL(){};

   325 

   326     };

   327 

   328 /**

   329  *  Utility Factory class to create the utility

   330  *

   331  *  @lib harvester utility

   332  */

   333 class CMPXHarvesterFactory : CBase

   334     {

   335 public:

   336     /**

   337      * Factory function to create the utility

   338      *

   339      * @since S60 3.0

   340      */

   341     IMPORT_C static MMPXHarvesterUtility* NewL();

   342     };

   343 

   344 #endif // MMPXHARVESTERUTILITY_H