1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmlibs/mmfw/inc/mmf/server/mmfdatasource.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,410 @@
1.4 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// include\mmf\Server\mmfdatasource.h
1.18 +//
1.19 +//
1.20 +
1.21 +#ifndef __MMF_SERVER_DATASOURCE_H__
1.22 +#define __MMF_SERVER_DATASOURCE_H__
1.23 +
1.24 +#include <e32base.h>
1.25 +#include <mmf/server/mmfdatasourcesink.hrh>
1.26 +#include <mmf/common/mmfutilities.h>
1.27 +#include <ecom/ecom.h>
1.28 +#include <mmf/common/mmfbase.h>
1.29 +#include <mmf/common/mmfcontrollerframework.h>
1.30 +
1.31 +//
1.32 +// MDataSource mixim
1.33 +//
1.34 +
1.35 +class CMMFBuffer;
1.36 +class MDataSink;
1.37 +class MAsyncEventHandler;
1.38 +
1.39 +/**
1.40 +@publishedAll
1.41 +@released
1.42 +
1.43 +Abstract class representing a data source.
1.44 +*/
1.45 +class MDataSource
1.46 + {
1.47 +public:
1.48 + static inline MDataSource* NewSourceL( TUid aImplementationUid, const TDesC8& aInitData ) ;
1.49 +
1.50 + /**
1.51 + Destructor.
1.52 + */
1.53 + virtual ~MDataSource() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
1.54 +
1.55 + /**
1.56 + Returns the UID identifying the type of data source.
1.57 +
1.58 + @return The UID identifying the type of data source.
1.59 + */
1.60 + virtual TUid DataSourceType() const {return iDataSourceType;};
1.61 +
1.62 + /**
1.63 + Returns the data type as a fourCC code of the data source.
1.64 +
1.65 + This is a pure virtual function that each derrived class must implement.
1.66 +
1.67 + @param aMediaId
1.68 + This identifies the type of media eg. audio or video and the stream ID.
1.69 + This parameter is required in cases where the source can supply data
1.70 + of more than one media type and/or multiple streams of data.
1.71 +
1.72 + @return The fourCC code identifying the source datatype for the specified aMediaId.
1.73 + */
1.74 + virtual TFourCC SourceDataTypeCode(TMediaId aMediaId) = 0;
1.75 +
1.76 + inline virtual TInt SetSourceDataTypeCode(TFourCC aSourceFourCC, TMediaId aMediaId);
1.77 +
1.78 + /**
1.79 + Function called by a MDataSink to request the data source to fill aBuffer with data.
1.80 +
1.81 + This is a pure virtual function that each derived class must implement.
1.82 + This method is used when a data source is passively waiting for requests from a consumer ie. a data sink
1.83 + to fill a buffer. The data source must call the BufferFilledL member on aConsumer when it has filled
1.84 + the buffer with data. The data source can either make this callback synchronously or asynchronously.
1.85 +
1.86 + The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
1.87 + function. From this, the format should be able to determine the actual position of the data on
1.88 + the data source. The technique here depends on the nature of the format. For a linear audio
1.89 + format, the position can be obtained by a simple calculation of the frame size, the header size
1.90 + and where appropriate the datatype.
1.91 +
1.92 + For non-linear formats, either an index table of frame number and location will need to be
1.93 + created in the NewL() or some form of approximating algorithm will be required. Some formats
1.94 + have an index table as part of the format eg. AVI. If no random access is required then no index
1.95 + table is required, the format can keep track of the current read position and increment it on
1.96 + each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear
1.97 + ie. variable bit rate formats, the size of the data read may vary from frame to frame, then the
1.98 + format should either set the request size of the buffer for the required frame or call the
1.99 + source's ReadBufferL() (either CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or
1.100 + CMMFFile::ReadBufferL()) function that takes the aLength parameter.
1.101 +
1.102 + It is the responsibility of the format decode to determine the size and position of the source
1.103 + data for each frame. For linear audio formats, the format decode should fill the buffer up to
1.104 + its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively
1.105 + acting as a demultiplexor, and must obtain the appropriate data from the source depending on
1.106 + the aMediaId.
1.107 +
1.108 + @param aBuffer
1.109 + The buffer that needs filling with data.
1.110 + @param aConsumer
1.111 + The data sink that consumes the data. The data source needs this to make the BufferFilledL
1.112 + callback on aConsumer when the data source has completed filling the aBuffer.
1.113 + @param aMediaId
1.114 + This identifies the type of media eg. audio or video and the stream ID.
1.115 + This parameter is required in cases where the source can supply data
1.116 + of more than one media type and/or multiple strams of data eg. a multimedia file.
1.117 + */
1.118 + virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer,TMediaId aMediaId)=0;
1.119 +
1.120 + /**
1.121 + Function called by a data sink to pass back an emptied buffer to the source.
1.122 +
1.123 + This is a pure virtual function that each derived class must implement.
1.124 + This method is used as the callback when the data source actively requests a consumer ie. a data
1.125 + sink to empty a buffer by calling the data sinks EmptyBufferL.
1.126 + When the data source gets this callback it knows that the buffer has been emptied and can be
1.127 + reused.
1.128 +
1.129 + @param aBuffer
1.130 + The buffer that has been emptied by a data sink and is now available for reuse.
1.131 + */
1.132 + virtual void BufferEmptiedL(CMMFBuffer* aBuffer)=0;
1.133 +
1.134 + /**
1.135 + @deprecated
1.136 +
1.137 + Function to indicate whether the data source can create a buffer.
1.138 +
1.139 + This is a pure virtual function that each derived class must implement.
1.140 +
1.141 + @return A boolean indicating if the data source can create a buffer. ETrue if it can otherwise
1.142 + EFalse.
1.143 + */
1.144 + virtual TBool CanCreateSourceBuffer()=0;
1.145 +
1.146 + /**
1.147 + @deprecated
1.148 +
1.149 + Returns a buffer created by the data source
1.150 +
1.151 + This is a pure virtual function that each derived class must implement.
1.152 +
1.153 + @param aMediaId
1.154 + This identifies the type of media eg. audio or video and the stream ID.
1.155 + This parameter is required in cases where the source can supply data
1.156 + of more than one media type and/or multiple strams of data eg a multimedia file.
1.157 + @param aReference
1.158 + This must be written to by the method to indicate whether the created buffer is
1.159 + a 'reference' buffer. A 'reference' buffer is a buffer that is owned by the source
1.160 + and should be used in preference to the sink buffer provided the sink buffer
1.161 + is also not a reference buffer.
1.162 +
1.163 + @return A pointer to the created buffer.
1.164 + */
1.165 + virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference) = 0;
1.166 +
1.167 + inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& aSinkBuffer, TBool &aReference);
1.168 +
1.169 + inline virtual TInt SourceThreadLogon(MAsyncEventHandler& aEventHandler);
1.170 +
1.171 + /**
1.172 + Function to 'logoff' the data source from the same thread that source supplies data in.
1.173 +
1.174 + This method may be required as the thread that the data source is deleted in may not be
1.175 + the same thread that the data transfer took place in. Therefore any thread specific
1.176 + releasing of resources needs to be performed in the SourceThreadLogoff rather than in the
1.177 + destructor.
1.178 +
1.179 + This is a virtual function that a derrived data source can implement if any thread specific
1.180 + releasing of resources is required.
1.181 + */
1.182 + virtual void SourceThreadLogoff() {};
1.183 +
1.184 + inline virtual void NegotiateSourceL(MDataSink& aDataSink); //called if source setup depends on sink
1.185 +
1.186 + /**
1.187 + Indicates whether the data source supports sample rate conversion.
1.188 +
1.189 + This is a virtual function that a derived class can implement.
1.190 +
1.191 + @return A boolean indicating if the data source can perform a sample rate conversion. ETrue if
1.192 + it can otherwise EFalse.
1.193 + */
1.194 + virtual TBool SourceSampleConvert() {return EFalse;};
1.195 +
1.196 + /**
1.197 + Function to 'prime' the data source.
1.198 +
1.199 + This is a virtual function that a derrived data source can implement if
1.200 + any data source specific 'priming' is required.
1.201 + */
1.202 + virtual void SourcePrimeL() {};
1.203 +
1.204 + /**
1.205 + Function to 'play' the data source.
1.206 +
1.207 + This is a virtual function that a derrived data source can implement if
1.208 + any data source specific action is required prior to 'playing' ie. the start of data transfer.
1.209 + */
1.210 + virtual void SourcePlayL() {};
1.211 +
1.212 + /**
1.213 + Function to 'pause' the data source.
1.214 +
1.215 + This is a virtual function that a derrived data source can implement if
1.216 + any data source specific action is required to 'pause'
1.217 + */
1.218 + virtual void SourcePauseL() {};
1.219 +
1.220 + /**
1.221 + Function to 'stop' the data source.
1.222 +
1.223 + This is a virtual function that a derrived data source can implement if
1.224 + any data source specific action is required to 'stop'.
1.225 + */
1.226 + virtual void SourceStopL() {};
1.227 +
1.228 + inline virtual void SetSourcePrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
1.229 +
1.230 + /**
1.231 + Function to call a source specific custom command.
1.232 +
1.233 + This is a virtual function that a derrived data source can implement if
1.234 + it implements any custom commands.
1.235 +
1.236 + @param aMessage
1.237 + The message specifying the custom command.
1.238 + */
1.239 + virtual void SourceCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};
1.240 +protected:
1.241 +
1.242 + /**
1.243 + Performs any source construction dependant on the source construction
1.244 + initialisation data aInitData.
1.245 +
1.246 + This is a pure virtual function that a derrived data source must implement
1.247 +
1.248 + @param aInitData
1.249 + The source specific initialisation data required for source construction.
1.250 + */
1.251 + virtual void ConstructSourceL( const TDesC8& aInitData ) = 0 ;
1.252 +
1.253 + /**
1.254 + Protected constructor.
1.255 + */
1.256 + MDataSource(TUid aType): iDataSourceType(aType) {}
1.257 +private:
1.258 + TUid iDataSourceType;
1.259 + TUid iDtor_ID_Key;
1.260 +
1.261 + };
1.262 +
1.263 +/**
1.264 +Instantiates a data source.
1.265 +
1.266 +@param aImplementationUid
1.267 + The UID identifying the data source to be instantiated.
1.268 +@param aInitData
1.269 + The source specific initialisation data required for source construction.
1.270 +
1.271 +@return The instantiated data source.
1.272 +*/
1.273 +inline MDataSource* MDataSource::NewSourceL( TUid aImplementationUid, const TDesC8& aInitData )
1.274 + {
1.275 + MDataSource* retPtr = REINTERPRET_CAST( MDataSource*, REComSession::CreateImplementationL( aImplementationUid,
1.276 + _FOFF(MDataSource, iDtor_ID_Key) ) ) ;
1.277 + CleanupDeletePushL(retPtr);
1.278 + retPtr->ConstructSourceL( aInitData ) ;
1.279 +
1.280 + CleanupStack::Pop(retPtr);
1.281 + return retPtr ;
1.282 + }
1.283 +
1.284 +/**
1.285 +Sets the data type as a fourCC code for the data source.
1.286 +
1.287 +This is a virtual function that each derived class can implement if the data source supports
1.288 +the ability to have its data type set.
1.289 +
1.290 +@param aSourceFourCC
1.291 + This specifies the data type as a fourCC code to set the source to.
1.292 +@param aMediaId
1.293 + This identifies the type of media eg. audio or video and the stream ID.
1.294 + This parameter is required in cases where the source can supply data
1.295 + of more than one media type and/or multiple strams of data eg a multimedia file.
1.296 +
1.297 +@return KErrNone if successful, KErrNotSupported if the source does not support having
1.298 + it's data type set, otherwise a system wide error code.
1.299 +*/
1.300 +inline TInt MDataSource::SetSourceDataTypeCode(TFourCC /*aSourceFourCC*/, TMediaId /*aMediaId*/)
1.301 +{
1.302 + return KErrNotSupported;
1.303 +}
1.304 +
1.305 +/**
1.306 +@deprecated
1.307 +
1.308 +Returns a buffer created by the data source.
1.309 +
1.310 +This is a virtual function that a derived class can implement.
1.311 +This can be used in preference to the above CreateSourceBufferL method in cases where
1.312 +the source buffer creation has a dependancy on the sink buffer.
1.313 +
1.314 +@param aMediaId
1.315 + This identifies the type of media eg. audio or video and the stream ID.
1.316 + This parameter is required in cases where the source can supply data
1.317 + of more than one media type and/or multiple strams of data eg a multimedia file
1.318 +@param aSinkBuffer
1.319 + The sink buffer the nature of which may influence the creation of the source buffer.
1.320 +@param aReference
1.321 + This must be written to by the method to indicate whether the created buffer is
1.322 + a 'reference' buffer. A 'reference' buffer is a buffer that is owned by the source
1.323 + and should be used in preference to the sink buffer provided the sink buffer is not a
1.324 + reference buffer.
1.325 +
1.326 +@return A pointer to the created buffer.
1.327 +*/
1.328 +inline CMMFBuffer* MDataSource::CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& /*aSinkBuffer*/, TBool &aReference)
1.329 +{
1.330 + return CreateSourceBufferL(aMediaId, aReference);
1.331 +}
1.332 +
1.333 +/**
1.334 +Function to 'logon' the data source to the same thread that source will be supplying data in.
1.335 +
1.336 +This method may be required as the thread that the data source was created in is not always
1.337 +the same thread that the data transfer will take place in. Therefore any thread specific
1.338 +initialisation needs to be performed in the SourceThreadLogon rather than in the creation
1.339 +of the data source.
1.340 +
1.341 +This is a virtual function that a derrived data source can implement if any thread specific
1.342 +initialisation is required and/or the data source can create any asynchronous events.
1.343 +
1.344 +@param aEventHandler
1.345 + This is an MAsyncEventHandler to handle asynchronous events that occur during the
1.346 + transfer of multimedia data. The event handler must be in the same thread as the data transfer
1.347 + thread. Hence the reason it is passed in the SourceThreadLogon as opposed to say the constructor.
1.348 +
1.349 +@return An error code indicating if the function call was successful. KErrNone on success, otherwise
1.350 + another of the system-wide error codes.
1.351 +*/
1.352 +inline TInt MDataSource::SourceThreadLogon(MAsyncEventHandler& /*aEventHandler*/)
1.353 +{
1.354 + return KErrNone;
1.355 +}
1.356 +
1.357 +/**
1.358 +Function to allow the data source to negotiate with a data sink
1.359 +
1.360 +This method is required in cases where the settings of data source are dependant on those of a
1.361 +data sink. This is a virtual function that a derrived data source can implement.
1.362 +
1.363 +@param aDataSink
1.364 + The data sink whose settings can affect the data source.
1.365 +*/
1.366 +inline void MDataSource::NegotiateSourceL(MDataSink& /*aDataSink*/)
1.367 +{
1.368 +}
1.369 +
1.370 +/**
1.371 +Function to set the source priority settings.
1.372 +
1.373 +This is a virtual function that a derrived data source can implement if
1.374 +a priority mechanism is required to arbitrate between multiple clients
1.375 +trying to access the same resource.
1.376 +
1.377 +@param aPrioritySettings
1.378 + The source priority settings.
1.379 +
1.380 +*/
1.381 +inline void MDataSource::SetSourcePrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)
1.382 +{
1.383 +}
1.384 +
1.385 +/**
1.386 +This function is used by TCleanupItem objects to perform
1.387 +a SourceStopL() when leaving functions exist, ususally between SourcePrimeL-SourceStopL pairs.
1.388 +
1.389 +@param aSource
1.390 + The data source to be stopped.
1.391 +*/
1.392 +inline static void DoDataSourceStop(TAny* aSource)
1.393 + {
1.394 + MDataSource* source = STATIC_CAST(MDataSource*, aSource);
1.395 + // we don't want this function to leave because no leaving functions are supposed
1.396 + // to be used as argument to the TCleanupItem objects. Hence we catch the error but
1.397 + // we do nothing with it.
1.398 + TRAP_IGNORE(source->SourceStopL());
1.399 + }
1.400 +
1.401 +/**
1.402 +This method is used by TCleanupItem objects to perform a SourceThreadLogoff().
1.403 +
1.404 +@param aSource
1.405 + The data source to be logged off.
1.406 +*/
1.407 +inline static void DoDataSourceThreadLogoff(TAny* aSource)
1.408 + {
1.409 + MDataSource* source = STATIC_CAST(MDataSource*, aSource);
1.410 + source->SourceThreadLogoff();
1.411 + }
1.412 +
1.413 +#endif