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