sl@0: // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // include\mmf\server\mmfdatasink.h
sl@0: // 
sl@0: //
sl@0: 
sl@0: #ifndef __MMF_SERVER_DATASINK_H__
sl@0: #define __MMF_SERVER_DATASINK_H__
sl@0: 
sl@0: #include <e32base.h>
sl@0: #include <mmf/server/mmfdatasourcesink.hrh>
sl@0: #include <mmf/common/mmfutilities.h>
sl@0: #include <ecom/ecom.h>
sl@0: #include <mmf/common/mmfbase.h>
sl@0: #include <mmf/common/mmfcontrollerframework.h>
sl@0: 
sl@0: //
sl@0: // MDataSink mixim
sl@0: //
sl@0: 
sl@0: class TFourCC;
sl@0: class TMediaId;
sl@0: class CMMFBuffer;
sl@0: class MDataSource;
sl@0: class MAsyncEventHandler;
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: Abstract class representing a data sink.
sl@0: */
sl@0: class MDataSink
sl@0: 	{
sl@0: public:
sl@0: 
sl@0: 	static inline MDataSink* NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData ) ;
sl@0: 
sl@0: 	/**
sl@0: 	Destructor.
sl@0: 	*/
sl@0: 	virtual ~MDataSink() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
sl@0: 
sl@0: 	/**
sl@0: 	Returns the UID identifying the type of data sink.
sl@0: 
sl@0: 	@return The UID identifying the type of data sink
sl@0: 	*/
sl@0: 	virtual TUid DataSinkType() const {return iDataSinkType;};
sl@0: 
sl@0: 	/**
sl@0: 	Returns the data type as a fourCC code of the data sink.
sl@0: 
sl@0: 	This is a pure virtual function that each derrived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        This identifies the type of media eg. audio or video and the stream ID.
sl@0: 	        This parameter is required in cases where the sink can accept data
sl@0: 	        of more than one media type and/or multiple streams of data.
sl@0: 
sl@0: 	@return The fourCC code identifying the sink datatype for the specified aMediaId.
sl@0: 	*/
sl@0: 	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
sl@0: 
sl@0: 	inline virtual TInt SetSinkDataTypeCode(TFourCC aSinkFourCC, TMediaId aMediaId);
sl@0: 
sl@0: 	/**
sl@0: 	Method called by a MDataSource to request the data sink to empty aBuffer of data.
sl@0: 
sl@0: 	This is a pure virtual function that each derived class must implement.
sl@0: 	This method is used when a data sink is passively waiting for requests from a supplier ie.
sl@0: 	a data source to empty a buffer. The data sink must call the BufferEmptiedL member on aSupplier 
sl@0: 	when it has emptied	the buffer of it's data. The data sink can either make this callback 
sl@0: 	synchronously or asynchronously.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The full buffer that needs emptying of it's data.
sl@0: 	@param  aSupplier
sl@0: 	        The data source that supplied the data. The data sink needs this to make the 
sl@0: 	        BufferEmptiedL callback on aSupplier to indicate to the data source that the data sink
sl@0: 	        has finished with the buffer.
sl@0: 	@param  aMediaId
sl@0: 	        This identifies the type of media eg. audio or video and the stream ID.
sl@0: 	        This parameter is required in cases where the source can supply data
sl@0: 	        of more than one media type and/or multiple streams of data.
sl@0: 	*/
sl@0: 	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Function called by a data source to pass back a filled buffer to the sink.
sl@0: 
sl@0: 	This is a pure virtual function that each derived class must implement.
sl@0: 	This method is used as the callback when the data sink actively requests a supplier ie. a
sl@0: 	data source	to fill a buffer by calling the data sources FillBufferL. When the data sink gets
sl@0: 	this callback it knows that the buffer has been filled and is ready to be emptied.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer that has been filled by a data source and is now available for processing.
sl@0: 	*/
sl@0: 	virtual void BufferFilledL(CMMFBuffer* aBuffer)=0;
sl@0: 	
sl@0: 	/**
sl@0: 	@deprecated
sl@0: 
sl@0: 	Function to indicate whether the data sink can create a buffer.
sl@0: 
sl@0: 	This is a pure virtual function that each derived class must implement.
sl@0: 
sl@0: 	@return	A boolean indicating if the data sink can create a buffer. ETrue if it can otherwise 
sl@0: 	        EFalse.
sl@0: 	*/
sl@0: 	virtual TBool CanCreateSinkBuffer()=0;
sl@0: 	
sl@0: 	/**
sl@0: 	Returns a buffer created by the data sink.
sl@0: 
sl@0: 	This is a pure virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        This identifies the type of media eg. audio or video and the stream ID.
sl@0: 	        This parameter is required in cases where the source can supply data
sl@0: 	        of more than one media type and/or multiple streams of data.
sl@0: 
sl@0: 	@param  aReference
sl@0: 	        This must be written to by the method to indicate whether the created buffer is
sl@0: 	        a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the sink
sl@0: 	        and should be used in preference to the source buffer provided the source buffer
sl@0: 	        is also not a reference buffer.
sl@0: 
sl@0: 	@return	The created buffer.
sl@0: 	*/
sl@0: 	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
sl@0: 
sl@0: 	inline virtual TInt SinkThreadLogon(MAsyncEventHandler& aEventHandler);
sl@0: 
sl@0: 	/**
sl@0: 	Function to 'logoff' the data sink from the same thread that sink consumes data in.
sl@0: 
sl@0: 	This method may be required as the thread that the data sink is deleted in may not be
sl@0: 	the same thread that the data transfer took place in.  Therefore any thread specific
sl@0: 	releasing of resources needs to be performed in the SinkThreadLogoff rather than in the
sl@0: 	destructor.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if any thread specific
sl@0: 	releasing of resources is required.
sl@0: 	*/
sl@0: 	virtual void SinkThreadLogoff() {};
sl@0: 
sl@0: 	inline virtual void NegotiateL(MDataSource& aDataSource);
sl@0: 
sl@0: 	/**
sl@0: 	Function to 'prime' the data sink.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if
sl@0: 	any data sink specific 'priming' is required.
sl@0: 	*/
sl@0: 	virtual void SinkPrimeL() {};
sl@0: 
sl@0: 	/**
sl@0: 	Function 'play' the data sink.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if
sl@0: 	any data sink specific action is required prior to 'playing' ie. the start of data transfer.
sl@0: 	*/
sl@0: 	virtual void SinkPlayL() {};
sl@0: 
sl@0: 	/**
sl@0: 	Function to 'pause' the data sink.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if
sl@0: 	any data sink specific action is required to 'pause'.
sl@0: 	*/
sl@0: 	virtual void SinkPauseL() {};
sl@0: 
sl@0: 	/**
sl@0: 	Function to 'stop' the data sink.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if
sl@0: 	any data sink specific action is required to 'stop'
sl@0: 	*/
sl@0: 	virtual void SinkStopL() {};
sl@0: 
sl@0: 	inline virtual void SetSinkPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
sl@0: 
sl@0: 	/**
sl@0: 	Calls a sink specific custom command.
sl@0: 
sl@0: 	This is a virtual function that a derrived data sink can implement if
sl@0: 	it implements any custom commands.
sl@0: 
sl@0: 	@param  aMessage
sl@0: 	        The message specifying the custom command.
sl@0: 	*/
sl@0: 	virtual void SinkCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};
sl@0: 	
sl@0: protected:
sl@0: 	/**
sl@0: 	Performs any sink construction dependant on the sink construction
sl@0: 	initialisation data aInitData.
sl@0: 
sl@0: 	This is a pure virtual function that a derrived data sink must implement
sl@0: 
sl@0: 	@param  aInitData
sl@0: 	        The sink specific initialisation data required for sink construction.
sl@0: 	*/
sl@0: 	virtual void ConstructSinkL( const TDesC8& aInitData ) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Protected constructor.
sl@0: 
sl@0: 	@param  aType
sl@0: 	        The source type UID.
sl@0: 	*/
sl@0: 	MDataSink(TUid aType): iDataSinkType(aType),iDtor_ID_Key(TUid::Null()) {}
sl@0: 	
sl@0: private:
sl@0: 	TUid iDataSinkType;
sl@0: 	TUid iDtor_ID_Key;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: Instantiates a new data sink.
sl@0: 
sl@0: @param  aImplementationUid
sl@0:         The UID identifying the data sink to be instantiated.
sl@0: @param  aInitData
sl@0:         The sink specific initialisation data required for sink construction.
sl@0: 
sl@0: @return	A pointer to the instantiated data sink.
sl@0: */
sl@0: inline MDataSink* MDataSink::NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData )
sl@0: 	{
sl@0: 	MDataSink* retPtr = REINTERPRET_CAST( MDataSink*, REComSession::CreateImplementationL( aImplementationUid,
sl@0: 																			_FOFF(MDataSink, iDtor_ID_Key) ) ) ;
sl@0: 	CleanupDeletePushL(retPtr);
sl@0: 	retPtr->ConstructSinkL( aInitData ) ;
sl@0: 
sl@0: 	CleanupStack::Pop(retPtr);
sl@0: 	return retPtr ;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sets the data type as a fourCC code for the data sink.
sl@0: 
sl@0: This is a virtual function that each derived class can implement if the data sink supports
sl@0: the ability to have its data type set.
sl@0: 
sl@0: @param  aSinkFourCC
sl@0:         This specifies the data type as a fourCC code to set the sink to.
sl@0: @param  aMediaId
sl@0:         This identifies the type of media eg. audio or video and the stream ID.
sl@0:         This parameter is required in cases where the source can supply data
sl@0:         of more than one media type and/or multiple streams of data.
sl@0: 
sl@0: @return	KErrNone if successful, KErrNotSupported if the sink does not support having
sl@0:         it's data type set, otherwise a system wide error code.
sl@0: */
sl@0: inline TInt MDataSink::SetSinkDataTypeCode(TFourCC /*aSinkFourCC*/, TMediaId /*aMediaId*/)
sl@0: {
sl@0: 	return KErrNotSupported;
sl@0: }
sl@0: 
sl@0: /**
sl@0: Function to 'logon' the data sink to the same thread that sink will be consuming data in.
sl@0: 
sl@0: This method may be required as the thread that the data sink was created in is not always
sl@0: the same thread that the data transfer will take place in.  Therefore any thread specific
sl@0: initialisation needs to be performed in the SinkThreadLogon rather than in the creation
sl@0: of the data sink.
sl@0: 
sl@0: This is a virtual function that a derrived data sink can implement if any thread specific
sl@0: initialisation is required and/or the data sink can create any asynchronous events.
sl@0: 
sl@0: @param  aEventHandler
sl@0:         This is an MAsyncEventHandler to handle asynchronous events that occur during the
sl@0:         transfer of multimedia data. The event handler must be in the same thread as the data
sl@0:         transfer thread - hence the reason it is passed in the SinkThreadLogon as opposed to
sl@0:         say the constructor.
sl@0: 
sl@0: @return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0:         another of the system-wide error codes.
sl@0: */
sl@0: inline TInt MDataSink::SinkThreadLogon(MAsyncEventHandler& /*aEventHandler*/)
sl@0: {
sl@0: 	return KErrNone;
sl@0: }
sl@0: 
sl@0: /**
sl@0: @deprecated
sl@0: 
sl@0: Allows the data sink to negotiate with a data source.
sl@0: 
sl@0: This method is required in cases where the settings of data sink are dependant on those of a
sl@0: data source. This is a virtual function that a derrived data sink can implement.
sl@0: 
sl@0: @param  aDataSource
sl@0:         The data source whose settings can affect the data sink.
sl@0: */
sl@0: inline void MDataSink::NegotiateL(MDataSource& /*aDataSource*/)
sl@0: {
sl@0: }
sl@0: 
sl@0: /**
sl@0: Sets the sink priority settings.
sl@0: 
sl@0: This is a virtual function that a derrived data sink can implement if
sl@0: a priority mechanism is required to arbitrate between multiple clients
sl@0: trying to access the same resource.
sl@0: 
sl@0: @param  aPrioritySettings
sl@0:         The sink priority settings.
sl@0: 
sl@0: */
sl@0: inline void MDataSink::SetSinkPrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)
sl@0: {
sl@0: }
sl@0: 
sl@0: /**
sl@0: This function is used by TCleanupItem objects to perform
sl@0: a SinkStopL() when leaving functions exist, ususally between SinkPrimeL-SinkStopL pairs.
sl@0: 
sl@0: @param  aSink
sl@0:         The data sink to be stopped.
sl@0: */
sl@0: inline static void DoDataSinkStop(TAny* aSink)
sl@0: 	{
sl@0: 	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);
sl@0: 	// we don't want this function to leave because no leaving functions are supposed
sl@0: 	// to be used as argument to the TCleanupItem objects. Hence we catch the error but
sl@0: 	// we do nothing with it.
sl@0: 	TRAP_IGNORE(sink->SinkStopL());
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method is used by TCleanupItem objects to perform a SinkThreadLogoff().
sl@0: 
sl@0: @param  aSink
sl@0:         The data sink to be logged off.
sl@0: */
sl@0: inline static void DoDataSinkThreadLogoff(TAny* aSink)
sl@0: 	{
sl@0: 	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);
sl@0: 	sink->SinkThreadLogoff();
sl@0: 	}
sl@0: 
sl@0: 
sl@0: #endif