/*
* Copyright (c) 2008 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:      class for containing and obtaining music track-specific
*                data from media server
*
*/






#ifndef C_UPNPTRACK_H
#define C_UPNPTRACK_H

// INCLUDES
#include <e32base.h>
#include "upnpitemresolverobserver.h"
#include "upnpresourceselector.h"

// FORWARD DECLARATIONS
class TMPXAttribute;
class TMPXAttributeData;
class MUPnPAVController;
class MUPnPAVBrowsingSession;
class MUPnPTrackObserver;
class MMPXPlaybackPluginObserver;
class CUpnpItem;
class MUPnPItemResolver;

// CONSTANTS
const TInt KMaxElementSize = 256;


/**
 *  A helper class for containing and obtaining music track-specific data
 *  from media server
 *
 *  @lib upnpmusicplugins.lib
 *  @since S60 v3.1
 */
class CUPnPTrack
    : public CBase
    , public MUPnPItemResolverObserver
    {

public: // datatypes 

    /**
     * Defines direction of playback
     *
     * EDirectionRemote  - Used in local to remote and remote to remote
     *                     playback cases 
     * EDirectionLocal   - Used only in remote to local case.
     * 
     */
    enum TPlaybackDirection
        {
        EDirectionRemote = 0,
        EDirectionLocal
        };
public:

    /**
     * static constructor
     *
     * @param aAvController AVController
     * @return a new CUPnPTrack instance
     * @since Series 60 3.1
     */
    static CUPnPTrack* NewL( MUPnPAVController& aAvController );

    /**
     * Destructor
     *
     * @since Series 60 3.1
     */
    virtual ~CUPnPTrack();

    /**
     * Parse and saves the song path from given descriptor
     *
     * @param aCodedTrackUri track URI that may be coded
     * @param atrackObserver observer to notify when resolve is complete
     * @param aPlaybackDirection direction of playback
     * @since Series 60 3.1
     */
    void ResolveURIL( const TDesC& aCodedTrackUri,
        MUPnPTrackObserver& aTrackObserver, 
        TPlaybackDirection aPlaybackDirection );

    /**
     * Returns the original URI given in initialisation
     *
     * @return TDesC URI
     * @since Series 60 3.1
     */
    const TDesC& URI() const;

    /**
     * Returns the true UPNP URI of a remote track
     *
     * @return TDesC8 URI
     * @since Series 60 3.1
     */
    const TDesC8& UpnpURI() const;

    /**
     * Returns the remote upnp item that represents the track
     *
     * @return CUpnpItem the item reference
     * @since Series 60 3.1
     */
    const CUpnpItem& UpnpItem() const;
    
    /**
     * Returns the file path of local item 
     *
     * @return TDesC file path
     * @since Series 60 3.1
     */
    const TDesC& FilePath() const;

    /**
     * Return location of track. ETrue = remote. EFalse = local
     *
     * @return TBool location of track
     * @since Series 60 3.1
     */
    TBool IsRemote() const;

    /**
     * Get metadata information for track from media server
     * 
     * @param aAttrs list of wanted media propeties
     * @param aObs the plugin observer that will receive the metadata
     * @since Series 60 3.1
     */
    void GetMetaDataL( const TArray<TMPXAttribute>& aAttrs,
        MMPXPlaybackPluginObserver& aObs );

    /**
     * Delivers media changed event to playback framework
     * @param aObs the plugin observer
     */
    void SendMediaChangedEventL(
        MMPXPlaybackPluginObserver& aObs );

    /**
     * current track duration
     * @return track duration in milliseconds
     */
    TInt TrackDuration();

    /**
     * overrides current track duration. Normally a track can provide
     * duration information for current remote track. However sometimes
     * the data is missing. In this case it can be set using this method.
     * @param aMilliseconds the duration in milliseconds
     */
    void SetTrackDuration( TInt aMilliseconds );

    /**
     * 
     */
    void Delete();
    
protected: // MUPnPItemResolverObserver

    /**
     * See MUPnPItemResolverObserver
     */
    void ResolveComplete( const MUPnPItemResolver& aResolver, TInt aError );

private:

    /**
     * Default constructor
     *
     * @param aAvController AVController
     * @since Series 60 3.1
     */
    CUPnPTrack( MUPnPAVController& aAvController );

    /**
     * 2nd phase constructor
     *
     * @since Series 60 3.1
     */
    void ConstructL();
    
    /**
     * Parse and save HttpURI, media server id and object id from 
     * given descriptor
     *
     * @since Series 60 3.1
     * @param aSong descriptor to be parsed
     */
    void ParsePiecesL( const TDesC& aSong );
    
    /**
     * See MUPnPAVBrowsingSessionObserver
     *
     * @since Series 60 3.1
     */
    void BrowseResponseL( const TDesC8& aBrowseResponse, TInt aError );

    /**
     * Starts a browsing session within the object
     */
    void StartBrowsingSessionL();

    /**
     * Stops a browsing session within the object
     */
    void StopBrowsingSession();

    /**
     * Delivers metadata to observer
     * @param aAttrs list of wanted media propeties
     * @param aObs the plugin observer that will receive the metadata
     * @param aError error code to be delivered to client
     */
    void DeliverMedataL( const TArray<TMPXAttribute>& aAttrs,
        MMPXPlaybackPluginObserver& aObs, TInt aError = KErrNone );

    /**
     * Fills item metadata into given MediaL object
     * @param aMedia the MPX media object to fill metadata into
     * @param aAttrs list of metadata elements to fill
     */
    void FillMediaFromItemL( CMPXMedia& aMedia,
        const TArray<TMPXAttribute>& aAttrs );

    /**
     * Tests if given attribute exists in the attribute array
     * returns true if it is found.
     * @param aAttrs the attribute array
     * @param aAttrData the attribute to look for
     * @return ETrue if it was found, EFalse otherwise
     */
    TBool Exists( const TArray<TMPXAttribute>& aAttrs,
        const TMPXAttributeData& aAttrData ) const;

    /**
     * A helper method that converts text from 8-bit to 16-bit.
     * Note that a member buffer is used that has static length.
     */
    const HBufC16* To16LC( const TDesC8& aText );

private: // data

    /**
     * Defines location of track
     *
     * @since Series 60 3.1
     */   
    enum TTrackLocation
        {
        ETrackLocationLocal = 0,
        ETrackLocationRemote
        };
    
    /**
     * Defines track state
     *
     * @since Series 60 3.2
     */  
    enum TTrackState
        {
        EStateIdle,
        EStateResolving,
        EStateSelfDestruct,
        EStateReady
        };
        

    /**
     * Location of track
     */
    TTrackLocation                      iTrackLocation;

    /**
     * URI for local track
     */
    HBufC*                              iOriginalURI;

    /**
     * Media server name 
     */
    HBufC8*                             iMediaServer;

    /**
     * Object id
     */
    HBufC8*                             iObjectId;

    /**
     * The AV Controller resource
     */
    MUPnPAVController&                  iAvController;

    /**
     * The rendering session
     */
    MUPnPAVBrowsingSession*             iBrowsingSession;

    /**
     * Track observer during resolving phase
     */
    MUPnPTrackObserver*                 iTrackObserver;

    /**
     * Observer for metadata queries
     * Stored in case metadata is not ready yet when queried
     */
    MMPXPlaybackPluginObserver*         iMetadataObserver;

    /**
     * Attributes in metadata query
     */
    RArray<TMPXAttribute>               iQueriedAttributes;

    /**
     * temp buffer used in 8->16 -bit conversion
     */
    TBuf16<KMaxElementSize>             iTempBuf;

    /**
     * track duration in milliseconds (from some other source)
     */
    TInt                                iTrackDuration;

    /**
     * Resolver for remote or local item (Owned).  
     */
    MUPnPItemResolver*                  iItemResolver;
    
    /**
     * Selectors for remote item.
     */
    TUPnPSelectDefaultResource          iDefaultSelector;
    
    /**
     * Selectors for local item.
     */
    TUPnPSelectFirstResource            iFirstSelector;
    
    /**
     * Tells is resolve item completed.
     */
    TBool                               iIsItemSolved;
    
    /**
     * Current track state
     */
    TTrackState                         iState;
    };


#endif // C_UPNPTRACK_H