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