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@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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\mmfdatasink.h williamr@2: // williamr@2: // williamr@2: williamr@2: #ifndef __MMF_SERVER_DATASINK_H__ williamr@2: #define __MMF_SERVER_DATASINK_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: // williamr@2: // MDataSink mixim williamr@2: // williamr@2: williamr@2: class TFourCC; williamr@2: class TMediaId; williamr@2: class CMMFBuffer; williamr@2: class MDataSource; williamr@2: class MAsyncEventHandler; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Abstract class representing a data sink. williamr@2: */ williamr@2: class MDataSink williamr@2: { williamr@2: public: williamr@2: williamr@2: static inline MDataSink* NewSinkL( TUid aImplementationUid, const TDesC8& aInitData ) ; williamr@2: williamr@2: /** williamr@2: Destructor. williamr@2: */ williamr@2: virtual ~MDataSink() {REComSession::DestroyedImplementation(iDtor_ID_Key);}; williamr@2: williamr@2: /** williamr@2: Returns the UID identifying the type of data sink. williamr@2: williamr@2: @return The UID identifying the type of data sink williamr@2: */ williamr@2: virtual TUid DataSinkType() const {return iDataSinkType;}; williamr@2: williamr@2: /** williamr@2: Returns the data type as a fourCC code of the data sink. 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 sink can accept 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 sink datatype for the specified aMediaId. williamr@2: */ williamr@2: virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0; williamr@2: williamr@2: inline virtual TInt SetSinkDataTypeCode(TFourCC aSinkFourCC, TMediaId aMediaId); williamr@2: williamr@2: /** williamr@2: Method called by a MDataSource to request the data sink to empty aBuffer of 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 sink is passively waiting for requests from a supplier ie. williamr@2: a data source to empty a buffer. The data sink must call the BufferEmptiedL member on aSupplier williamr@2: when it has emptied the buffer of it's data. The data sink can either make this callback williamr@2: synchronously or asynchronously. williamr@2: williamr@2: @param aBuffer williamr@2: The full buffer that needs emptying of it's data. williamr@2: @param aSupplier williamr@2: The data source that supplied the data. The data sink needs this to make the williamr@2: BufferEmptiedL callback on aSupplier to indicate to the data source that the data sink williamr@2: has finished with the buffer. 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: virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0; williamr@2: williamr@2: /** williamr@2: Function called by a data source to pass back a filled buffer to the sink. 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 sink actively requests a supplier ie. a williamr@2: data source to fill a buffer by calling the data sources FillBufferL. When the data sink gets williamr@2: this callback it knows that the buffer has been filled and is ready to be emptied. williamr@2: williamr@2: @param aBuffer williamr@2: The buffer that has been filled by a data source and is now available for processing. williamr@2: */ williamr@2: virtual void BufferFilledL(CMMFBuffer* aBuffer)=0; williamr@2: williamr@2: /** williamr@2: @deprecated williamr@2: williamr@2: Function to indicate whether the data sink 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 sink can create a buffer. ETrue if it can otherwise williamr@2: EFalse. williamr@2: */ williamr@2: virtual TBool CanCreateSinkBuffer()=0; williamr@2: williamr@2: /** williamr@2: Returns a buffer created by the data sink. 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 streams of data. williamr@2: 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 sink williamr@2: and should be used in preference to the source buffer provided the source buffer williamr@2: is also not a reference buffer. williamr@2: williamr@2: @return The created buffer. williamr@2: */ williamr@2: virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0; williamr@2: williamr@2: inline virtual TInt SinkThreadLogon(MAsyncEventHandler& aEventHandler); williamr@2: williamr@2: /** williamr@2: Function to 'logoff' the data sink from the same thread that sink consumes data in. williamr@2: williamr@2: This method may be required as the thread that the data sink 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 SinkThreadLogoff rather than in the williamr@2: destructor. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if any thread specific williamr@2: releasing of resources is required. williamr@2: */ williamr@2: virtual void SinkThreadLogoff() {}; williamr@2: williamr@2: inline virtual void NegotiateL(MDataSource& aDataSource); williamr@2: williamr@2: /** williamr@2: Function to 'prime' the data sink. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if williamr@2: any data sink specific 'priming' is required. williamr@2: */ williamr@2: virtual void SinkPrimeL() {}; williamr@2: williamr@2: /** williamr@2: Function 'play' the data sink. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if williamr@2: any data sink specific action is required prior to 'playing' ie. the start of data transfer. williamr@2: */ williamr@2: virtual void SinkPlayL() {}; williamr@2: williamr@2: /** williamr@2: Function to 'pause' the data sink. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if williamr@2: any data sink specific action is required to 'pause'. williamr@2: */ williamr@2: virtual void SinkPauseL() {}; williamr@2: williamr@2: /** williamr@2: Function to 'stop' the data sink. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if williamr@2: any data sink specific action is required to 'stop' williamr@2: */ williamr@2: virtual void SinkStopL() {}; williamr@2: williamr@2: inline virtual void SetSinkPrioritySettings(const TMMFPrioritySettings& aPrioritySettings); williamr@2: williamr@2: /** williamr@2: Calls a sink specific custom command. williamr@2: williamr@2: This is a virtual function that a derrived data sink 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 SinkCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);}; williamr@2: williamr@2: protected: williamr@2: /** williamr@2: Performs any sink construction dependant on the sink construction williamr@2: initialisation data aInitData. williamr@2: williamr@2: This is a pure virtual function that a derrived data sink must implement williamr@2: williamr@2: @param aInitData williamr@2: The sink specific initialisation data required for sink construction. williamr@2: */ williamr@2: virtual void ConstructSinkL( const TDesC8& aInitData ) = 0; williamr@2: williamr@2: /** williamr@2: Protected constructor. williamr@2: williamr@2: @param aType williamr@2: The source type UID. williamr@2: */ williamr@2: MDataSink(TUid aType): iDataSinkType(aType) {} williamr@2: williamr@2: private: williamr@2: TUid iDataSinkType; williamr@2: TUid iDtor_ID_Key; williamr@2: }; williamr@2: williamr@2: /** williamr@2: Instantiates a new data sink. williamr@2: williamr@2: @param aImplementationUid williamr@2: The UID identifying the data sink to be instantiated. williamr@2: @param aInitData williamr@2: The sink specific initialisation data required for sink construction. williamr@2: williamr@2: @return A pointer to the instantiated data sink. williamr@2: */ williamr@2: inline MDataSink* MDataSink::NewSinkL( TUid aImplementationUid, const TDesC8& aInitData ) williamr@2: { williamr@2: MDataSink* retPtr = REINTERPRET_CAST( MDataSink*, REComSession::CreateImplementationL( aImplementationUid, williamr@2: _FOFF(MDataSink, iDtor_ID_Key) ) ) ; williamr@2: CleanupDeletePushL(retPtr); williamr@2: retPtr->ConstructSinkL( 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 sink. williamr@2: williamr@2: This is a virtual function that each derived class can implement if the data sink supports williamr@2: the ability to have its data type set. williamr@2: williamr@2: @param aSinkFourCC williamr@2: This specifies the data type as a fourCC code to set the sink 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 streams of data. williamr@2: williamr@2: @return KErrNone if successful, KErrNotSupported if the sink does not support having williamr@2: it's data type set, otherwise a system wide error code. williamr@2: */ williamr@2: inline TInt MDataSink::SetSinkDataTypeCode(TFourCC /*aSinkFourCC*/, TMediaId /*aMediaId*/) williamr@2: { williamr@2: return KErrNotSupported; williamr@2: } williamr@2: williamr@2: /** williamr@2: Function to 'logon' the data sink to the same thread that sink will be consuming data in. williamr@2: williamr@2: This method may be required as the thread that the data sink 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 SinkThreadLogon rather than in the creation williamr@2: of the data sink. williamr@2: williamr@2: This is a virtual function that a derrived data sink can implement if any thread specific williamr@2: initialisation is required and/or the data sink 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 williamr@2: transfer thread - hence the reason it is passed in the SinkThreadLogon as opposed to williamr@2: 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 MDataSink::SinkThreadLogon(MAsyncEventHandler& /*aEventHandler*/) williamr@2: { williamr@2: return KErrNone; williamr@2: } williamr@2: williamr@2: /** williamr@2: @deprecated williamr@2: williamr@2: Allows the data sink to negotiate with a data source. williamr@2: williamr@2: This method is required in cases where the settings of data sink are dependant on those of a williamr@2: data source. This is a virtual function that a derrived data sink can implement. williamr@2: williamr@2: @param aDataSource williamr@2: The data source whose settings can affect the data sink. williamr@2: */ williamr@2: inline void MDataSink::NegotiateL(MDataSource& /*aDataSource*/) williamr@2: { williamr@2: } williamr@2: williamr@2: /** williamr@2: Sets the sink priority settings. williamr@2: williamr@2: This is a virtual function that a derrived data sink 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 sink priority settings. williamr@2: williamr@2: @capability MultimediaDD williamr@2: A process requesting or using this method that has MultimediaDD capability will williamr@2: always have precedence over a process that does not have MultimediaDD. williamr@2: */ williamr@2: inline void MDataSink::SetSinkPrioritySettings(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 SinkStopL() when leaving functions exist, ususally between SinkPrimeL-SinkStopL pairs. williamr@2: williamr@2: @param aSink williamr@2: The data sink to be stopped. williamr@2: */ williamr@2: inline static void DoDataSinkStop(TAny* aSink) williamr@2: { williamr@2: MDataSink* sink = STATIC_CAST(MDataSink*, aSink); 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(sink->SinkStopL()); williamr@2: } williamr@2: williamr@2: /** williamr@2: This method is used by TCleanupItem objects to perform a SinkThreadLogoff(). williamr@2: williamr@2: @param aSink williamr@2: The data sink to be logged off. williamr@2: */ williamr@2: inline static void DoDataSinkThreadLogoff(TAny* aSink) williamr@2: { williamr@2: MDataSink* sink = STATIC_CAST(MDataSink*, aSink); williamr@2: sink->SinkThreadLogoff(); williamr@2: } williamr@2: williamr@2: williamr@2: #endif