// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// include\mmf\server\mmfdatasink.h

// 

//

#ifndef __MMF_SERVER_DATASINK_H__

#define __MMF_SERVER_DATASINK_H__

#include <e32base.h>

#include <mmf/server/mmfdatasourcesink.hrh>

#include <mmf/common/mmfutilities.h>

#include <ecom/ecom.h>

#include <mmf/common/mmfbase.h>

#include <mmf/common/mmfcontrollerframework.h>

//

// MDataSink mixim

//

class TFourCC;

class TMediaId;

class CMMFBuffer;

class MDataSource;

class MAsyncEventHandler;

/**

@publishedAll

@released

Abstract class representing a data sink.

*/

class MDataSink

	{

public:

	static inline MDataSink* NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData ) ;

	/**

	Destructor.

	*/

	virtual ~MDataSink() {REComSession::DestroyedImplementation(iDtor_ID_Key);};

	/**

	Returns the UID identifying the type of data sink.

	@return The UID identifying the type of data sink

	*/

	virtual TUid DataSinkType() const {return iDataSinkType;};

	/**

	Returns the data type as a fourCC code of the data sink.

	This is a pure virtual function that each derrived class must implement.

	@param  aMediaId

	        This identifies the type of media eg. audio or video and the stream ID.

	        This parameter is required in cases where the sink can accept data

	        of more than one media type and/or multiple streams of data.

	@return The fourCC code identifying the sink datatype for the specified aMediaId.

	*/

	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;

	inline virtual TInt SetSinkDataTypeCode(TFourCC aSinkFourCC, TMediaId aMediaId);

	/**

	Method called by a MDataSource to request the data sink to empty aBuffer of data.

	This is a pure virtual function that each derived class must implement.

	This method is used when a data sink is passively waiting for requests from a supplier ie.

	a data source to empty a buffer. The data sink must call the BufferEmptiedL member on aSupplier 

	when it has emptied	the buffer of it's data. The data sink can either make this callback 

	synchronously or asynchronously.

	@param  aBuffer

	        The full buffer that needs emptying of it's data.

	@param  aSupplier

	        The data source that supplied the data. The data sink needs this to make the 

	        BufferEmptiedL callback on aSupplier to indicate to the data source that the data sink

	        has finished with the buffer.

	@param  aMediaId

	        This identifies the type of media eg. audio or video and the stream ID.

	        This parameter is required in cases where the source can supply data

	        of more than one media type and/or multiple streams of data.

	*/

	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;

	/**

	Function called by a data source to pass back a filled buffer to the sink.

	This is a pure virtual function that each derived class must implement.

	This method is used as the callback when the data sink actively requests a supplier ie. a

	data source	to fill a buffer by calling the data sources FillBufferL. When the data sink gets

	this callback it knows that the buffer has been filled and is ready to be emptied.

	@param  aBuffer

	        The buffer that has been filled by a data source and is now available for processing.

	*/

	virtual void BufferFilledL(CMMFBuffer* aBuffer)=0;

	/**

	@deprecated

	Function to indicate whether the data sink can create a buffer.

	This is a pure virtual function that each derived class must implement.

	@return	A boolean indicating if the data sink can create a buffer. ETrue if it can otherwise 

	        EFalse.

	*/

	virtual TBool CanCreateSinkBuffer()=0;

	/**

	Returns a buffer created by the data sink.

	This is a pure virtual function that each derived class must implement.

	@param  aMediaId

	        This identifies the type of media eg. audio or video and the stream ID.

	        This parameter is required in cases where the source can supply data

	        of more than one media type and/or multiple streams of data.

	@param  aReference

	        This must be written to by the method to indicate whether the created buffer is

	        a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the sink

	        and should be used in preference to the source buffer provided the source buffer

	        is also not a reference buffer.

	@return	The created buffer.

	*/

	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;

	inline virtual TInt SinkThreadLogon(MAsyncEventHandler& aEventHandler);

	/**

	Function to 'logoff' the data sink from the same thread that sink consumes data in.

	This method may be required as the thread that the data sink is deleted in may not be

	the same thread that the data transfer took place in.  Therefore any thread specific

	releasing of resources needs to be performed in the SinkThreadLogoff rather than in the

	destructor.

	This is a virtual function that a derrived data sink can implement if any thread specific

	releasing of resources is required.

	*/

	virtual void SinkThreadLogoff() {};

	inline virtual void NegotiateL(MDataSource& aDataSource);

	/**

	Function to 'prime' the data sink.

	This is a virtual function that a derrived data sink can implement if

	any data sink specific 'priming' is required.

	*/

	virtual void SinkPrimeL() {};

	/**

	Function 'play' the data sink.

	This is a virtual function that a derrived data sink can implement if

	any data sink specific action is required prior to 'playing' ie. the start of data transfer.

	*/

	virtual void SinkPlayL() {};

	/**

	Function to 'pause' the data sink.

	This is a virtual function that a derrived data sink can implement if

	any data sink specific action is required to 'pause'.

	*/

	virtual void SinkPauseL() {};

	/**

	Function to 'stop' the data sink.

	This is a virtual function that a derrived data sink can implement if

	any data sink specific action is required to 'stop'

	*/

	virtual void SinkStopL() {};

	inline virtual void SetSinkPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);

	/**

	Calls a sink specific custom command.

	This is a virtual function that a derrived data sink can implement if

	it implements any custom commands.

	@param  aMessage

	        The message specifying the custom command.

	*/

	virtual void SinkCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};

protected:

	/**

	Performs any sink construction dependant on the sink construction

	initialisation data aInitData.

	This is a pure virtual function that a derrived data sink must implement

	@param  aInitData

	        The sink specific initialisation data required for sink construction.

	*/

	virtual void ConstructSinkL( const TDesC8& aInitData ) = 0;

	/**

	Protected constructor.

	@param  aType

	        The source type UID.

	*/

	MDataSink(TUid aType): iDataSinkType(aType) {}

private:

	TUid iDataSinkType;

	TUid iDtor_ID_Key;

	};

/**

Instantiates a new data sink.

@param  aImplementationUid

        The UID identifying the data sink to be instantiated.

@param  aInitData

        The sink specific initialisation data required for sink construction.

@return	A pointer to the instantiated data sink.

*/

inline MDataSink* MDataSink::NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData )

	{

	MDataSink* retPtr = REINTERPRET_CAST( MDataSink*, REComSession::CreateImplementationL( aImplementationUid,

																			_FOFF(MDataSink, iDtor_ID_Key) ) ) ;

	CleanupDeletePushL(retPtr);

	retPtr->ConstructSinkL( aInitData ) ;

	CleanupStack::Pop(retPtr);

	return retPtr ;

	}

/**

Sets the data type as a fourCC code for the data sink.

This is a virtual function that each derived class can implement if the data sink supports

the ability to have its data type set.

@param  aSinkFourCC

        This specifies the data type as a fourCC code to set the sink to.

@param  aMediaId

        This identifies the type of media eg. audio or video and the stream ID.

        This parameter is required in cases where the source can supply data

        of more than one media type and/or multiple streams of data.

@return	KErrNone if successful, KErrNotSupported if the sink does not support having

        it's data type set, otherwise a system wide error code.

*/

inline TInt MDataSink::SetSinkDataTypeCode(TFourCC /*aSinkFourCC*/, TMediaId /*aMediaId*/)

{

	return KErrNotSupported;

}

/**

Function to 'logon' the data sink to the same thread that sink will be consuming data in.

This method may be required as the thread that the data sink was created in is not always

the same thread that the data transfer will take place in.  Therefore any thread specific

initialisation needs to be performed in the SinkThreadLogon rather than in the creation

of the data sink.

This is a virtual function that a derrived data sink can implement if any thread specific

initialisation is required and/or the data sink can create any asynchronous events.

@param  aEventHandler

        This is an MAsyncEventHandler to handle asynchronous events that occur during the

        transfer of multimedia data. The event handler must be in the same thread as the data

        transfer thread - hence the reason it is passed in the SinkThreadLogon as opposed to

        say the constructor.

@return An error code indicating if the function call was successful. KErrNone on success, otherwise

        another of the system-wide error codes.

*/

inline TInt MDataSink::SinkThreadLogon(MAsyncEventHandler& /*aEventHandler*/)

{

	return KErrNone;

}

/**

@deprecated

Allows the data sink to negotiate with a data source.

This method is required in cases where the settings of data sink are dependant on those of a

data source. This is a virtual function that a derrived data sink can implement.

@param  aDataSource

        The data source whose settings can affect the data sink.

*/

inline void MDataSink::NegotiateL(MDataSource& /*aDataSource*/)

{

}

/**

Sets the sink priority settings.

This is a virtual function that a derrived data sink can implement if

a priority mechanism is required to arbitrate between multiple clients

trying to access the same resource.

@param  aPrioritySettings

        The sink priority settings.

@capability MultimediaDD

            A process requesting or using this method that has MultimediaDD capability will

			always have precedence over a process that does not have MultimediaDD.

*/

inline void MDataSink::SetSinkPrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)

{

}

/**

This function is used by TCleanupItem objects to perform

a SinkStopL() when leaving functions exist, ususally between SinkPrimeL-SinkStopL pairs.

@param  aSink

        The data sink to be stopped.

*/

inline static void DoDataSinkStop(TAny* aSink)

	{

	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);

	// we don't want this function to leave because no leaving functions are supposed

	// to be used as argument to the TCleanupItem objects. Hence we catch the error but

	// we do nothing with it.

	TRAP_IGNORE(sink->SinkStopL());

	}

/**

This method is used by TCleanupItem objects to perform a SinkThreadLogoff().

@param  aSink

        The data sink to be logged off.

*/

inline static void DoDataSinkThreadLogoff(TAny* aSink)

	{

	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);

	sink->SinkThreadLogoff();

	}

#endif