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