/*

* Copyright (c) 2005 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:    

*

*/

#ifndef CMCEMEDIASTREAM_H

#define CMCEMEDIASTREAM_H

// INCLUDES

#include <e32std.h>  	

#include <e32base.h>

#include <mcedefs.h>

// DATA TYPES

typedef TUint TMceMediaType;

// FORWARD DECLARATIONS

class CMceComMediaStream;

class TMceFactory;

class TMceMediaStreamFactory;

class RWriteStream;

class RReadStream;

class CDesC8Array;

class MDesC8Array;

class CMceSession;

class TMceIds;

class TMceEvent;

class TMceMediaId;

class CMceManager;

class CMceSession;

class CMceMediaSource;

class CMceMediaSink;

class MMceComSerializationContext;

class CMceFileSource;

class CMceCodec;

// CLASS DECLARATION

/**

* Base class for MCE media streams.

*

* MCE Media stream represents stream of data negotiated between two terminals.

* Streams may transfer any data.

*

* Enabling or disabling of a stream is not a local operation, but it requires

* always signalling. Thus, these operation require always to be completed by

* calling CMceSession::UpdateL() function.

*

*  @lib mceclient.lib

*/

class CMceMediaStream : public CBase

	{

	public: // Stream states

	    enum TState

	        {

	        EUninitialized,       // Stream is created

	        EInitialized,         // Stream is initialized

	        EBuffering,           // Stream is buffering

	        EIdle,                // Stream is not receiving RTP

	        EStreaming,           // Stream is streaming

	        EDisabled,            // Stream is explicitly disabled

	        ENoResources,         // Stream has no needed resources to stream

	        ETranscodingRequired, // Stream requires non-realtime transcoding

	        ETranscoding          // Stream is transcoding in non-realtime

	        };

	public: // Destructor

	    /**

	    * Destructor.

	    */

		IMPORT_C ~CMceMediaStream();

	public: // Functions

	    /**

	    * Gets the state of the stream.

	    * @return the current state of the stream

	    */

	    IMPORT_C CMceMediaStream::TState State() const;

	    /**

	    * Returns the type of the stream.

	    * @return The type of the stream.

	    */

		IMPORT_C TMceMediaType Type() const;

	    /**

		* Configures media stream by updating SDP media lines. 

		* In order to get complete update, whole session must be 

		* updated causing sending of re-invite.

	    * @param aMediaSDPLines, application specific SDP media lines for

		*		 the stream. Ownership is transferred.

	    */

		IMPORT_C void SetMediaAttributeLinesL( CDesC8Array* aMediaSDPLines );

		/**

		* Gets attribute lines of the media.

		* @return array of media attribute lines, owneship is transferred.

		*/

		IMPORT_C MDesC8Array* MediaAttributeLinesL();

		/** 

	    * Sets local media port

	    * @param aLocalMediaPort, local port for the media

	    */

	    IMPORT_C void SetLocalMediaPortL(TUint aLocalMediaPort); 

	    /**

	    * Gets the local media port.

	    * @return Local port used for media.

	    */

	    IMPORT_C TUint LocalMediaPort() const;

	    /**

	    * Gets the session this stream belongs to, if exists. The

	    * ownership is not transfered.

	    * @return Session object

	    */

		IMPORT_C CMceSession* Session() const;

	public: // Local stream control

	    /**

	    * Enables streaming explicitly.

	    */

	    virtual void EnableL(); 

	    /**

	    * Disables streaming explicitly.

	    */

		virtual void DisableL(); 

		/**

	    * Returns the state of the stream.

	    * @return ETrue if enabled, EFalse if disabled.

	    */

    	IMPORT_C TBool IsEnabled() const;

		/**

	    * Sets state of stream

	    * @param aState the state

	    */

	    TBool SetState( TState aState );

    public: // Source and sink functions

        /**

        * Adds source to the stream. CMceMediaStream can only

        * have one source at a time. Ownership of passed source is transferred.

        * However, the same source can be also passed to other streams resulting

        * that streams share ownership of the source. Passing NULL source will

        * remove source from stream.

        * In some cases the source might contain a codec. The codec is derived

        * to the stream when such source is added to the stream. 

        * Derived codec will get automatically highest preference.

        * @param aSource source to be added to the stream; ownership is 

        *        transferred

        */

        IMPORT_C void SetSourceL( CMceMediaSource* aSource );

        /**

        * Adds sink to the stream. CMceMediaStream can have

        * many sinks at a time. Ownership of passed sink is transferred.

        * However, the same sink can be also passed to other streams resulting

        * that streams share ownership of the sink.

        * @param aSink sink to be added to the stream; ownership is transferred

        */

        IMPORT_C void AddSinkL( CMceMediaSink* aSink );

        /**

        * Gets source of the stream. Returns NULL if source is not set.

        * @return source of the stream; ownership is not transferred

        */

        IMPORT_C CMceMediaSource* Source() const;

        /**

        * Gets array of sinks of the stream.

        * @return array of sinks

        */

        IMPORT_C const RPointerArray<CMceMediaSink>& Sinks() const;

        /**

        * Removes sink from the stream.

        * @post aSink cannot be used anymore and contents of 

        *       previously returned sink array (CMceMediaStream::Sinks())

        *       are not anymore valid

        * @param aSink sink to be removed from the stream

        */

        IMPORT_C void RemoveSinkL( CMceMediaSink& aSink );

    public: // Binding opposite way stream

        /**

        * Binds opposite direction stream to this stream.

        * @param aStream another stream to be bind to the stream; 

        *        ownership is transferred

        */

        IMPORT_C void BindL( CMceMediaStream* aStream );

        /**

        * Gets opposite direction stream of this stream.

        * @return opposite direction stream

        */

        IMPORT_C CMceMediaStream& BoundStreamL() const;

        /**

        * Checks if opposite direction stream is set.

        * @return ETrue if opposite direction stream is set; 

        *         otherwise EFalse

        */

        IMPORT_C TBool BoundStream() const;

    public: // from MMceComSerializableMedia

        /**

        * Returns serialization id

        * @return serialization id

        */

        TUint64 SerializationId() const;

        /**

        * Internalizes flat data

        * @param aReadStream read stream

        */

        void InternalizeFlatL( RReadStream& aReadStream );

        /**

        * Externalizes flat data

        * @param aWriteStream write stream

        */

        void ExternalizeFlatL( RWriteStream& aWriteStream );

        /**

        * Internalizes

        * @param aSerCtx context for serialization

        */

        virtual void InternalizeL( MMceComSerializationContext& aSerCtx );

        /**

        * Externalizes

        * @param aSerCtx context for serialization

        */

        virtual void ExternalizeL( MMceComSerializationContext& aSerCtx );

public:// internal serialization

        /**

        * Adds source, during serialization, to the stream.

        * @param aSerCtx serialization context

        */

        void SetSourceL( MMceComSerializationContext& aSerCtx );

        /**

        * Adds sink, during serialization, to the stream.

        * @param aSerCtx serialization context

        */

        void AddSinkL( MMceComSerializationContext& aSerCtx );

	    /**

	    * Factory

	    * @return factory

	    */

	    TMceFactory BaseFactory() const;

	    /**

	    * Factory

	    * @return factory

	    */

	    static TMceMediaStreamFactory Factory();

	public: //internal

	    /**

	    * Checks if this is binder (biding owner)

	    * @return ETrue if this is binder (biding owner)

	    */

		TBool Binder() const;

	    /**

	    * ID 

	    * @return ID

	    */

		TMceMediaId Id() const;

	    /**

	    * Initializes 

	    * @param aParent the parent

	    * @param aDiscardUnusedCodecs

	    */

	    virtual void InitializeL( CMceSession& aParent, TBool aDiscardUnusedCodecs );

	    /**

	    * Initializes 

	    * @param aManager the manager. Ownership is NOT transferred

	    * @param aSession the Session.

	    */

	    virtual void InitializeL( CMceManager* aManager, CMceSession& aSession );

	    /**

	    * Called when stream is added to session

	    */

	    virtual void AddedL();

	    /**

	    * Called file source wants to synchronized with stream

	    * @param aFile the file source

	    */

        virtual void SynchronizeWithFileL( CMceFileSource& aFile ) = 0;

        /**

        * Searches for codec matching with input codec instance or sdp name

        * @param aCodec the search term

        * @return matching codec or NULL if not found

        */

        virtual CMceCodec* FindCodec( CMceCodec& aCodec ) = 0;

      /**

	    * Arranges codec priority order based on codecs preference values.

	    * @param aDiscardUnusedCodecs ETrue if all disabled codecs should

	    *        be removed from the stream

	    */

        virtual void ReorderCodecsByPreferenceL( TBool aDiscardUnusedCodecs ) = 0;

        /**

        * Return codecs of stream.

        * @return list of codecs in the stream.

        */

        virtual const RPointerArray<CMceCodec>& BaseCodecs() = 0;

        /**

        * Returns pointer to the bound stream and NULL if no bound

        * stream exists.

        * @return bound stream

        */

	    CMceMediaStream* Bound() const;

	    /**

	    * Gets the flat data

	    * @return flat data

	    */

	    CMceComMediaStream* FlatData();

	public://event handling & update

	    /**

	    * Traversal event handler

	    * @param aEvent the event

	    * @return status, if event was consumed or not or object needs update

	    */

	    virtual TInt EventReceivedL( TMceEvent& aEvent );

	    /**

	    * Called after update

	    */

	    virtual void Updated();

	    /**

	    * Handles possible media errors.

	    * @return ETrue, if media error occured and was handled.

	    */

	    TBool HandleMediaError( TState aState, TBool aIsEnabled, TInt aError );

	protected:

	    /**

	    * C++ default constructor.

	    */

		CMceMediaStream();

	    /**

	    * Second-phase constructor

	    * @param aFlatData flat data container

	    */

		void ConstructL( CMceComMediaStream* aFlatData );

		/**

		* Search for codec inside given codec array

		* @param aCodecs array of codecs

		* @param aCodec search term

		* @return matching codec or NULL if not found

		*/

		CMceCodec* FindCodec( const RPointerArray<CMceCodec>& aCodecs, 

                              CMceCodec& aCodec );

	private:

	    /**

	    * Handles event

	    * @param aEvent the event

	    * @return status, if event was consumed or not or object needs update

	    */

	    TInt HandleEvent( TMceEvent& aEvent );

	    /**

	    * one-way bind

	    * @param aStream another stream to be bind to the stream.

	    */

	    void DoBindL( CMceMediaStream* aStream );

	    /**

	    * Deletes sink

	    * @param aIndex index of sink in the array

	    */

        void DeleteSink( TInt aIndex );

	    /**

	    * Deletes source

	    */

    	void DeleteSource();

	protected: // NOT owned data

	    /**

	     * session

	     */

		CMceSession* iSession;

	protected: // owned data

	    /**

	     * flat data container

	     */

		CMceComMediaStream* iFlatData;

	    /**

	     * linked stream. Owned if iLinkOwner is ETrue

	     */

	    CMceMediaStream* iLinkedStream;

	    /**

	     * source

	     */

		CMceMediaSource* iSource;

	    /**

	     * sinks

	     */

		RPointerArray<CMceMediaSink> iSinks;

    private: // Reserved for future use

        TAny* iReserved;       

		//for testing

	    MCE_UNIT_TEST_DEFS	

	};

#endif