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 sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: #include 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