/*

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

*

*/

#ifndef MMPXHARVESTERUTILITY_H

#define MMPXHARVESTERUTILITY_H

#include <bamdesca.h>

// FOWARD DECLARATION

class CMPXMedia;

class TMPXAttribute;

class MMPXHarvesterUtilityObserver;

/**

 *  Harvester Utility

 *

 *  Utility class to the harvester server

 *

 *  @lib mpxharvesterutility.lib

 */

class MMPXHarvesterUtility

    {

public: // New Functions

    /**

     *  Initiates a scan for new files on all drives.

     *  All files are added to the collection.

     *  Scan results are broadcasted through the collection framework.

     *

     *  @since S60 3.0

     */

    virtual void ScanL() = 0;

    /**

     *  Cancels a scan to refresh the db.

     *

     *  @since S60 3.0

     */

    virtual void CancelScanL() = 0;

    /**

     * Shutdown the server.

     *

     * @since S60 3.0

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

     */

    virtual void ShutdownL() = 0;

    /**

     * Add a single song.

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

     *

     * @since S60 3.0

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

     * @param aFilePath path to the song to be added

     * @param aObs observer to the add file event

     */

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

    /**

     * Add a media property.

     *

     * @since S60 3.0

     * @param aMedia media to add

     * @return collection ID for this media

     */

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

    /**

     * Remove a single song.

     *

     * @since S60 3.0

     * @param aFilePath path to the song to be removed

     * @return collection ID for the item

     */

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

    /**

     * Remove a list of songs.

     *

     * @since S60 3.0

     * @param aArray list of songs to remove

     */

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

    /**

     * Remove all songs from the harvester.

     *

     * @since S60 3.0

     */

    virtual void RemoveAllFilesL() = 0;

    /**

     * Recreate all databases (deletes old).

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

     *

     * @since S60 3.0

     */

    virtual void RecreateDatabasesL() = 0;

    /**

     * Remove a single song.

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

     *

     * @since S60 3.0

     * @param aFilePath path to the song to be removed

     * @param aObs observer to the delete event

     */

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

    /**

     * Remove a list of songs.

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

     *

     * @since S60 3.0

     * @param aArray list of songs to remove

     * @param aObs observer to the delete event

     */

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

    /**

     * Remove a list of songs.

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

     *

     * @since S60 3.0

     * @param aArray list of songs to remove

     */

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

    /**

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

     *

     * @since S60 3.0

     * @param aMedia media object containing the item to updates

     */

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

    /**

     * Rename file for the given media.

     *

     * @since S60 3.0

     * @param aMedia media to be renamed

     * @return new URI of the renamed file

     */

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

    /**

     * Rename file.

     *

     * @since S60 3.0

     * @param aOldUri existing URI

     * @param aNewUri new URI

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

     */

    virtual void RenameFileL( const TDesC& aOldUri,

                              const TDesC& aNewUri,

                              TInt aCollection ) = 0;

    /**

     * Finds the collection ID based on a File name.

     *

     * @since S60 3.0

     * @param aFile file name to lookup

     * @return the collection ID

     */

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

    /**

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

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

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

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

     *

     * @since S60 3.0

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

     * @param aPath path and filename

     * @param aPlaylistType playlist type, default to M3U

     * @param aObs observer for async callback

     */

    virtual void ExportPlaylistL( const CMPXMedia& aProp,

                                  const TDesC& aPath,

                                  TInt aPlaylistType,

                                  MMPXHarvesterUtilityObserver* aObs ) = 0;

    /**

     * Import a playlist from a file (Asynchronous).

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

     *

     * @since S60 3.0

     */

    virtual void ImportPlaylistL( const TDesC& aFilename,

                                  MMPXHarvesterUtilityObserver* aObs ) = 0;

    /**

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

     * File is not added to any databases.

     *

     * @since S60 3.0

     * @param aFileName file to import

     * @param aObs observer for the import event

     */

    virtual void ImportFileL( const TDesC& aFilename,

                              MMPXHarvesterUtilityObserver* aObs ) = 0;

    /**

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

     *

     * @since S60 3.0

     * @param aPlaylistType playlist type for this query

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

     *        of the specified playlist type

     */

    virtual void RequiredAttributesL( TInt aPlaylistType,

                              RArray<TMPXAttribute>& aRequiredAttributes ) = 0;

    /**

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

     *

     * @since S60 3.0

     * @param aPlaylistType playlist type for this query

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

     *        of the specified playlist type

     */

    virtual void OptionalAttributesL( TInt aPlaylistType,

                              RArray<TMPXAttribute>& aOptionalAttributes ) = 0;

    /*

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

     *

     * @since S60 3.0

     * @param aPlaylistType playlist type for this query

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

     *         this includes the period. ownership transferred

     */

    virtual HBufC* PlaylistFileExtensionLC( TInt aPlaylistType ) = 0;

    /**

     * Determines whether the given file is a playlist from available

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

     * file is not part of this validation process.

     *

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

     * appropriate playlist plugin has been installed, the client can

     * retest it and ETrue will be returned.

     *

     * @since S60 3.0

     * @param aUri URI of the media to be tested

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

     */

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

    /**

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

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

     * It will notify the rest of the MPX framework.

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

     *

     * @since S60 3.0

     */

    virtual void CheckForSystemEventsL() = 0;

    /**

     * Closes the utility and deletes the object.

     *

     * @since S60 3.0

     */

    virtual void Close() = 0;

    /**

     * Get a media object for the file.

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

     *

     * @since S60 3.0

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

     * @param aFilePath path to the song to be added

     * @param aObs observer to the add file event

     */

    virtual void GetMediaForFileL( const TDesC& aFilePath,

                                   MMPXHarvesterUtilityObserver* aObs ) = 0;

    /**

     * Get a collection ID for the file.

     *

     * @since S60 3.0

     * @param aMedia media to add

     * @return collection ID for this media

     */

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

    /**

     * Remove a list of songs.

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

     * Method is not pure virtual for backward compatibility.

     * 

     * @since S60 3.2.3

     * @param aArray list of songs to remove

     * @param aEndTransaction ETrue to end current database transaction 

     */

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

    /**

     * Close the transaction.

     * This method is synchronous.

     * Method is not pure virtual for backward compatibility.

     * 

     * @since S60 3.2.3

     */

    virtual void CloseTransactionL(){};

    };

/**

 *  Utility Factory class to create the utility

 *

 *  @lib harvester utility

 */

class CMPXHarvesterFactory : CBase

    {

public:

    /**

     * Factory function to create the utility

     *

     * @since S60 3.0

     */

    IMPORT_C static MMPXHarvesterUtility* NewL();

    };

#endif // MMPXHARVESTERUTILITY_H