1 mmfdatasink.h

     1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // include\mmf\server\mmfdatasink.h

    15 // 

    16 //

    17 

    18 #ifndef __MMF_SERVER_DATASINK_H__

    19 #define __MMF_SERVER_DATASINK_H__

    20 

    21 #include <e32base.h>

    22 #include <mmf/server/mmfdatasourcesink.hrh>

    23 #include <mmf/common/mmfutilities.h>

    24 #include <ecom/ecom.h>

    25 #include <mmf/common/mmfbase.h>

    26 #include <mmf/common/mmfcontrollerframework.h>

    27 

    28 //

    29 // MDataSink mixim

    30 //

    31 

    32 class TFourCC;

    33 class TMediaId;

    34 class CMMFBuffer;

    35 class MDataSource;

    36 class MAsyncEventHandler;

    37 

    38 /**

    39 @publishedAll

    40 @released

    41 

    42 Abstract class representing a data sink.

    43 */

    44 class MDataSink

    45 	{

    46 public:

    47 

    48 	static inline MDataSink* NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData ) ;

    49 

    50 	/**

    51 	Destructor.

    52 	*/

    53 	virtual ~MDataSink() {REComSession::DestroyedImplementation(iDtor_ID_Key);};

    54 

    55 	/**

    56 	Returns the UID identifying the type of data sink.

    57 

    58 	@return The UID identifying the type of data sink

    59 	*/

    60 	virtual TUid DataSinkType() const {return iDataSinkType;};

    61 

    62 	/**

    63 	Returns the data type as a fourCC code of the data sink.

    64 

    65 	This is a pure virtual function that each derrived class must implement.

    66 

    67 	@param  aMediaId

    68 	        This identifies the type of media eg. audio or video and the stream ID.

    69 	        This parameter is required in cases where the sink can accept data

    70 	        of more than one media type and/or multiple streams of data.

    71 

    72 	@return The fourCC code identifying the sink datatype for the specified aMediaId.

    73 	*/

    74 	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;

    75 

    76 	inline virtual TInt SetSinkDataTypeCode(TFourCC aSinkFourCC, TMediaId aMediaId);

    77 

    78 	/**

    79 	Method called by a MDataSource to request the data sink to empty aBuffer of data.

    80 

    81 	This is a pure virtual function that each derived class must implement.

    82 	This method is used when a data sink is passively waiting for requests from a supplier ie.

    83 	a data source to empty a buffer. The data sink must call the BufferEmptiedL member on aSupplier 

    84 	when it has emptied	the buffer of it's data. The data sink can either make this callback 

    85 	synchronously or asynchronously.

    86 

    87 	@param  aBuffer

    88 	        The full buffer that needs emptying of it's data.

    89 	@param  aSupplier

    90 	        The data source that supplied the data. The data sink needs this to make the 

    91 	        BufferEmptiedL callback on aSupplier to indicate to the data source that the data sink

    92 	        has finished with the buffer.

    93 	@param  aMediaId

    94 	        This identifies the type of media eg. audio or video and the stream ID.

    95 	        This parameter is required in cases where the source can supply data

    96 	        of more than one media type and/or multiple streams of data.

    97 	*/

    98 	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;

    99 

   100 	/**

   101 	Function called by a data source to pass back a filled buffer to the sink.

   102 

   103 	This is a pure virtual function that each derived class must implement.

   104 	This method is used as the callback when the data sink actively requests a supplier ie. a

   105 	data source	to fill a buffer by calling the data sources FillBufferL. When the data sink gets

   106 	this callback it knows that the buffer has been filled and is ready to be emptied.

   107 

   108 	@param  aBuffer

   109 	        The buffer that has been filled by a data source and is now available for processing.

   110 	*/

   111 	virtual void BufferFilledL(CMMFBuffer* aBuffer)=0;

   112 	

   113 	/**

   114 	@deprecated

   115 

   116 	Function to indicate whether the data sink can create a buffer.

   117 

   118 	This is a pure virtual function that each derived class must implement.

   119 

   120 	@return	A boolean indicating if the data sink can create a buffer. ETrue if it can otherwise 

   121 	        EFalse.

   122 	*/

   123 	virtual TBool CanCreateSinkBuffer()=0;

   124 	

   125 	/**

   126 	Returns a buffer created by the data sink.

   127 

   128 	This is a pure virtual function that each derived class must implement.

   129 

   130 	@param  aMediaId

   131 	        This identifies the type of media eg. audio or video and the stream ID.

   132 	        This parameter is required in cases where the source can supply data

   133 	        of more than one media type and/or multiple streams of data.

   134 

   135 	@param  aReference

   136 	        This must be written to by the method to indicate whether the created buffer is

   137 	        a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the sink

   138 	        and should be used in preference to the source buffer provided the source buffer

   139 	        is also not a reference buffer.

   140 

   141 	@return	The created buffer.

   142 	*/

   143 	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;

   144 

   145 	inline virtual TInt SinkThreadLogon(MAsyncEventHandler& aEventHandler);

   146 

   147 	/**

   148 	Function to 'logoff' the data sink from the same thread that sink consumes data in.

   149 

   150 	This method may be required as the thread that the data sink is deleted in may not be

   151 	the same thread that the data transfer took place in.  Therefore any thread specific

   152 	releasing of resources needs to be performed in the SinkThreadLogoff rather than in the

   153 	destructor.

   154 

   155 	This is a virtual function that a derrived data sink can implement if any thread specific

   156 	releasing of resources is required.

   157 	*/

   158 	virtual void SinkThreadLogoff() {};

   159 

   160 	inline virtual void NegotiateL(MDataSource& aDataSource);

   161 

   162 	/**

   163 	Function to 'prime' the data sink.

   164 

   165 	This is a virtual function that a derrived data sink can implement if

   166 	any data sink specific 'priming' is required.

   167 	*/

   168 	virtual void SinkPrimeL() {};

   169 

   170 	/**

   171 	Function 'play' the data sink.

   172 

   173 	This is a virtual function that a derrived data sink can implement if

   174 	any data sink specific action is required prior to 'playing' ie. the start of data transfer.

   175 	*/

   176 	virtual void SinkPlayL() {};

   177 

   178 	/**

   179 	Function to 'pause' the data sink.

   180 

   181 	This is a virtual function that a derrived data sink can implement if

   182 	any data sink specific action is required to 'pause'.

   183 	*/

   184 	virtual void SinkPauseL() {};

   185 

   186 	/**

   187 	Function to 'stop' the data sink.

   188 

   189 	This is a virtual function that a derrived data sink can implement if

   190 	any data sink specific action is required to 'stop'

   191 	*/

   192 	virtual void SinkStopL() {};

   193 

   194 	inline virtual void SetSinkPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);

   195 

   196 	/**

   197 	Calls a sink specific custom command.

   198 

   199 	This is a virtual function that a derrived data sink can implement if

   200 	it implements any custom commands.

   201 

   202 	@param  aMessage

   203 	        The message specifying the custom command.

   204 	*/

   205 	virtual void SinkCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};

   206 	

   207 protected:

   208 	/**

   209 	Performs any sink construction dependant on the sink construction

   210 	initialisation data aInitData.

   211 

   212 	This is a pure virtual function that a derrived data sink must implement

   213 

   214 	@param  aInitData

   215 	        The sink specific initialisation data required for sink construction.

   216 	*/

   217 	virtual void ConstructSinkL( const TDesC8& aInitData ) = 0;

   218 

   219 	/**

   220 	Protected constructor.

   221 

   222 	@param  aType

   223 	        The source type UID.

   224 	*/

   225 	MDataSink(TUid aType): iDataSinkType(aType) {}

   226 	

   227 private:

   228 	TUid iDataSinkType;

   229 	TUid iDtor_ID_Key;

   230 	};

   231 

   232 /**

   233 Instantiates a new data sink.

   234 

   235 @param  aImplementationUid

   236         The UID identifying the data sink to be instantiated.

   237 @param  aInitData

   238         The sink specific initialisation data required for sink construction.

   239 

   240 @return	A pointer to the instantiated data sink.

   241 */

   242 inline MDataSink* MDataSink::NewSinkL( TUid aImplementationUid,  const TDesC8& aInitData )

   243 	{

   244 	MDataSink* retPtr = REINTERPRET_CAST( MDataSink*, REComSession::CreateImplementationL( aImplementationUid,

   245 																			_FOFF(MDataSink, iDtor_ID_Key) ) ) ;

   246 	CleanupDeletePushL(retPtr);

   247 	retPtr->ConstructSinkL( aInitData ) ;

   248 

   249 	CleanupStack::Pop(retPtr);

   250 	return retPtr ;

   251 	}

   252 

   253 /**

   254 Sets the data type as a fourCC code for the data sink.

   255 

   256 This is a virtual function that each derived class can implement if the data sink supports

   257 the ability to have its data type set.

   258 

   259 @param  aSinkFourCC

   260         This specifies the data type as a fourCC code to set the sink to.

   261 @param  aMediaId

   262         This identifies the type of media eg. audio or video and the stream ID.

   263         This parameter is required in cases where the source can supply data

   264         of more than one media type and/or multiple streams of data.

   265 

   266 @return	KErrNone if successful, KErrNotSupported if the sink does not support having

   267         it's data type set, otherwise a system wide error code.

   268 */

   269 inline TInt MDataSink::SetSinkDataTypeCode(TFourCC /*aSinkFourCC*/, TMediaId /*aMediaId*/)

   270 {

   271 	return KErrNotSupported;

   272 }

   273 

   274 /**

   275 Function to 'logon' the data sink to the same thread that sink will be consuming data in.

   276 

   277 This method may be required as the thread that the data sink was created in is not always

   278 the same thread that the data transfer will take place in.  Therefore any thread specific

   279 initialisation needs to be performed in the SinkThreadLogon rather than in the creation

   280 of the data sink.

   281 

   282 This is a virtual function that a derrived data sink can implement if any thread specific

   283 initialisation is required and/or the data sink can create any asynchronous events.

   284 

   285 @param  aEventHandler

   286         This is an MAsyncEventHandler to handle asynchronous events that occur during the

   287         transfer of multimedia data. The event handler must be in the same thread as the data

   288         transfer thread - hence the reason it is passed in the SinkThreadLogon as opposed to

   289         say the constructor.

   290 

   291 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   292         another of the system-wide error codes.

   293 */

   294 inline TInt MDataSink::SinkThreadLogon(MAsyncEventHandler& /*aEventHandler*/)

   295 {

   296 	return KErrNone;

   297 }

   298 

   299 /**

   300 @deprecated

   301 

   302 Allows the data sink to negotiate with a data source.

   303 

   304 This method is required in cases where the settings of data sink are dependant on those of a

   305 data source. This is a virtual function that a derrived data sink can implement.

   306 

   307 @param  aDataSource

   308         The data source whose settings can affect the data sink.

   309 */

   310 inline void MDataSink::NegotiateL(MDataSource& /*aDataSource*/)

   311 {

   312 }

   313 

   314 /**

   315 Sets the sink priority settings.

   316 

   317 This is a virtual function that a derrived data sink can implement if

   318 a priority mechanism is required to arbitrate between multiple clients

   319 trying to access the same resource.

   320 

   321 @param  aPrioritySettings

   322         The sink priority settings.

   323 

   324 @capability MultimediaDD

   325             A process requesting or using this method that has MultimediaDD capability will

   326 			always have precedence over a process that does not have MultimediaDD.

   327 */

   328 inline void MDataSink::SetSinkPrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)

   329 {

   330 }

   331 

   332 /**

   333 This function is used by TCleanupItem objects to perform

   334 a SinkStopL() when leaving functions exist, ususally between SinkPrimeL-SinkStopL pairs.

   335 

   336 @param  aSink

   337         The data sink to be stopped.

   338 */

   339 inline static void DoDataSinkStop(TAny* aSink)

   340 	{

   341 	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);

   342 	// we don't want this function to leave because no leaving functions are supposed

   343 	// to be used as argument to the TCleanupItem objects. Hence we catch the error but

   344 	// we do nothing with it.

   345 	TRAP_IGNORE(sink->SinkStopL());

   346 	}

   347 

   348 /**

   349 This method is used by TCleanupItem objects to perform a SinkThreadLogoff().

   350 

   351 @param  aSink

   352         The data sink to be logged off.

   353 */

   354 inline static void DoDataSinkThreadLogoff(TAny* aSink)

   355 	{

   356 	MDataSink* sink = STATIC_CAST(MDataSink*, aSink);

   357 	sink->SinkThreadLogoff();

   358 	}

   359 

   360 

   361 #endif