/*

* 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:  This class provides the functions to manipulate the music collection

*                database.

*

*/

#ifndef MPXDBHANDLER_H

#define MPXDBHANDLER_H

//  INCLUDES

#include <e32base.h>

#include <f32file.h>

#include <mpxattribute.h>

#include <mpxmessage2.h>

#include <mpxmediageneraldefs.h>

#include <mpxcollectionframeworkdefs.h>

#include <mpxmessagegeneraldefs.h>

#include <mpxcollectionmessagedefs.h>

#include "mpxcollectiondbstd.h"

#include "mpxcollectiondb.hrh"

#include "mpxdbactivetask.h"

#include "mpxdbmusic.h"     // for MMPXDbMusicObserver

#include "mpxdbartist.h"    // for MMPXDbArtistObserver

#include "mpxdbalbum.h"     // for MMPXDbAlbumObserver

#include "mpxdbplaylist.h"	// for MMPXDbPlaylistObserver

// FORWARD DECLARATIONS

class CMPXMedia;

class CMPXMediaArray;

class CMPXCollectionDbManager;

class CMPXDbPlaylist;

class CMPXDbCategory;

class CMPXDbAuxiliary;

class CMPXDbAutoPlaylist;

class CMPXDbArtist;

class CMPXDbAlbum;

class CMPXDbGenre;

class CMPXDbComposer;

// CLASS DECLARATION

/**

*  Music collection database handler

*

*  @lib MPXDbPlugin.lib

*/

class CMPXDbHandler :

    public CBase,

    public MMPXDbMusicObserver,

    public MMPXDbArtistObserver,

    public MMPXDbAlbumObserver,

	public MMPXDbPlaylistObserver

    {

    public:  // Constructors and destructor

        /**

        * Two-phased constructor.

        * @param aFs file server session

        * @return a new CMPXDbHandler instance

        */

        static CMPXDbHandler* NewL(RFs& aFs, CMPXResource& aResource);

        /**

        * Two-phased constructor.

        * @param aFs file server session

        * @return a new CMPXDbHandler instance

        */

        static CMPXDbHandler* NewLC(RFs& aFs, CMPXResource& aResource);

        /**

        * Destructor.

        */

        virtual ~CMPXDbHandler();

    public:

        /**

        * Add a song to the music collection database

        * @param aMedia media object which contains file path,

        *           artist, composer, name(title), track, etc...

        * @param aMessageArray change event message to notify client of the changes

        * @return TUint32 id of the item added

        */

        TUint32 AddSongL(const CMPXMedia& aMedia, CMPXMessageArray* aMessageArray=NULL);

        /**

        * Add a song to the music collection without a database transaction; it

        * is assumed the transaction is created at a higher leve

        * @param aMedia media object which contains file path,

        *           artist, composer, name(title), track, etc...

        * @param aMessageArray change event message to notify client of the changes

        * @return TUint32 id of the item added

        */

        TUint32 AddSongWithNoTransactionL(const CMPXMedia& aMedia, CMPXMessageArray* aMessageArray=NULL);

        /**

        * Add a playlist to the collection

        * @param aMedia playlist media object with title and URI of the playlist.

        * @return playlist Id of the playlist created

        */

        TUint32 AddPlaylistL(const CMPXMedia& aMedia);

        /**

        * Add songs to the specified playlist

        * @param aMedia playlist media object with playlist Id.

        * @return playlist Id of the playlist

        */

        TUint32 AddSongToPlaylistL(const CMPXMedia& aMedia);

        /**

        * Update song info for a song in the music collection database

        * @param aMedia songDetails object  which contains file path,

        *           artist, composer, name(title), track, etc...

        * @param aItemChangedMessages a list of change events as a result of the

        *           song update

        * @return ETrue if UI visible change else EFalse

        */

        CMPXDbActiveTask::TChangeVisibility UpdateSongL(const CMPXMedia& aMedia,

            CMPXMessageArray& aItemChangedMessages);

        /**

        * Update playlist info in the music collection database

        * @param aMedia playlist details object which contains file path,

        *           timestamps etc.

        * @param aMessageArray change event messages for the playlist update

        */

        void UpdatePlaylistL(const CMPXMedia& aMedia, CMPXMessageArray& aMessageArray);

        /**

        * Update the songs for a playlist in the music collection database

        * @param aMedia playlist details object which contains the playlist songs.

        * @param aMessage change event message for the playlist update

        */

        void UpdatePlaylistSongsL(const CMPXMedia& aMedia, CMPXMessage& aMessage);

        /**

        * Reorder the specified song in the specified playlist

        * @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 aMessage change event message for the playlist update

        */

        void ReorderPlaylistL(const TMPXItemId& aPlaylistId, const TMPXItemId& aSongId,

            TUint aOriginalOrdinal, TUint aNewOrdinal, CMPXMessage& aMessage);

        /**

        * Remove all songs within music collection database

        */

        void RemoveEntireCollectionL();

        /**

        * Remove a song from the music collection database

        * @param aSongId ID of the song to be removed

        * @param aUriArray a descriptor array to contain the URI of the deleted file

        * @param aItemChangedMessages a list of change events as a result of the song removal

        * @param aDeleteRecord indicates whether the client has explictly requested

        *                to delete the records from the database. If ETrue, records

        *                associated with the media will be deleted from the database;

        *                if EFalse, whether to mark the records as deleted or to delete

        *                the records will be based on other deciding factors.

        */

        void RemoveSongL(TUint32 aSongId, CDesCArray& aUriArray,

            CMPXMessageArray& aItemChangedMessages, TBool aDeleteRecord = EFalse);

        /**

        * Removes a category of songs from the music collection, and its

        * corresponding category in the lookup table

        * @param aCategory the category to remove

        * @param aCategoryId ID of the category to remove

        * @param aUriArray a descriptor array to contain the URI of the deleted songs

        * @param aItemChangedMessages a list of change events as a result of the song removal

        */

        void RemoveSongsMatchingCategoryL(TMPXGeneralCategory aCategory, TUint32 aCategoryId,

            CDesCArray& aUriArray, CMPXMessageArray& aItemChangedMessages);

        /**

        * Removes songs from the music collection belonging to the

        * specified artist and album as well as the actual category

        * in the lookup table

        * @param aArtistId id of the artist

        * @param aAlbumId id of the album

        * @param aUriArray a descriptor array to contain the URI of the deleted file(s)

        * @param aItemChangedMessages a list of change events as a result of the song removal

        */

        void RemoveSongsMatchingArtistAndAlbumL(TUint32 aArtistId, TUint32 aAlbumId,

            CDesCArray& aUriArray, CMPXMessageArray& aItemChangedMessages);

        /**

        * Remove all playlists from the collection

        */

        void RemoveAllPlaylistsL();

        /**

        * Remove a playlist This will remove all the songs from the playlist

        * @param aPlaylistId ID of the playlist to remove

        * @param aUriArray a descriptor array to contain the URI of the deleted file

        * @param aItemChangedMessages a list of change events as a result of the

        *        playlist removal

        */

        void RemovePlaylistL(TUint32 aPlaylistId, CDesCArray& aUriArray,

            CMPXMessageArray& aItemChangedMessages);

        /**

        * Remove a song from the specified playlist.

        * @param aPlaylistId ID of the playlist to remove the song from

        * @param aSongId Id of the song in the playlist to be removed

        * @param aOrdinal the ordinal of the song in the playlist. This uniquely

        *        identifies which song in the playlist to be removed; whereas song

        *        Id doesn't because duplicate tracks in the playlist are allowed.

        *        The position is relative to zero, i.e. zero implies that the song

        *        at the beginning of the playlist is to be removed.

        * @param aItemChangedMessages a list of change events as a result of the

        *        song removal

        */

        void RemoveSongFromPlaylistL(TUint32 aPlaylist, const TMPXItemId& aSongId,

            TInt aOrdinal, CMPXMessageArray& aItemChangedMessages);

        /**

        * Delete records in all databases which have been marked as deleted

        */

        void CleanupDeletedRecordsL();

        /**

        * Get all songs from the music collection databasee

        * @param aMediaArray Array to place all the songs' required info

        * @param aAttrs required attributes

        */

        void GetAllSongsL(CMPXMediaArray* aMediaArray,

            const TArray<TMPXAttribute>& aAttrs);

        /**

        * Get a limited number of songs from the music collection databasee

        * @param aMediaArray Array to place all the songs' required info

        * @param aAttrs required attributes

        * @param aLimit maximum number of songs to retrieve

        */

        void GetAllSongsLimitedL(const TArray<TMPXAttribute>& aAttrs,

                                 CMPXMediaArray& aMediaArray, TInt aLimit);

        /**

        * Get songs from the music collection database incrementally

        * @param aMediaArray Array to place all the songs' required info

        * @param aAttrs required attributes

        * @param aTitle title to use as a key

        * @param aNumOfSongs number of songs to read

        * @param aAsc ascending or descending data read

        */

        void GetSongsInBlockL(CMPXMediaArray* aMediaArray,

            const TArray<TMPXAttribute>& aAttrs,

            TPtrC aTitle,

            TUint aNumOfSongs,

            TBool aAsc);

        /**

        * Get songs from the music collection starting at a particular offset

        * ONLY use this as the first query to locate particular item. Should use

        * GetSongsInBlockL() to fetch in blocks with a particular index

        * @param aMediaArray Array to store the results

        * @param aAttrs attributes to fetch

        * @param aOffset offset to start reading

        * @param aCount number of items to get

        */

        void GetSongsAtOffsetL( CMPXMediaArray* aMediaArray,

                                const TArray<TMPXAttribute>& aAttrs,

                                TInt aOffset,

                                TInt aCount );

        /**

        * Get all the songs that match the given artist ID

        * @param aArtistId ID of the artist to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching songs' required

        *        attributes

        */

        void GetSongsMatchingArtistL(TUint aArtistId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get all the songs that match the given album ID

        * @param aAlbumId ID of the album to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching songs' required info

        */

        void GetSongsMatchingAlbumL(TUint aAlbumId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get all the songs that match the given artist and album ID

        * @param aArtistId ID of the artist to match

        * @param aAlbumId ID of the album to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching songs' required info

        */

        void GetSongsMatchingArtistAndAlbumL(TUint aArtistId, TUint aAlbumId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get all the songs that match the given genre ID

        * @param aGenreId ID of the genre to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching songs' required info

        */

        void GetSongsMatchingGenreL(TUint aGenreId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get all the songs that match the given composer ID

        * @param aComposerId ID of the composer to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching songs' required info

        */

        void GetSongsMatchingComposerL(TUint aComposerId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get all the songs that match the given playlist ID

        * @param aPlaylistId ID of the playlist to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the required song info

        */

        void GetSongsMatchingPlaylistL(TUint aPlaylistId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray* aMediaArray);

        /**

        * Get the song info that matches the given song ID from Songs table.

        * @param aSongId ID of the song

        * @param aAttrs required attributes

        * @param aMedia returns the song info

        */

        void GetSongL(TUint32 aSongId, const TArray<TMPXAttribute>& aAttrs,

            CMPXMedia& aMedia);

        /**

        * Appends the media object with the song information to the specified array.

        * @param aSongId ID of the song

        * @param aAttrs required attributes

        * @param aMediaArray on return the song info is appended to this array

        */

        void GetSongL(TUint32 aSongId, const TArray<TMPXAttribute>& aAttrs,

            CMPXMediaArray& aMediaArray);

        /**

        * Get the song info that matches the given song ID from Songs table.

        * The song info will first be populated from Playlist table and

        * if the Songs table exists in the drive where the song is located,

        * song info will be overwritten from Songs table. This enables the

        * support for displaying song title in a playlist when the drive

        * where the song is located is not present.

        * @aSongId ID of the song

        * @aPlaylistId ID of the playlist the song belongs to.

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the required song info

        * @leave KErrNotFound if the song could not be found in the

        *       PlaylistSongs table

        */

        void GetPlaylistSongL(TUint32 aSongId, TUint32 aPlaylistId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMedia& aMedia);

        /**

        * Appends the a media object with the song information to the specified array.

        * @param aSongId ID of the song

        * @param aPlaylistId ID of the playlist

        * @param aAttrs required attributes

        * @param aMediaArray on return the song info is appended to this array

        */

        void GetPlaylistSongL(TUint32 aSongId, TUint32 aPlaylistId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray& aMediaArray);

        /**

        * Get the song ID of the song that matches the given URI

        * @param aUri URI to match

        * @return song ID

        */

        TUint32 GetSongIdMatchingUriL(const TDesC& aUri);

        /**

        * Get all the artist names from the music collection database sorted by name.

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the artists' required info

        */

        void GetAllArtistsL(const TArray<TMPXAttribute>& aAttrs,

            CMPXMediaArray* aMediaArray);

        /**

        * Get all the album names from the music collection database sorted by name.

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the albums' required info

        */

        void GetAllAlbumsL(const TArray<TMPXAttribute>& aAttrs,

            CMPXMediaArray* aMediaArray);

        /**

        * Get all the albums that match the given artist ID sorted by name.

        * @param aArtistId ID of the artist to match

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the matching albums' required info

        */

        void GetAlbumsMatchingArtistL(TUint aArtistId,

            const TArray<TMPXAttribute>& aAttrs, CMPXMediaArray& aMediaArray);

        /**

        * Get all the genre names from the collection

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the genres' required info

        */

        void GetAllGenresL(const TArray<TMPXAttribute>& aAttrs,

            CMPXMediaArray* aMediaArray);

        /**

        * Get all the composer names from the collection

        * @param aAttrs required attributes

        * @param aMediaArray Array to place all the composers' required info

        */

        void GetAllComposersL(const TArray<TMPXAttribute>& aAttrs,

            CMPXMediaArray* aMediaArray);

        /**

        * Get the playlist ID of the playlist that matches the given URI

        * @param aUri URI to match

        * @return playlist ID to return

        */

        TUint32 GetPlaylistIdMatchingUriL(const TDesC& aUri);

        /**

        * Checks if the specified ID corresponds to an auto playlist.

        * @param aPlaylistId ID to be checked

        * @return ETrue if it corresponds to an auto playlist, EFalse otherwise

        */

        TBool IsAutoPlaylistL(TUint32 aPlaylistId);

        /**

        * Get all the playlist names from the collection

        * @param aMediaArray Array to place all the playlists' required info

        * @param aAttrs required attributes

        */

        void GetAllPlaylistsL(CMPXMediaArray* aMediaArray,

            const TArray<TMPXAttribute>& aAttrs);

        /**

        * Get all the system playlist names from the collection

        * @param aMediaArray Array to place all the system playlists' required info

        */

        void GetAllSystemPlaylistNamesL(CMPXMediaArray* aMediaArray);

        /**

        * Get title from the Id

        * @param Id to search for

        * @return name matching the ID

        */

        HBufC* GetNameMatchingIdL(const TUint32 aId) const;

        /**

        * Get URI from the Id

        * @param Id to search for

        * @return URI matching the ID

        * @leave KErrNotSupported if the ID refers to an invalid category

        */

        HBufC* GetUriMatchingIdL(const TUint32 aId) const;

        /**

        * Retrieve category record with information as specified in the given

        * attributes

        * @param aCategoryId Id of the record to be retrieved

        * @param aCategory category type

        * @param aAttrs information to return about the specified category

        * @param aMedia returns the category information

        */

        void GetCategoryL(const TUint32 aCategoryId, TMPXGeneralCategory aCategory,

                const TArray<TMPXAttribute>& aAttrs, CMPXMedia* aMedia);

        /**

        * Get the duration for all songs

        * @return duration

        */

        TInt GetAllSongsDurationL();

        /**

        * Get the duration for all songs for a specified artist

        * @param aArtistId identifies the artist

        * @return duration

        */

        TInt GetArtistDurationL(TInt aArtistId);

        /**

        * Get the duration for all songs in a specified album

        * @param aAlbumId identifies the album

        * @return duration

        */

        TInt GetAlbumDurationL(TInt aAlbumId);

        /**

        * Get the duration for all songs for a specified artist and album

        * @param aArtistId identifies the artist

        * @param aAlbumId identifies the album

        * @return duration

        */

        TInt GetArtistAlbumDurationL(TInt aArtistId, TInt aAlbumId);

        /**

        * Get the duration for all songs for a specified composer

        * @param aComposerId identifies the composer

        * @return duration

        */

        TInt GetComposerDurationL(TInt aComposerId);

        /**

        * Get the duration for all songs for a specified genre

        * @param aGenreId identifies the genre

        * @return duration

        */