williamr@2: // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: // include\mmf\Server\mmfdatasource.h
williamr@2: // 
williamr@2: //
williamr@2: 
williamr@2: #ifndef __MMF_SERVER_DATASOURCE_H__
williamr@2: #define __MMF_SERVER_DATASOURCE_H__
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <mmf/server/mmfdatasourcesink.hrh>
williamr@2: #include <mmf/common/mmfutilities.h>
williamr@2: #include <ecom/ecom.h>
williamr@2: #include <mmf/common/mmfbase.h>
williamr@2: #include <mmf/common/mmfcontrollerframework.h>
williamr@2: 
williamr@2: //
williamr@2: // MDataSource mixim
williamr@2: //
williamr@2: 
williamr@2: class CMMFBuffer;
williamr@2: class MDataSink;
williamr@2: class MAsyncEventHandler;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Abstract class representing a data source.
williamr@2: */
williamr@2: class MDataSource
williamr@2: 	{
williamr@2: public:
williamr@2: 	static inline MDataSource* NewSourceL( TUid aImplementationUid,  const TDesC8& aInitData ) ;
williamr@2: 
williamr@2: 	/**
williamr@2: 	Destructor.
williamr@2: 	*/
williamr@2: 	virtual ~MDataSource() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the UID identifying the type of data source.
williamr@2: 
williamr@2: 	@return	The UID identifying the type of data source.
williamr@2: 	*/
williamr@2: 	virtual TUid DataSourceType() const {return iDataSourceType;};
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the data type as a fourCC code of the data source.
williamr@2: 
williamr@2: 	This is a pure virtual function that each derrived class must implement.
williamr@2: 
williamr@2: 	@param  aMediaId
williamr@2: 	        This identifies the type of media eg. audio or video and the stream ID.
williamr@2: 	        This parameter is required in cases where the source can supply data
williamr@2: 	        of more than one media type and/or multiple streams of data.
williamr@2: 
williamr@2: 	@return The fourCC code identifying the source datatype for the specified aMediaId.
williamr@2: 	*/
williamr@2: 	virtual TFourCC SourceDataTypeCode(TMediaId aMediaId) = 0;
williamr@2: 
williamr@2: 	inline virtual TInt SetSourceDataTypeCode(TFourCC aSourceFourCC, TMediaId aMediaId);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function called by a MDataSink to request the data source to fill aBuffer with data.
williamr@2: 
williamr@2: 	This is a pure virtual function that each derived class must implement.
williamr@2: 	This method is used when a data source is passively waiting for requests from a consumer ie. a data sink
williamr@2: 	to fill a buffer. The data source must call the BufferFilledL member on aConsumer when it has filled
williamr@2: 	the buffer with data. The data source can either make this callback synchronously or asynchronously.
williamr@2: 
williamr@2: 	The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
williamr@2: 	function. From this, the format should be able to determine the actual position of the data on
williamr@2: 	the data source. The technique here depends on the nature of the format. For a linear audio
williamr@2: 	format, the position can be obtained by a simple calculation of the frame size, the header size
williamr@2: 	and where appropriate the datatype.
williamr@2: 
williamr@2: 	For non-linear formats, either an index table of frame number and location will need to be
williamr@2: 	created in the NewL() or some form of approximating algorithm will be required. Some formats
williamr@2: 	have an index table as part of the format eg. AVI. If no random access is required then no index
williamr@2: 	table is required, the format can keep track of the current read position and increment it on
williamr@2: 	each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear
williamr@2: 	ie. variable bit rate formats, the size of the data read may vary from frame to frame, then the
williamr@2: 	format should either set the request size of the buffer for the required frame or call the
williamr@2: 	source's ReadBufferL() (either CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or
williamr@2: 	CMMFFile::ReadBufferL()) function that takes the aLength parameter.
williamr@2: 
williamr@2: 	It is the responsibility of the format decode to determine the size and position of the source
williamr@2: 	data for each frame. For linear audio formats, the format decode should fill the buffer up to
williamr@2: 	its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively
williamr@2: 	acting as a demultiplexor, and must obtain the appropriate data from the source depending on
williamr@2: 	the aMediaId.
williamr@2: 
williamr@2: 	@param  aBuffer
williamr@2: 	        The buffer that needs filling with data.
williamr@2: 	@param  aConsumer
williamr@2: 	        The data sink that consumes the data. The data source needs this to make the BufferFilledL
williamr@2: 	        callback on aConsumer when the data source has completed filling the aBuffer.
williamr@2: 	@param  aMediaId
williamr@2: 	        This identifies the type of media eg. audio or video and the stream ID.
williamr@2: 	        This parameter is required in cases where the source can supply data
williamr@2: 	        of more than one media type and/or multiple strams of data eg. a multimedia file.
williamr@2: 	*/
williamr@2: 	virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer,TMediaId aMediaId)=0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function called by a data sink to pass back an emptied buffer to the source.
williamr@2: 
williamr@2: 	This is a pure virtual function that each derived class must implement.
williamr@2: 	This method is used as the callback when the data source actively requests a consumer ie. a data
williamr@2: 	sink to empty a buffer by calling the data sinks EmptyBufferL.
williamr@2: 	When the data source gets this callback it knows that the buffer has been emptied and can be
williamr@2: 	reused.
williamr@2: 
williamr@2: 	@param  aBuffer
williamr@2: 	        The buffer that has been emptied by a data sink and is now available for reuse.
williamr@2: 	*/
williamr@2: 	virtual void BufferEmptiedL(CMMFBuffer* aBuffer)=0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	@deprecated
williamr@2: 
williamr@2: 	Function to indicate whether the data source can create a buffer.
williamr@2: 
williamr@2: 	This is a pure virtual function that each derived class must implement.
williamr@2: 
williamr@2: 	@return	A boolean indicating if the data source can create a buffer. ETrue if it can otherwise
williamr@2: 	        EFalse.
williamr@2: 	*/
williamr@2: 	virtual TBool CanCreateSourceBuffer()=0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	@deprecated
williamr@2: 
williamr@2: 	Returns a buffer created by the data source
williamr@2: 
williamr@2: 	This is a pure virtual function that each derived class must implement.
williamr@2: 
williamr@2: 	@param	aMediaId
williamr@2: 	        This identifies the type of media eg. audio or video and the stream ID.
williamr@2: 	        This parameter is required in cases where the source can supply data
williamr@2: 	        of more than one media type and/or multiple strams of data eg a multimedia file.
williamr@2: 	@param  aReference
williamr@2: 	        This must be written to by the method to indicate whether the created buffer is
williamr@2: 	        a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the source
williamr@2: 	        and should be used in preference to the sink buffer provided the sink buffer
williamr@2: 	        is also not a reference buffer.
williamr@2: 
williamr@2: 	@return	A pointer to the created buffer.
williamr@2: 	*/
williamr@2: 	virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference) = 0;
williamr@2: 
williamr@2: 	inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& aSinkBuffer, TBool &aReference);
williamr@2: 
williamr@2: 	inline virtual TInt SourceThreadLogon(MAsyncEventHandler& aEventHandler);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function to 'logoff' the data source from the same thread that source supplies data in.
williamr@2: 
williamr@2: 	This method may be required as the thread that the data source is deleted in may not be
williamr@2: 	the same thread that the data transfer took place in.  Therefore any thread specific
williamr@2: 	releasing of resources needs to be performed in the SourceThreadLogoff rather than in the
williamr@2: 	destructor.
williamr@2: 
williamr@2: 	This is a virtual function that a derrived data source can implement if any thread specific
williamr@2: 	releasing of resources is required.
williamr@2: 	*/
williamr@2: 	virtual void SourceThreadLogoff() {};
williamr@2: 
williamr@2: 	inline virtual void NegotiateSourceL(MDataSink& aDataSink); //called if source setup depends on sink
williamr@2: 
williamr@2: 	/**
williamr@2: 	Indicates whether the data source supports sample rate conversion.
williamr@2: 
williamr@2: 	This is a virtual function that a derived class can implement.
williamr@2: 
williamr@2: 	@return	A boolean indicating if the data source can perform a sample rate conversion. ETrue if 
williamr@2: 	        it can otherwise EFalse.
williamr@2: 	*/
williamr@2: 	virtual TBool SourceSampleConvert() {return EFalse;};
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Function to 'prime' the data source.
williamr@2: 	
williamr@2: 	This is a virtual function that a derrived data source can implement if
williamr@2: 	any data source specific 'priming' is required.
williamr@2: 	*/
williamr@2: 	virtual void SourcePrimeL() {};
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Function to 'play' the data source.
williamr@2: 
williamr@2: 	This is a virtual function that a derrived data source can implement if
williamr@2: 	any data source specific action is required prior to 'playing' ie. the start of data transfer.
williamr@2: 	*/
williamr@2: 	virtual void SourcePlayL() {};
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function to 'pause' the data source.
williamr@2: 
williamr@2: 	This is a virtual function that a derrived data source can implement if
williamr@2: 	any data source specific action is required to 'pause'
williamr@2: 	*/
williamr@2: 	virtual void SourcePauseL() {};
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function to 'stop' the data source.
williamr@2: 
williamr@2: 	This is a virtual function that a derrived data source can implement if
williamr@2: 	any data source specific action is required to 'stop'.
williamr@2: 	*/
williamr@2: 	virtual void SourceStopL() {};
williamr@2: 
williamr@2: 	inline virtual void SetSourcePrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Function to call a source specific custom command.
williamr@2: 
williamr@2: 	This is a virtual function that a derrived data source can implement if
williamr@2: 	it implements any custom commands.
williamr@2: 
williamr@2: 	@param  aMessage
williamr@2: 	        The message specifying the custom command.
williamr@2: 	*/
williamr@2: 	virtual void SourceCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};
williamr@2: protected:
williamr@2: 
williamr@2: 	/**
williamr@2: 	Performs any source construction dependant on the source construction
williamr@2: 	initialisation data aInitData.
williamr@2: 
williamr@2: 	This is a pure virtual function that a derrived data source must implement
williamr@2: 
williamr@2: 	@param  aInitData
williamr@2: 	        The source specific initialisation data required for source construction.
williamr@2: 	*/
williamr@2: 	virtual void ConstructSourceL(  const TDesC8& aInitData ) = 0 ;
williamr@2: 
williamr@2: 	/**
williamr@2: 	Protected constructor.
williamr@2: 	*/
williamr@2: 	MDataSource(TUid aType): iDataSourceType(aType) {}
williamr@2: private:
williamr@2: 	TUid iDataSourceType;
williamr@2: 	TUid iDtor_ID_Key;
williamr@2: 
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Instantiates a data source.
williamr@2: 
williamr@2: @param  aImplementationUid
williamr@2:         The UID identifying the data source to be instantiated.
williamr@2: @param  aInitData
williamr@2:         The source specific initialisation data required for source construction.
williamr@2: 
williamr@2: @return	The instantiated data source.
williamr@2: */
williamr@2: inline MDataSource* MDataSource::NewSourceL( TUid aImplementationUid, const TDesC8& aInitData )
williamr@2: 	{
williamr@2: 	MDataSource* retPtr = REINTERPRET_CAST( MDataSource*, REComSession::CreateImplementationL( aImplementationUid,
williamr@2: 																			_FOFF(MDataSource, iDtor_ID_Key) ) ) ;
williamr@2: 	CleanupDeletePushL(retPtr);
williamr@2: 	retPtr->ConstructSourceL( aInitData ) ;
williamr@2: 
williamr@2: 	CleanupStack::Pop(retPtr);
williamr@2: 	return retPtr ;
williamr@2: 	}
williamr@2: 
williamr@2: /**
williamr@2: Sets the data type as a fourCC code for the data source.
williamr@2: 
williamr@2: This is a virtual function that each derived class can implement if the data source supports
williamr@2: the ability to have its data type set.
williamr@2: 
williamr@2: @param  aSourceFourCC
williamr@2:         This specifies the data type as a fourCC code to set the source to.
williamr@2: @param  aMediaId
williamr@2:         This identifies the type of media eg. audio or video and the stream ID.
williamr@2:         This parameter is required in cases where the source can supply data
williamr@2:         of more than one media type and/or multiple strams of data eg a multimedia file.
williamr@2: 
williamr@2: @return	KErrNone if successful, KErrNotSupported if the source does not support having
williamr@2:         it's data type set, otherwise a system wide error code.
williamr@2: */
williamr@2: inline TInt MDataSource::SetSourceDataTypeCode(TFourCC /*aSourceFourCC*/, TMediaId /*aMediaId*/)
williamr@2: {
williamr@2: 	return KErrNotSupported;
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2: @deprecated
williamr@2: 
williamr@2: Returns a buffer created by the data source.
williamr@2: 
williamr@2: This is a virtual function that a derived class can implement.
williamr@2: This can be used in preference to the above CreateSourceBufferL method in cases where
williamr@2: the source buffer creation has a dependancy on the sink buffer.
williamr@2: 
williamr@2: @param  aMediaId
williamr@2:         This identifies the type of media eg. audio or video and the stream ID.
williamr@2:         This parameter is required in cases where the source can supply data
williamr@2:         of more than one media type and/or multiple strams of data eg a multimedia file
williamr@2: @param  aSinkBuffer
williamr@2:         The sink buffer the nature of which may influence the creation of the source buffer.
williamr@2: @param  aReference
williamr@2:         This must be written to by the method to indicate whether the created buffer is
williamr@2:         a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the source
williamr@2:         and should be used in preference to the sink buffer provided the sink buffer is not a
williamr@2:         reference buffer.
williamr@2: 
williamr@2: @return A pointer to the created buffer.
williamr@2: */
williamr@2: inline CMMFBuffer* MDataSource::CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& /*aSinkBuffer*/, TBool &aReference)
williamr@2: {
williamr@2: 	return CreateSourceBufferL(aMediaId, aReference);
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2: Function to 'logon' the data source to the same thread that source will be supplying data in.
williamr@2: 
williamr@2: This method may be required as the thread that the data source was created in is not always
williamr@2: the same thread that the data transfer will take place in.  Therefore any thread specific
williamr@2: initialisation needs to be performed in the SourceThreadLogon rather than in the creation
williamr@2: of the data source.
williamr@2: 
williamr@2: This is a virtual function that a derrived data source can implement if any thread specific
williamr@2: initialisation is required and/or the data source can create any asynchronous events.
williamr@2: 
williamr@2: @param  aEventHandler
williamr@2:         This is an MAsyncEventHandler to handle asynchronous events that occur during the
williamr@2:         transfer of multimedia data.  The event handler must be in the same thread as the data transfer
williamr@2:         thread. Hence the reason it is passed in the SourceThreadLogon as opposed to say the constructor.
williamr@2: 
williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, otherwise
williamr@2:         another of the system-wide error codes.
williamr@2: */
williamr@2: inline TInt MDataSource::SourceThreadLogon(MAsyncEventHandler& /*aEventHandler*/)
williamr@2: {
williamr@2: 	return KErrNone;
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2: Function to allow the data source to negotiate with a data sink
williamr@2: 
williamr@2: This method is required in cases where the settings of data source are dependant on those of a
williamr@2: data sink. This is a virtual function that a derrived data source can implement.
williamr@2: 
williamr@2: @param  aDataSink
williamr@2:         The data sink whose settings can affect the data source.
williamr@2: */
williamr@2: inline void MDataSource::NegotiateSourceL(MDataSink& /*aDataSink*/)
williamr@2: {
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2: Function to set the source priority settings.
williamr@2: 
williamr@2: This is a virtual function that a derrived data source can implement if
williamr@2: a priority mechanism is required to arbitrate between multiple clients
williamr@2: trying to access the same resource.
williamr@2: 
williamr@2: @param  aPrioritySettings
williamr@2:         The source priority settings.
williamr@2: 
williamr@2: */
williamr@2: inline void MDataSource::SetSourcePrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)
williamr@2: {
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2: This function is used by TCleanupItem objects to perform
williamr@2: a SourceStopL() when leaving functions exist, ususally between SourcePrimeL-SourceStopL pairs.
williamr@2: 
williamr@2: @param  aSource
williamr@2:         The data source to be stopped.
williamr@2: */
williamr@2: inline static void DoDataSourceStop(TAny* aSource)
williamr@2: 	{
williamr@2: 	MDataSource* source = STATIC_CAST(MDataSource*, aSource);
williamr@2: 	// we don't want this function to leave because no leaving functions are supposed
williamr@2: 	// to be used as argument to the TCleanupItem objects. Hence we catch the error but
williamr@2: 	// we do nothing with it.
williamr@2: 	TRAP_IGNORE(source->SourceStopL());
williamr@2: 	}
williamr@2: 
williamr@2: /**
williamr@2: This method is used by TCleanupItem objects to perform a SourceThreadLogoff().
williamr@2: 
williamr@2: @param  aSource
williamr@2:         The data source to be logged off.
williamr@2: */
williamr@2: inline static void DoDataSourceThreadLogoff(TAny* aSource)
williamr@2: 	{
williamr@2: 	MDataSource* source = STATIC_CAST(MDataSource*, aSource);
williamr@2: 	source->SourceThreadLogoff();
williamr@2: 	}
williamr@2: 
williamr@2: #endif