epoc32/include/mmf/server/mmfdatasource.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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 "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // include\mmf\Server\mmfdatasource.h
    15 // 
    16 //
    17 
    18 #ifndef __MMF_SERVER_DATASOURCE_H__
    19 #define __MMF_SERVER_DATASOURCE_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 // MDataSource mixim
    30 //
    31 
    32 class CMMFBuffer;
    33 class MDataSink;
    34 class MAsyncEventHandler;
    35 
    36 /**
    37 @publishedAll
    38 @released
    39 
    40 Abstract class representing a data source.
    41 */
    42 class MDataSource
    43 	{
    44 public:
    45 	static inline MDataSource* NewSourceL( TUid aImplementationUid,  const TDesC8& aInitData ) ;
    46 
    47 	/**
    48 	Destructor.
    49 	*/
    50 	virtual ~MDataSource() {REComSession::DestroyedImplementation(iDtor_ID_Key);};
    51 
    52 	/**
    53 	Returns the UID identifying the type of data source.
    54 
    55 	@return	The UID identifying the type of data source.
    56 	*/
    57 	virtual TUid DataSourceType() const {return iDataSourceType;};
    58 
    59 	/**
    60 	Returns the data type as a fourCC code of the data source.
    61 
    62 	This is a pure virtual function that each derrived class must implement.
    63 
    64 	@param  aMediaId
    65 	        This identifies the type of media eg. audio or video and the stream ID.
    66 	        This parameter is required in cases where the source can supply data
    67 	        of more than one media type and/or multiple streams of data.
    68 
    69 	@return The fourCC code identifying the source datatype for the specified aMediaId.
    70 	*/
    71 	virtual TFourCC SourceDataTypeCode(TMediaId aMediaId) = 0;
    72 
    73 	inline virtual TInt SetSourceDataTypeCode(TFourCC aSourceFourCC, TMediaId aMediaId);
    74 
    75 	/**
    76 	Function called by a MDataSink to request the data source to fill aBuffer with data.
    77 
    78 	This is a pure virtual function that each derived class must implement.
    79 	This method is used when a data source is passively waiting for requests from a consumer ie. a data sink
    80 	to fill a buffer. The data source must call the BufferFilledL member on aConsumer when it has filled
    81 	the buffer with data. The data source can either make this callback synchronously or asynchronously.
    82 
    83 	The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
    84 	function. From this, the format should be able to determine the actual position of the data on
    85 	the data source. The technique here depends on the nature of the format. For a linear audio
    86 	format, the position can be obtained by a simple calculation of the frame size, the header size
    87 	and where appropriate the datatype.
    88 
    89 	For non-linear formats, either an index table of frame number and location will need to be
    90 	created in the NewL() or some form of approximating algorithm will be required. Some formats
    91 	have an index table as part of the format eg. AVI. If no random access is required then no index
    92 	table is required, the format can keep track of the current read position and increment it on
    93 	each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear
    94 	ie. variable bit rate formats, the size of the data read may vary from frame to frame, then the
    95 	format should either set the request size of the buffer for the required frame or call the
    96 	source's ReadBufferL() (either CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or
    97 	CMMFFile::ReadBufferL()) function that takes the aLength parameter.
    98 
    99 	It is the responsibility of the format decode to determine the size and position of the source
   100 	data for each frame. For linear audio formats, the format decode should fill the buffer up to
   101 	its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively
   102 	acting as a demultiplexor, and must obtain the appropriate data from the source depending on
   103 	the aMediaId.
   104 
   105 	@param  aBuffer
   106 	        The buffer that needs filling with data.
   107 	@param  aConsumer
   108 	        The data sink that consumes the data. The data source needs this to make the BufferFilledL
   109 	        callback on aConsumer when the data source has completed filling the aBuffer.
   110 	@param  aMediaId
   111 	        This identifies the type of media eg. audio or video and the stream ID.
   112 	        This parameter is required in cases where the source can supply data
   113 	        of more than one media type and/or multiple strams of data eg. a multimedia file.
   114 	*/
   115 	virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer,TMediaId aMediaId)=0;
   116 
   117 	/**
   118 	Function called by a data sink to pass back an emptied buffer to the source.
   119 
   120 	This is a pure virtual function that each derived class must implement.
   121 	This method is used as the callback when the data source actively requests a consumer ie. a data
   122 	sink to empty a buffer by calling the data sinks EmptyBufferL.
   123 	When the data source gets this callback it knows that the buffer has been emptied and can be
   124 	reused.
   125 
   126 	@param  aBuffer
   127 	        The buffer that has been emptied by a data sink and is now available for reuse.
   128 	*/
   129 	virtual void BufferEmptiedL(CMMFBuffer* aBuffer)=0;
   130 
   131 	/**
   132 	@deprecated
   133 
   134 	Function to indicate whether the data source can create a buffer.
   135 
   136 	This is a pure virtual function that each derived class must implement.
   137 
   138 	@return	A boolean indicating if the data source can create a buffer. ETrue if it can otherwise
   139 	        EFalse.
   140 	*/
   141 	virtual TBool CanCreateSourceBuffer()=0;
   142 
   143 	/**
   144 	@deprecated
   145 
   146 	Returns a buffer created by the data source
   147 
   148 	This is a pure virtual function that each derived class must implement.
   149 
   150 	@param	aMediaId
   151 	        This identifies the type of media eg. audio or video and the stream ID.
   152 	        This parameter is required in cases where the source can supply data
   153 	        of more than one media type and/or multiple strams of data eg a multimedia file.
   154 	@param  aReference
   155 	        This must be written to by the method to indicate whether the created buffer is
   156 	        a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the source
   157 	        and should be used in preference to the sink buffer provided the sink buffer
   158 	        is also not a reference buffer.
   159 
   160 	@return	A pointer to the created buffer.
   161 	*/
   162 	virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference) = 0;
   163 
   164 	inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& aSinkBuffer, TBool &aReference);
   165 
   166 	inline virtual TInt SourceThreadLogon(MAsyncEventHandler& aEventHandler);
   167 
   168 	/**
   169 	Function to 'logoff' the data source from the same thread that source supplies data in.
   170 
   171 	This method may be required as the thread that the data source is deleted in may not be
   172 	the same thread that the data transfer took place in.  Therefore any thread specific
   173 	releasing of resources needs to be performed in the SourceThreadLogoff rather than in the
   174 	destructor.
   175 
   176 	This is a virtual function that a derrived data source can implement if any thread specific
   177 	releasing of resources is required.
   178 	*/
   179 	virtual void SourceThreadLogoff() {};
   180 
   181 	inline virtual void NegotiateSourceL(MDataSink& aDataSink); //called if source setup depends on sink
   182 
   183 	/**
   184 	Indicates whether the data source supports sample rate conversion.
   185 
   186 	This is a virtual function that a derived class can implement.
   187 
   188 	@return	A boolean indicating if the data source can perform a sample rate conversion. ETrue if 
   189 	        it can otherwise EFalse.
   190 	*/
   191 	virtual TBool SourceSampleConvert() {return EFalse;};
   192 	
   193 	/**
   194 	Function to 'prime' the data source.
   195 	
   196 	This is a virtual function that a derrived data source can implement if
   197 	any data source specific 'priming' is required.
   198 	*/
   199 	virtual void SourcePrimeL() {};
   200 	
   201 	/**
   202 	Function to 'play' the data source.
   203 
   204 	This is a virtual function that a derrived data source can implement if
   205 	any data source specific action is required prior to 'playing' ie. the start of data transfer.
   206 	*/
   207 	virtual void SourcePlayL() {};
   208 
   209 	/**
   210 	Function to 'pause' the data source.
   211 
   212 	This is a virtual function that a derrived data source can implement if
   213 	any data source specific action is required to 'pause'
   214 	*/
   215 	virtual void SourcePauseL() {};
   216 
   217 	/**
   218 	Function to 'stop' the data source.
   219 
   220 	This is a virtual function that a derrived data source can implement if
   221 	any data source specific action is required to 'stop'.
   222 	*/
   223 	virtual void SourceStopL() {};
   224 
   225 	inline virtual void SetSourcePrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
   226 
   227 	/**
   228 	Function to call a source specific custom command.
   229 
   230 	This is a virtual function that a derrived data source can implement if
   231 	it implements any custom commands.
   232 
   233 	@param  aMessage
   234 	        The message specifying the custom command.
   235 	*/
   236 	virtual void SourceCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);};
   237 protected:
   238 
   239 	/**
   240 	Performs any source construction dependant on the source construction
   241 	initialisation data aInitData.
   242 
   243 	This is a pure virtual function that a derrived data source must implement
   244 
   245 	@param  aInitData
   246 	        The source specific initialisation data required for source construction.
   247 	*/
   248 	virtual void ConstructSourceL(  const TDesC8& aInitData ) = 0 ;
   249 
   250 	/**
   251 	Protected constructor.
   252 	*/
   253 	MDataSource(TUid aType): iDataSourceType(aType) {}
   254 private:
   255 	TUid iDataSourceType;
   256 	TUid iDtor_ID_Key;
   257 
   258 	};
   259 
   260 /**
   261 Instantiates a data source.
   262 
   263 @param  aImplementationUid
   264         The UID identifying the data source to be instantiated.
   265 @param  aInitData
   266         The source specific initialisation data required for source construction.
   267 
   268 @return	The instantiated data source.
   269 */
   270 inline MDataSource* MDataSource::NewSourceL( TUid aImplementationUid, const TDesC8& aInitData )
   271 	{
   272 	MDataSource* retPtr = REINTERPRET_CAST( MDataSource*, REComSession::CreateImplementationL( aImplementationUid,
   273 																			_FOFF(MDataSource, iDtor_ID_Key) ) ) ;
   274 	CleanupDeletePushL(retPtr);
   275 	retPtr->ConstructSourceL( aInitData ) ;
   276 
   277 	CleanupStack::Pop(retPtr);
   278 	return retPtr ;
   279 	}
   280 
   281 /**
   282 Sets the data type as a fourCC code for the data source.
   283 
   284 This is a virtual function that each derived class can implement if the data source supports
   285 the ability to have its data type set.
   286 
   287 @param  aSourceFourCC
   288         This specifies the data type as a fourCC code to set the source to.
   289 @param  aMediaId
   290         This identifies the type of media eg. audio or video and the stream ID.
   291         This parameter is required in cases where the source can supply data
   292         of more than one media type and/or multiple strams of data eg a multimedia file.
   293 
   294 @return	KErrNone if successful, KErrNotSupported if the source does not support having
   295         it's data type set, otherwise a system wide error code.
   296 */
   297 inline TInt MDataSource::SetSourceDataTypeCode(TFourCC /*aSourceFourCC*/, TMediaId /*aMediaId*/)
   298 {
   299 	return KErrNotSupported;
   300 }
   301 
   302 /**
   303 @deprecated
   304 
   305 Returns a buffer created by the data source.
   306 
   307 This is a virtual function that a derived class can implement.
   308 This can be used in preference to the above CreateSourceBufferL method in cases where
   309 the source buffer creation has a dependancy on the sink buffer.
   310 
   311 @param  aMediaId
   312         This identifies the type of media eg. audio or video and the stream ID.
   313         This parameter is required in cases where the source can supply data
   314         of more than one media type and/or multiple strams of data eg a multimedia file
   315 @param  aSinkBuffer
   316         The sink buffer the nature of which may influence the creation of the source buffer.
   317 @param  aReference
   318         This must be written to by the method to indicate whether the created buffer is
   319         a 'reference' buffer.  A 'reference' buffer is a buffer that is owned by the source
   320         and should be used in preference to the sink buffer provided the sink buffer is not a
   321         reference buffer.
   322 
   323 @return A pointer to the created buffer.
   324 */
   325 inline CMMFBuffer* MDataSource::CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& /*aSinkBuffer*/, TBool &aReference)
   326 {
   327 	return CreateSourceBufferL(aMediaId, aReference);
   328 }
   329 
   330 /**
   331 Function to 'logon' the data source to the same thread that source will be supplying data in.
   332 
   333 This method may be required as the thread that the data source was created in is not always
   334 the same thread that the data transfer will take place in.  Therefore any thread specific
   335 initialisation needs to be performed in the SourceThreadLogon rather than in the creation
   336 of the data source.
   337 
   338 This is a virtual function that a derrived data source can implement if any thread specific
   339 initialisation is required and/or the data source can create any asynchronous events.
   340 
   341 @param  aEventHandler
   342         This is an MAsyncEventHandler to handle asynchronous events that occur during the
   343         transfer of multimedia data.  The event handler must be in the same thread as the data transfer
   344         thread. Hence the reason it is passed in the SourceThreadLogon as opposed to say the constructor.
   345 
   346 @return An error code indicating if the function call was successful. KErrNone on success, otherwise
   347         another of the system-wide error codes.
   348 */
   349 inline TInt MDataSource::SourceThreadLogon(MAsyncEventHandler& /*aEventHandler*/)
   350 {
   351 	return KErrNone;
   352 }
   353 
   354 /**
   355 Function to allow the data source to negotiate with a data sink
   356 
   357 This method is required in cases where the settings of data source are dependant on those of a
   358 data sink. This is a virtual function that a derrived data source can implement.
   359 
   360 @param  aDataSink
   361         The data sink whose settings can affect the data source.
   362 */
   363 inline void MDataSource::NegotiateSourceL(MDataSink& /*aDataSink*/)
   364 {
   365 }
   366 
   367 /**
   368 Function to set the source priority settings.
   369 
   370 This is a virtual function that a derrived data source can implement if
   371 a priority mechanism is required to arbitrate between multiple clients
   372 trying to access the same resource.
   373 
   374 @param  aPrioritySettings
   375         The source priority settings.
   376 
   377 */
   378 inline void MDataSource::SetSourcePrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/)
   379 {
   380 }
   381 
   382 /**
   383 This function is used by TCleanupItem objects to perform
   384 a SourceStopL() when leaving functions exist, ususally between SourcePrimeL-SourceStopL pairs.
   385 
   386 @param  aSource
   387         The data source to be stopped.
   388 */
   389 inline static void DoDataSourceStop(TAny* aSource)
   390 	{
   391 	MDataSource* source = STATIC_CAST(MDataSource*, aSource);
   392 	// we don't want this function to leave because no leaving functions are supposed
   393 	// to be used as argument to the TCleanupItem objects. Hence we catch the error but
   394 	// we do nothing with it.
   395 	TRAP_IGNORE(source->SourceStopL());
   396 	}
   397 
   398 /**
   399 This method is used by TCleanupItem objects to perform a SourceThreadLogoff().
   400 
   401 @param  aSource
   402         The data source to be logged off.
   403 */
   404 inline static void DoDataSourceThreadLogoff(TAny* aSource)
   405 	{
   406 	MDataSource* source = STATIC_CAST(MDataSource*, aSource);
   407 	source->SourceThreadLogoff();
   408 	}
   409 
   410 #endif