/*

* 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:  Encapsulates a 'playlist' from a collection

*

*/

#ifndef CMPXCOLLECTIONPLAYLIST_H

#define CMPXCOLLECTIONPLAYLIST_H

#include <s32strm.h>

#include <mpxattribute.h>

#include <mpxcollectionobserver.h>

class CMPXCollectionPath;

class MMPXCollectionUtility;

class RReadStream;

class MMPXCollectionPlaylistObserver;

class CMPXCollectionOpenUtility;

/**

 *  Encapsulates a playlist

 *

 *  @lib mpxcollectionutility.lib

 */

class CMPXCollectionPlaylist : public CBase, public MMPXCollectionObserver

    {

public: // Data type    

    enum TRepeatMode

        {

        ERepeatOff, // No repeat

        ERepeatOne, // Play one track over and over again

        ERepeatAll  // Repeat the whole play list

        };

public:

   /**

    *  Two-phase constructor.

    *

    *  @since S60 3.2.3

    */

    IMPORT_C static CMPXCollectionPlaylist* NewL();

   /**

    *  Two-phase constructor.

    *

    *  @since S60 3.2.3

    *  @param aPlaylist reference to an existing playlist

    *  @param aPlObs playlist observer

    *  @return object created

    */

    IMPORT_C static CMPXCollectionPlaylist* NewL(

                                const CMPXCollectionPlaylist& aPlaylist,

                                MMPXCollectionPlaylistObserver* aPlObs = NULL);

    /**

     *  Two-phase constructor.

     *

     *  @since S60 3.2.3

     *  @param aPath reference to a collection path

     *  @param aPlObs playlist observer

     *  @return object created

     */

    IMPORT_C static CMPXCollectionPlaylist* NewL(

                                const CMPXCollectionPath& aPath,

                                MMPXCollectionPlaylistObserver* aPlObs = NULL);

    /**

     *  Two-phase constructor.

     *

     *  @since S60 3.2.3

     *  @param aStream reference to a collection path

     *  @param aPlObs playlist observer

     *  @return object created

     */

    IMPORT_C static CMPXCollectionPlaylist* NewL(

                                  RReadStream& aStream,

                                  MMPXCollectionPlaylistObserver* aPlObs = NULL);

    /**

     *  Destructor.

     *

     *  @since S60 3.2.3

     */

    IMPORT_C virtual ~CMPXCollectionPlaylist();

public: //Iterate through the playlist

    /**

     *  Copy content from other playlist.

     *

     *  @since S60 3.2.3

     *  @param aPlaylist reference to an existing playlist

     */

    IMPORT_C void CopyContentL(const CMPXCollectionPlaylist& aPlaylist);

    /**

     *  Next item.

     *

     *  @since S60 3.2.3

     *  @param aIgnoreRepeat ETrue to ignore repeat setting

     *  @return ETrue if exists

     */

    IMPORT_C TBool Next( TBool aIgnoreRepeat=EFalse );

    /**

     *  Gets the next index to play.  This method should not change

     *  any of the internal index values (const method).

     *

     *  @since S60 3.2.3

     *  @param aIgnoreRepeat ETrue to ignore repeat setting

     *  @param aPlaylistIndex Out Parameter - The next index. KErrNotFound if no valid index.

     *                                - This is the index in the playlist order.

     *  @return ETrue if exists

     */

    IMPORT_C TBool NextIndex( 

        TBool aIgnoreRepeat, 

        TInt& aPlaylistIndex ) const;

    /**

     *  Gets the path index of the item given it's position in the playlist.

     *

     *  @since S60 3.2.3

     *  @param aPlaylistIndex Index of item in the playlist

     *  @return The index of the item in the path

     */

    IMPORT_C TInt PathIndex( TInt aPlaylistIndex ) const;

    /**

     *  Previous item.

     *

     *  @since S60 3.2.3

     *  @param aIgnoreRepeat ETrue to ignore repeat setting

     *  @return ETrue if exists    

     */

    IMPORT_C TBool Previous( TBool aIgnoreRepeat=EFalse );

    /**

     *  Go to the first item.

     *

     *  @since S60 3.2.3

     */

    IMPORT_C void SetToFirst();

    /**

     *  Go to the last item.

     *

     *  @since S60 3.2.3

     */

    IMPORT_C void SetToLast();

    /**

     * Go to a particular item.

     *

     * @since S60 3.2.3

     * @param aIndex index to goto

     *               The index can be -1 for no selection and must be

     *               Smaller than the number of items in the playlist

     */

public: // State information   

    /**

     * Number of items.

     *

     * @since S60 3.2.3

     * @return the number of items

     */

    IMPORT_C TInt Count() const;

    /**

     * Depth of the playlist.

     *

     * @since S60 3.2.3

     * @return the depth

     */

    IMPORT_C TInt Levels() const;

    /**

     * Index to current item in the playlist.

     *

     * @since S60 3.2.3

     * @return the index

     */

    IMPORT_C TInt Index() const;

    /**

     * Remote playlist.

     *

     * @since S60 3.2.3

     * @return ETrue remote, EFalse local

     */

    IMPORT_C TBool Remote() const;

    /**

     * Repeat mode.

     *

     * @since S60 3.2.3

     * @return the repeat mode

     */

    IMPORT_C TRepeatMode RepeatMode() const;

    /**

     * Shuffle mode.

     *

     * @since S60 3.2.3

     * @return ETrue shuffle on, EFalse shuffle off

     */

    IMPORT_C TBool Shuffle() const; 

    /**

     * Get collection path.

     *

     * @since S60 3.2.3

     * @return collection path

     */

    IMPORT_C const CMPXCollectionPath& Path() const;

    /**

     * Get extended media of current item.

     *

     * @since S60 3.2.3

     * @param aAttrs attributes requested

     * @param aMediaObs properties observer

     */    

    IMPORT_C void MediaL(const TArray<TMPXAttribute>& aAttrs,

                         MMPXCollectionMediaObserver& aMediaObs);

    /**

     * Set repeat mode.

     *

     * @since S60 3.2.3

     * @param aMode the repeat mode

     */

    IMPORT_C void SetRepeatMode(TRepeatMode aMode); 

    /**

     * Set repeat enabled.

     *

     * @since S60 3.2.3

     * @param aEnable To enable repeat mode or not

     */

    IMPORT_C void SetRepeatEnabled( TBool aEnable ); 

    /**

     * Turn shuffle mode on/off.

     *

     * @since S60 3.2.3

     * @param aShuffle new shuffle mode

     * @param aCurrentToTop move current item to the top

     */

    IMPORT_C void SetShuffleL(TBool aShuffle, TBool aCurrentToTop);

    /**

     * Set shuffle enabled.

     *

     * @since S60 3.2.3

     * @param aEnable To enable shuffle mode or not

     */

    IMPORT_C void SetShuffleEnabledL( TBool aEnable );

    /**

     * Externalize an object of this class to stream.

     *

     * @since S60 3.2.3

     * @param aStream write stream

     */

    IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

    /**

     * Internalize an object of this class from stream.

     *

     * @since S60 3.2.3

     * @param aStream read stream

     */

    IMPORT_C void InternalizeL(RReadStream& aStream);

    /**

     * Set a new observer for current request.

     * Used when handling pre-initializing.

     *

     * @since S60 3.2.3

     * @param aMediaObs properties observer

     * @param aPlObs playlist observer

     * @param aCollectionObs collection observer

     */    

    IMPORT_C void SetObserver(MMPXCollectionMediaObserver& aMediaObs,

                              MMPXCollectionPlaylistObserver* aPlObs = NULL,

                              MMPXCollectionObserver* aCollectionObs = NULL);

    /**

     * Is this playlist launched from embedded mode.

     *

     * @since S60 3.2.3

     * @return ETrue if embedded mode

     */

    IMPORT_C TBool EmbeddedPlaylist() const;

    /**

     * Set or clear the embedded playlist flag.

     *

     * @since S60 3.2.3

     * @param aEmbedded is this playlist embedded?

     */

    IMPORT_C void SetEmbeddedPlaylist( TBool aEmbedded );

    /**

     *  Sets/updates the media for the item provided.

     *

     *  @since S60 3.2.3

     *  @param aMedia new value

     *  Callback via EMediaChanged message if currently opened

     */

    IMPORT_C void SetL( const CMPXMedia& aMedia );

    /**

     *  Stops any async operations that are currently under way.

     *

     *  @since S60 3.2.3

     */

    IMPORT_C void CancelRequest(); 

    /**

     *  Invalidate the playlist.

     *  

     */

    IMPORT_C void Invalidate();

    /**

     * AutoPlay

     *  

     * @since S60 TB9.2

     * @return the auto play value

     */

    IMPORT_C TBool AutoPlay() const;

    /**

     * Set auto play.

     * 

     * @since S60 TB9.2

     * @param aAutoPlay new value

     */

    IMPORT_C void SetAutoPlay(TBool aAutoPlay);

     /**

     * Single item playlist.

     *

     * @since S60 TB9.2

     * @return ETrue for single item, EFalse if not

     */

     IMPORT_C TBool IsSingleItemPlaylist();

    /**

     * Set single item playlist.

     *

     * @since S60 TB9.2

     */

     IMPORT_C void SetSingleItemPlaylist();

     /**

     * Pre-initialize next plugin.

     *

     * @since S60 TB9.2

     * @return ETrue for pre-init, EFalse if not

     */

     IMPORT_C TBool PreInitPlugin() const;

     /**

      * Set pre-initialize next plugin.

      *

      * @since S60 TB9.2

      * @param aPreInit new value

      */

      IMPORT_C void SetPreInitPlugin(TBool aPreInitPlugin);

private:  // From base class

    /**

     *  Handle media.

     *  From MMPXCollectionObserver / MMPXCollectionMediaObserver.

     *

     *  @since S60 3.2.3

     *  @param aMedia media properties

     *  @param aError error code

     */

    void HandleCollectionMediaL(const CMPXMedia& aMedia, TInt aError);

    /**

     *  Handle collection message.

     *  From MMPXCollectionObserver

     *

     *  @since S60 3.2.3

     *  @param aMessage collection message

     *  @param aErr system error code.

     */

    void HandleCollectionMessage(CMPXMessage* aMessage, TInt aErr);

    /**

     *  Handles the collection entries being opened. Typically called

     *  when client has Open()'d a folder.

     *  From MMPXCollectionObserver    

     *

     *  @since S60 3.2.3

     *  @param aEntries collection entries opened

     *  @param aIndex focused entry

     *  @param aComplete ETrue no more entries. EFalse more entries

     *                   expected

     *  @param aError error code   

     */

    void HandleOpenL(const CMPXMedia& aEntries,

                     TInt aIndex,TBool aComplete,TInt aError);

    /**

     *  Handles the item being opened. 

     *  Typically called when client has Open()'d an item. Client typically 

     *  responds by 'playing' the item via the playlist

     *  From MMPXCollectionObserver    

     *

     *  @since S60 3.2.3

     *  @param aPlaylist collection playlist

     *  @param aError error code   

     */                         

    void HandleOpenL(const CMPXCollectionPlaylist& aPlaylist,TInt aError);

private:

    /**

     *  Restore ordinal after changes.

     *  

     *  @since S60 3.2.3

     *  @param aEntries collection entries opened

     *  @param aIndex index of current item 

     *  @leave IfNull 

     */

    void RestoreOrdinalL(const CMPXMedia& aEntries, TInt aIndex);

    /**

     *  Handle collection message.

     *

     *  @since S60 3.2.3

     *  @param aMessage collection message

     *  @param aErr system error code.

     *  @leave IfNull

     */

    void DoHandleCollectionMessageL(CMPXMessage* aMessage, TInt aErr);

    /**

     * Handle a CMPXCollection message with a change event.

     *

     * @since S60 3.2.3

     * @param aMessage single collection message to handle

     * @return ETrue if a re-open is needed, EFalse otherwise

     */

    TBool DoHandleCollectionChangeMessageL(CMPXMessage& aMessage);

    /**

     * Handle starting of fetch for incremental algorithm.

     *

     * @since S60 3.2.3

     */

    void DoIncrementalOpenL();

    /**

     * Do Restore Ordinal for incremental opens.

     *

     * @since S60 3.2.3

     * @param aMedia media returned from collection

     * @param aComplete OpenL Completed or not

     */

    void DoHandleIncompleteOpenL( const CMPXMedia& aMedia, TBool aComplete);

private:

    /**

     *  C++ default constructor.

     *  content not constructed yet, it may be internalized from buffer

     *

     *  @since S60 3.2.3

     *  @param aPlObs playlist observer

     */

    CMPXCollectionPlaylist(MMPXCollectionPlaylistObserver* aPlObs);

    /**

     * 2nd phase constructor.

     *

     * @since S60 3.2.3

     * @param aPath collection path

     */

    void ConstructL(const CMPXCollectionPath& aPath);

    /**

     * 2nd phase constructor.

     *

     * @since S60 3.2.3

     * @param aPlaylist playlist

     */

    void ConstructL(const CMPXCollectionPlaylist& aPlaylist);

    /**

     * 2nd phase contructor.

     *

     * @since S60 3.2.3

     * @param aStream stream

     */

    void ConstructL(RReadStream& aStream);

    /**

     * 2nd phase contructor.

     *

     *  @since S60 3.2.3

     */

    void ConstructL();

private:

    TRepeatMode iRepeatMode;

    TBool iShuffle;