1.1 --- a/epoc32/include/mmf/server/mmfdatasink.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mmf/server/mmfdatasink.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,361 @@
1.4 -mmfdatasink.h
1.5 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// include\mmf\server\mmfdatasink.h
1.19 +//
1.20 +//
1.21 +
1.22 +#ifndef __MMF_SERVER_DATASINK_H__
1.23 +#define __MMF_SERVER_DATASINK_H__
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <mmf/server/mmfdatasourcesink.hrh>
1.27 +#include <mmf/common/mmfutilities.h>
1.28 +#include <ecom/ecom.h>
1.29 +#include <mmf/common/mmfbase.h>
1.30 +#include <mmf/common/mmfcontrollerframework.h>
1.31 +
1.32 +//
1.33 +// MDataSink mixim
1.34 +//
1.35 +
1.36 +class TFourCC;
1.37 +class TMediaId;
1.38 +class CMMFBuffer;
1.39 +class MDataSource;
1.40 +class MAsyncEventHandler;
1.41 +
1.42 +/**
1.43 +@publishedAll
1.44 +@released
1.45 +
1.46 +Abstract class representing a data sink.
1.47 +*/
1.48 +class MDataSink
1.49 + {
1.50 +public:
1.51 +
1.52 + static inline MDataSink* NewSinkL( TUid aImplementationUid, const TDesC8& aInitData ) ;
1.53 +
1.54 + /**
1.55 + Destructor.
1.56 + */
1.57 + virtual ~MDataSink() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
1.58 +
1.59 + /**
1.60 + Returns the UID identifying the type of data sink.
1.61 +
1.62 + @return The UID identifying the type of data sink
1.63 + */
1.64 + virtual TUid DataSinkType() const {return iDataSinkType;};
1.65 +
1.66 + /**
1.67 + Returns the data type as a fourCC code of the data sink.
1.68 +
1.69 + This is a pure virtual function that each derrived class must implement.
1.70 +
1.71 + @param aMediaId
1.72 + This identifies the type of media eg. audio or video and the stream ID.
1.73 + This parameter is required in cases where the sink can accept data
1.74 + of more than one media type and/or multiple streams of data.
1.75 +
1.76 + @return The fourCC code identifying the sink datatype for the specified aMediaId.
1.77 + */
1.78 + virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
1.79 +
1.80 + inline virtual TInt SetSinkDataTypeCode(TFourCC aSinkFourCC, TMediaId aMediaId);
1.81 +
1.82 + /**
1.83 + Method called by a MDataSource to request the data sink to empty aBuffer of data.
1.84 +
1.85 + This is a pure virtual function that each derived class must implement.
1.86 + This method is used when a data sink is passively waiting for requests from a supplier ie.
1.87 + a data source to empty a buffer. The data sink must call the BufferEmptiedL member on aSupplier
1.88 + when it has emptied the buffer of it's data. The data sink can either make this callback
1.89 + synchronously or asynchronously.
1.90 +
1.91 + @param aBuffer
1.92 + The full buffer that needs emptying of it's data.
1.93 + @param aSupplier
1.94 + The data source that supplied the data. The data sink needs this to make the
1.95 + BufferEmptiedL callback on aSupplier to indicate to the data source that the data sink
1.96 + has finished with the buffer.
1.97 + @param aMediaId
1.98 + This identifies the type of media eg. audio or video and the stream ID.
1.99 + This parameter is required in cases where the source can supply data
1.100 + of more than one media type and/or multiple streams of data.
1.101 + */
1.102 + virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
1.103 +
1.104 + /**
1.105 + Function called by a data source to pass back a filled buffer to the sink.
1.106 +
1.107 + This is a pure virtual function that each derived class must implement.
1.108 + This method is used as the callback when the data sink actively requests a supplier ie. a
1.109 + data source to fill a buffer by calling the data sources FillBufferL. When the data sink gets
1.110 + this callback it knows that the buffer has been filled and is ready to be emptied.
1.111 +
1.112 + @param aBuffer
1.113 + The buffer that has been filled by a data source and is now available for processing.
1.114 + */
1.115 + virtual void BufferFilledL(CMMFBuffer* aBuffer)=0;
1.116 +
1.117 + /**
1.118 + @deprecated
1.119 +
1.120 + Function to indicate whether the data sink can create a buffer.
1.121 +
1.122 + This is a pure virtual function that each derived class must implement.
1.123 +
1.124 + @return A boolean indicating if the data sink can create a buffer. ETrue if it can otherwise
1.125 + EFalse.
1.126 + */
1.127 + virtual TBool CanCreateSinkBuffer()=0;
1.128 +
1.129 + /**
1.130 + Returns a buffer created by the data sink.
1.131 +
1.132 + This is a pure virtual function that each derived class must implement.
1.133 +
1.134 + @param aMediaId
1.135 + This identifies the type of media eg. audio or video and the stream ID.
1.136 + This parameter is required in cases where the source can supply data
1.137 + of more than one media type and/or multiple streams of data.
1.138 +
1.139 + @param aReference
1.140 + This must be written to by the method to indicate whether the created buffer is
1.141 + a 'reference' buffer. A 'reference' buffer is a buffer that is owned by the sink
1.142 + and should be used in preference to the source buffer provided the source buffer
1.143 + is also not a reference buffer.
1.144 +
1.145 + @return The created buffer.
1.146 + */
1.147 + virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
1.148 +
1.149 + inline virtual TInt SinkThreadLogon(MAsyncEventHandler& aEventHandler);
1.150 +
1.151 + /**
1.152 + Function to 'logoff' the data sink from the same thread that sink consumes data in.
1.153 +
1.154 + This method may be required as the thread that the data sink is deleted in may not be
1.155 + the same thread that the data transfer took place in. Therefore any thread specific
1.156 + releasing of resources needs to be performed in the SinkThreadLogoff rather than in the
1.157 + destructor.
1.158 +
1.159 + This is a virtual function that a derrived data sink can implement if any thread specific
1.160 + releasing of resources is required.
1.161 + */
1.162 + virtual void SinkThreadLogoff() {};
1.163 +
1.164 + inline virtual void NegotiateL(MDataSource& aDataSource);
1.165 +
1.166 + /**
1.167 + Function to 'prime' the data sink.
1.168 +
1.169 + This is a virtual function that a derrived data sink can implement if
1.170 + any data sink specific 'priming' is required.
1.171 + */
1.172 + virtual void SinkPrimeL() {};
1.173 +
1.174 + /**
1.175 + Function 'play' the data sink.
1.176 +
1.177 + This is a virtual function that a derrived data sink can implement if
1.178 + any data sink specific action is required prior to 'playing' ie. the start of data transfer.
1.179 + */
1.180 + virtual void SinkPlayL() {};
1.181 +
1.182 + /**
1.183 + Function to 'pause' the data sink.
1.184 +
1.185 + This is a virtual function that a derrived data sink can implement if
1.186 + any data sink specific action is required to 'pause'.
1.187 + */
1.188 + virtual void SinkPauseL() {};
1.189 +
1.190 + /**
1.191 + Function to 'stop' the data sink.
1.192 +
1.193 + This is a virtual function that a derrived data sink can implement if
1.194 + any data sink specific action is required to 'stop'
1.195 + */
1.196 + virtual void SinkStopL() {};
1.197 +
1.198 + inline virtual void SetSinkPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
1.199 +
1.200 + /**
1.201 + Calls a sink specific custom command.
1.202 +
1.203 + This is a virtual function that a derrived data sink can implement if
1.204 + it implements any custom commands.
1.205 +
1.206 + @param aMessage
1.207 + The message specifying the custom command.
1.208 + */
1.209 + virtual void SinkCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};
1.210 +
1.211 +protected:
1.212 + /**
1.213 + Performs any sink construction dependant on the sink construction
1.214 + initialisation data aInitData.
1.215 +
1.216 + This is a pure virtual function that a derrived data sink must implement
1.217 +
1.218 + @param aInitData
1.219 + The sink specific initialisation data required for sink construction.
1.220 + */
1.221 + virtual void ConstructSinkL( const TDesC8& aInitData ) = 0;
1.222 +
1.223 + /**
1.224 + Protected constructor.
1.225 +
1.226 + @param aType
1.227 + The source type UID.
1.228 + */
1.229 + MDataSink(TUid aType): iDataSinkType(aType) {}
1.230 +
1.231 +private:
1.232 + TUid iDataSinkType;
1.233 + TUid iDtor_ID_Key;
1.234 + };
1.235 +
1.236 +/**
1.237 +Instantiates a new data sink.
1.238 +
1.239 +@param aImplementationUid
1.240 + The UID identifying the data sink to be instantiated.
1.241 +@param aInitData
1.242 + The sink specific initialisation data required for sink construction.
1.243 +
1.244 +@return A pointer to the instantiated data sink.
1.245 +*/
1.246 +inline MDataSink* MDataSink::NewSinkL( TUid aImplementationUid, const TDesC8& aInitData )
1.247 + {
1.248 + MDataSink* retPtr = REINTERPRET_CAST( MDataSink*, REComSession::CreateImplementationL( aImplementationUid,
1.249 + _FOFF(MDataSink, iDtor_ID_Key) ) ) ;
1.250 + CleanupDeletePushL(retPtr);
1.251 + retPtr->ConstructSinkL( aInitData ) ;
1.252 +
1.253 + CleanupStack::Pop(retPtr);
1.254 + return retPtr ;
1.255 + }
1.256 +
1.257 +/**
1.258 +Sets the data type as a fourCC code for the data sink.
1.259 +
1.260 +This is a virtual function that each derived class can implement if the data sink supports
1.261 +the ability to have its data type set.
1.262 +
1.263 +@param aSinkFourCC
1.264 + This specifies the data type as a fourCC code to set the sink to.
1.265 +@param aMediaId
1.266 + This identifies the type of media eg. audio or video and the stream ID.
1.267 + This parameter is required in cases where the source can supply data
1.268 + of more than one media type and/or multiple streams of data.
1.269 +
1.270 +@return KErrNone if successful, KErrNotSupported if the sink does not support having
1.271 + it's data type set, otherwise a system wide error code.
1.272 +*/
1.273 +inline TInt MDataSink::SetSinkDataTypeCode(TFourCC /*aSinkFourCC*/, TMediaId /*aMediaId*/)
1.274 +{
1.275 + return KErrNotSupported;
1.276 +}
1.277 +
1.278 +/**
1.279 +Function to 'logon' the data sink to the same thread that sink will be consuming data in.
1.280 +
1.281 +This method may be required as the thread that the data sink was created in is not always
1.282 +the same thread that the data transfer will take place in. Therefore any thread specific
1.283 +initialisation needs to be performed in the SinkThreadLogon rather than in the creation
1.284 +of the data sink.
1.285 +
1.286 +This is a virtual function that a derrived data sink can implement if any thread specific
1.287 +initialisation is required and/or the data sink can create any asynchronous events.
1.288 +
1.289 +@param aEventHandler
1.290 + This is an MAsyncEventHandler to handle asynchronous events that occur during the
1.291 + transfer of multimedia data. The event handler must be in the same thread as the data
1.292 + transfer thread - hence the reason it is passed in the SinkThreadLogon as opposed to
1.293 + say the constructor.
1.294 +
1.295 +@return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.296 + another of the system-wide error codes.
1.297 +*/
1.298 +inline TInt MDataSink::SinkThreadLogon(MAsyncEventHandler& /*aEventHandler*/)
1.299 +{
1.300 + return KErrNone;
1.301 +}
1.302 +
1.303 +/**
1.304 +@deprecated
1.305 +
1.306 +Allows the data sink to negotiate with a data source.
1.307 +
1.308 +This method is required in cases where the settings of data sink are dependant on those of a
1.309 +data source. This is a virtual function that a derrived data sink can implement.
1.310 +
1.311 +@param aDataSource
1.312 + The data source whose settings can affect the data sink.
1.313 +*/
1.314 +inline void MDataSink::NegotiateL(MDataSource& /*aDataSource*/)
1.315 +{
1.316 +}
1.317 +
1.318 +/**
1.319 +Sets the sink priority settings.
1.320 +
1.321 +This is a virtual function that a derrived data sink can implement if
1.322 +a priority mechanism is required to arbitrate between multiple clients
1.323 +trying to access the same resource.
1.324 +
1.325 +@param aPrioritySettings
1.326 + The sink priority settings.
1.327 +
1.328 +@capability MultimediaDD
1.329 + A process requesting or using this method that has MultimediaDD capability will
1.330 + always have precedence over a process that does not have MultimediaDD.
1.331 +*/
1.332 +inline void MDataSink::SetSinkPrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)
1.333 +{
1.334 +}
1.335 +
1.336 +/**
1.337 +This function is used by TCleanupItem objects to perform
1.338 +a SinkStopL() when leaving functions exist, ususally between SinkPrimeL-SinkStopL pairs.
1.339 +
1.340 +@param aSink
1.341 + The data sink to be stopped.
1.342 +*/
1.343 +inline static void DoDataSinkStop(TAny* aSink)
1.344 + {
1.345 + MDataSink* sink = STATIC_CAST(MDataSink*, aSink);
1.346 + // we don't want this function to leave because no leaving functions are supposed
1.347 + // to be used as argument to the TCleanupItem objects. Hence we catch the error but
1.348 + // we do nothing with it.
1.349 + TRAP_IGNORE(sink->SinkStopL());
1.350 + }
1.351 +
1.352 +/**
1.353 +This method is used by TCleanupItem objects to perform a SinkThreadLogoff().
1.354 +
1.355 +@param aSink
1.356 + The data sink to be logged off.
1.357 +*/
1.358 +inline static void DoDataSinkThreadLogoff(TAny* aSink)
1.359 + {
1.360 + MDataSink* sink = STATIC_CAST(MDataSink*, aSink);
1.361 + sink->SinkThreadLogoff();
1.362 + }
1.363 +
1.364 +
1.365 +#endif