diff -r 000000000000 -r 40261b775718 mmlibs/mmfw/inc/mmf/server/mmfdatasource.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmlibs/mmfw/inc/mmf/server/mmfdatasource.h Tue Feb 02 01:56:55 2010 +0200 @@ -0,0 +1,410 @@ +// 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 "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: +// include\mmf\Server\mmfdatasource.h +// +// + +#ifndef __MMF_SERVER_DATASOURCE_H__ +#define __MMF_SERVER_DATASOURCE_H__ + +#include +#include +#include +#include +#include +#include + +// +// MDataSource mixim +// + +class CMMFBuffer; +class MDataSink; +class MAsyncEventHandler; + +/** +@publishedAll +@released + +Abstract class representing a data source. +*/ +class MDataSource + { +public: + static inline MDataSource* NewSourceL( TUid aImplementationUid, const TDesC8& aInitData ) ; + + /** + Destructor. + */ + virtual ~MDataSource() {REComSession::DestroyedImplementation(iDtor_ID_Key);}; + + /** + Returns the UID identifying the type of data source. + + @return The UID identifying the type of data source. + */ + virtual TUid DataSourceType() const {return iDataSourceType;}; + + /** + Returns the data type as a fourCC code of the data source. + + 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 source can supply data + of more than one media type and/or multiple streams of data. + + @return The fourCC code identifying the source datatype for the specified aMediaId. + */ + virtual TFourCC SourceDataTypeCode(TMediaId aMediaId) = 0; + + inline virtual TInt SetSourceDataTypeCode(TFourCC aSourceFourCC, TMediaId aMediaId); + + /** + Function called by a MDataSink to request the data source to fill aBuffer with data. + + This is a pure virtual function that each derived class must implement. + This method is used when a data source is passively waiting for requests from a consumer ie. a data sink + to fill a buffer. The data source must call the BufferFilledL member on aConsumer when it has filled + the buffer with data. The data source can either make this callback synchronously or asynchronously. + + The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber() + function. From this, the format should be able to determine the actual position of the data on + the data source. The technique here depends on the nature of the format. For a linear audio + format, the position can be obtained by a simple calculation of the frame size, the header size + and where appropriate the datatype. + + For non-linear formats, either an index table of frame number and location will need to be + created in the NewL() or some form of approximating algorithm will be required. Some formats + have an index table as part of the format eg. AVI. If no random access is required then no index + table is required, the format can keep track of the current read position and increment it on + each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear + ie. variable bit rate formats, the size of the data read may vary from frame to frame, then the + format should either set the request size of the buffer for the required frame or call the + source's ReadBufferL() (either CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or + CMMFFile::ReadBufferL()) function that takes the aLength parameter. + + It is the responsibility of the format decode to determine the size and position of the source + data for each frame. For linear audio formats, the format decode should fill the buffer up to + its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively + acting as a demultiplexor, and must obtain the appropriate data from the source depending on + the aMediaId. + + @param aBuffer + The buffer that needs filling with data. + @param aConsumer + The data sink that consumes the data. The data source needs this to make the BufferFilledL + callback on aConsumer when the data source has completed filling the aBuffer. + @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 strams of data eg. a multimedia file. + */ + virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer,TMediaId aMediaId)=0; + + /** + Function called by a data sink to pass back an emptied buffer to the source. + + This is a pure virtual function that each derived class must implement. + This method is used as the callback when the data source actively requests a consumer ie. a data + sink to empty a buffer by calling the data sinks EmptyBufferL. + When the data source gets this callback it knows that the buffer has been emptied and can be + reused. + + @param aBuffer + The buffer that has been emptied by a data sink and is now available for reuse. + */ + virtual void BufferEmptiedL(CMMFBuffer* aBuffer)=0; + + /** + @deprecated + + Function to indicate whether the data source can create a buffer. + + This is a pure virtual function that each derived class must implement. + + @return A boolean indicating if the data source can create a buffer. ETrue if it can otherwise + EFalse. + */ + virtual TBool CanCreateSourceBuffer()=0; + + /** + @deprecated + + Returns a buffer created by the data source + + 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 strams of data eg a multimedia file. + @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 source + and should be used in preference to the sink buffer provided the sink buffer + is also not a reference buffer. + + @return A pointer to the created buffer. + */ + virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference) = 0; + + inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& aSinkBuffer, TBool &aReference); + + inline virtual TInt SourceThreadLogon(MAsyncEventHandler& aEventHandler); + + /** + Function to 'logoff' the data source from the same thread that source supplies data in. + + This method may be required as the thread that the data source 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 SourceThreadLogoff rather than in the + destructor. + + This is a virtual function that a derrived data source can implement if any thread specific + releasing of resources is required. + */ + virtual void SourceThreadLogoff() {}; + + inline virtual void NegotiateSourceL(MDataSink& aDataSink); //called if source setup depends on sink + + /** + Indicates whether the data source supports sample rate conversion. + + This is a virtual function that a derived class can implement. + + @return A boolean indicating if the data source can perform a sample rate conversion. ETrue if + it can otherwise EFalse. + */ + virtual TBool SourceSampleConvert() {return EFalse;}; + + /** + Function to 'prime' the data source. + + This is a virtual function that a derrived data source can implement if + any data source specific 'priming' is required. + */ + virtual void SourcePrimeL() {}; + + /** + Function to 'play' the data source. + + This is a virtual function that a derrived data source can implement if + any data source specific action is required prior to 'playing' ie. the start of data transfer. + */ + virtual void SourcePlayL() {}; + + /** + Function to 'pause' the data source. + + This is a virtual function that a derrived data source can implement if + any data source specific action is required to 'pause' + */ + virtual void SourcePauseL() {}; + + /** + Function to 'stop' the data source. + + This is a virtual function that a derrived data source can implement if + any data source specific action is required to 'stop'. + */ + virtual void SourceStopL() {}; + + inline virtual void SetSourcePrioritySettings(const TMMFPrioritySettings& aPrioritySettings); + + /** + Function to call a source specific custom command. + + This is a virtual function that a derrived data source can implement if + it implements any custom commands. + + @param aMessage + The message specifying the custom command. + */ + virtual void SourceCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);}; +protected: + + /** + Performs any source construction dependant on the source construction + initialisation data aInitData. + + This is a pure virtual function that a derrived data source must implement + + @param aInitData + The source specific initialisation data required for source construction. + */ + virtual void ConstructSourceL( const TDesC8& aInitData ) = 0 ; + + /** + Protected constructor. + */ + MDataSource(TUid aType): iDataSourceType(aType) {} +private: + TUid iDataSourceType; + TUid iDtor_ID_Key; + + }; + +/** +Instantiates a data source. + +@param aImplementationUid + The UID identifying the data source to be instantiated. +@param aInitData + The source specific initialisation data required for source construction. + +@return The instantiated data source. +*/ +inline MDataSource* MDataSource::NewSourceL( TUid aImplementationUid, const TDesC8& aInitData ) + { + MDataSource* retPtr = REINTERPRET_CAST( MDataSource*, REComSession::CreateImplementationL( aImplementationUid, + _FOFF(MDataSource, iDtor_ID_Key) ) ) ; + CleanupDeletePushL(retPtr); + retPtr->ConstructSourceL( aInitData ) ; + + CleanupStack::Pop(retPtr); + return retPtr ; + } + +/** +Sets the data type as a fourCC code for the data source. + +This is a virtual function that each derived class can implement if the data source supports +the ability to have its data type set. + +@param aSourceFourCC + This specifies the data type as a fourCC code to set the source 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 strams of data eg a multimedia file. + +@return KErrNone if successful, KErrNotSupported if the source does not support having + it's data type set, otherwise a system wide error code. +*/ +inline TInt MDataSource::SetSourceDataTypeCode(TFourCC /*aSourceFourCC*/, TMediaId /*aMediaId*/) +{ + return KErrNotSupported; +} + +/** +@deprecated + +Returns a buffer created by the data source. + +This is a virtual function that a derived class can implement. +This can be used in preference to the above CreateSourceBufferL method in cases where +the source buffer creation has a dependancy on the sink 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 strams of data eg a multimedia file +@param aSinkBuffer + The sink buffer the nature of which may influence the creation of the source buffer. +@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 source + and should be used in preference to the sink buffer provided the sink buffer is not a + reference buffer. + +@return A pointer to the created buffer. +*/ +inline CMMFBuffer* MDataSource::CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& /*aSinkBuffer*/, TBool &aReference) +{ + return CreateSourceBufferL(aMediaId, aReference); +} + +/** +Function to 'logon' the data source to the same thread that source will be supplying data in. + +This method may be required as the thread that the data source 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 SourceThreadLogon rather than in the creation +of the data source. + +This is a virtual function that a derrived data source can implement if any thread specific +initialisation is required and/or the data source 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 SourceThreadLogon 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 MDataSource::SourceThreadLogon(MAsyncEventHandler& /*aEventHandler*/) +{ + return KErrNone; +} + +/** +Function to allow the data source to negotiate with a data sink + +This method is required in cases where the settings of data source are dependant on those of a +data sink. This is a virtual function that a derrived data source can implement. + +@param aDataSink + The data sink whose settings can affect the data source. +*/ +inline void MDataSource::NegotiateSourceL(MDataSink& /*aDataSink*/) +{ +} + +/** +Function to set the source priority settings. + +This is a virtual function that a derrived data source can implement if +a priority mechanism is required to arbitrate between multiple clients +trying to access the same resource. + +@param aPrioritySettings + The source priority settings. + +*/ +inline void MDataSource::SetSourcePrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/) +{ +} + +/** +This function is used by TCleanupItem objects to perform +a SourceStopL() when leaving functions exist, ususally between SourcePrimeL-SourceStopL pairs. + +@param aSource + The data source to be stopped. +*/ +inline static void DoDataSourceStop(TAny* aSource) + { + MDataSource* source = STATIC_CAST(MDataSource*, aSource); + // 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(source->SourceStopL()); + } + +/** +This method is used by TCleanupItem objects to perform a SourceThreadLogoff(). + +@param aSource + The data source to be logged off. +*/ +inline static void DoDataSourceThreadLogoff(TAny* aSource) + { + MDataSource* source = STATIC_CAST(MDataSource*, aSource); + source->SourceThreadLogoff(); + } + +#endif