epoc32/include/mmf/server/mmfformat.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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 //
    15 
    16 #ifndef __MMF_SERVER_FORMAT_H__
    17 #define __MMF_SERVER_FORMAT_H__
    18 
    19 #include <mmf/server/mmfdatasink.h>
    20 #include <mmf/server/mmfdatasource.h>
    21 #include <ecom/ecom.h>
    22 #include <mmfplugininterfaceuids.hrh>
    23 
    24 const TUint KMMFFormatDefaultFrameSize = 0x1000;  //4K
    25 
    26 /**
    27 @publishedAll
    28 @released
    29 
    30 Base class from which source formats can be derived from. The intended usage is for controllers that can support more
    31 than one type of format. The class is an MDataSource as far as the data path is concerned but is an MDataSink to the clip
    32 that is the source of the actual data.
    33 
    34 All CMMFFormatDecode plugin DLLs must include interface_uid = KMmfUidPluginInterfaceFormatDecode in their .rss files.
    35 */
    36 class CMMFFormatDecode : public CBase, public MDataSource, public MDataSink
    37 	{
    38 public:
    39 	// ECOM creation.
    40 	IMPORT_C static CMMFFormatDecode* NewL( TUid aUid, MDataSource* aSource );
    41 
    42 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    43 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    44 	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    45 
    46 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    47 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    48 	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    49 
    50 	/**
    51 	Destructor.
    52 	*/
    53 	virtual ~CMMFFormatDecode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);};
    54 
    55 	/**
    56 	Returns the ECom plugin UID of this format.
    57 
    58 	@return The plugin UID.
    59 	*/
    60 	TUid ImplementationUid() const {return iImplementationUid;}
    61 
    62 	/**
    63 	Gets the number of streams of the specified media type.
    64 
    65 	This is a virtual function that each derived class must implement.
    66 
    67 	@param  aMediaType
    68 	        The UID of the media type, for example KUidMediaTypeAudio or KUidMediaTypeVideo.
    69 
    70 	@return	The number of streams of multimedia data in the format for the specified media type.
    71 	        For example, for a WAV or mp3 audio file this procedure would return 1 for a media
    72 	        type of audio and 0 for a media type of video. More complex multimedia formats (for
    73 	        example AVI and mp4) can support multiple streams of both video and audio.
    74 	*/
    75 	virtual TUint Streams(TUid aMediaType) const = 0;
    76 
    77 	/**
    78 	Returns the time interval for one frame for the specified media type.
    79 
    80 	This is a virtual function that each derived class must implement.
    81 
    82 	In the case of video, a frame would usually be one frame of video. In the case of
    83 	audio, a frame may correspond to a frame of audio, if the particular audio data type
    84 	is framed eg mp3. There are two definitions of a frame. A format frame, which may
    85 	consist of several frames of a particular framed audio data type. This may be the case,
    86 	for example for GSM610 (a low quality audio data type used in telephony) where a frame
    87 	is only 65 bytes large. In this case a format frame consists of several GSM610 data type
    88 	frames as passing the data out 65 bytes at a time would be inefficient. In the case of
    89 	non-framed data such as pcm, a frame can be an arbitrary size determined by the format plugin.
    90 
    91 	@param  aMediaType
    92 	        The media type id.
    93 
    94 	@return	The frame time interval
    95 	*/
    96 	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
    97 
    98 
    99 	/**
   100 	Returns the duration of the clip for the specified media type.
   101 
   102 	This is a virtual function that each derived class must implement.
   103 
   104 	@param  aMediaType
   105 	        The media type ID.
   106 
   107 	@return The duration of the clip.
   108 	*/
   109 	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
   110 
   111 	/**
   112 	Request from CMMFDataPath to fill the specified buffer.
   113 	The CMMFFormat needs to break this down into one or more reads from the clip
   114 	(from MDataSource - CMMFFormatDecode is a MDataSource to a CMMFDataPath consumer).
   115 
   116 	This is a virtual function that each derived class must implement.
   117 
   118 	This method is the means by which data is obtained from the data source. aBuffer is
   119 	the buffer that needs filling from the source data stream as identified by aMediaId. The
   120 	format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
   121 	method. From this the format should be able to determine the actual position of the data on
   122 	the data source. The technique here depends on the nature of the format. For a linear audio
   123 	format, the position can be obtained by a simple calculation of the frame size, the header size
   124 	and where appropriate the datatype.
   125 
   126 	For non-linear formats either an index table of frame number and location will need to be
   127 	created in the NewL() or some form of approximating algorithm will be required. Some formats have
   128 	an index table as part of the format e.g. AVI. If no random access is required then no index table
   129 	is required, the format can keep track of the current read position and increment it on each access,
   130 	and reset it if the frame number is reset to 0 or 1. Given that for non-linear i.e. variable bit rate
   131 	formats, the size of the data read may vary from frame to frame, then the format should either set
   132 	the request size of the buffer for the required frame or call the source's ReadBufferL() (either
   133 	CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or CMMFFile::ReadBufferL()) function that
   134 	takes the aLength parameter.
   135 
   136 	It is the responsibility of the format decode to determine the size and position of the source data
   137 	for each frame. For linear audio formats, the format decode should fill the buffer up to its maximum
   138 	length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively acting as a demultiplexor,
   139 	and must obtain the appropriate data from the source depending on the aMediaId.
   140 
   141 	@param  aBuffer
   142 	        The buffer to fill.
   143 	@param  aConsumer
   144 	        The consumer.
   145 	@param  aMediaId
   146 	        The media type ID.
   147 	*/
   148 	virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId)=0;
   149 
   150 	/**
   151 	@internalAll
   152 
   153 	Indicates data has been added to the file.
   154 
   155 	@param  aBuffer
   156 	        The emptied buffer.
   157     */
   158 	inline virtual void BufferEmptiedL(CMMFBuffer* aBuffer);
   159 
   160 	/**
   161 	Tests whether a source buffer can be created.
   162 
   163 	The format knows what type of source buffer it requires so default returns ETrue.
   164 	It doesn't usually need to set the size of this buffer.
   165 
   166 	@return	A boolean indicating whether a buffer can be created. ETrue if the buffer can be created,
   167 	        EFalse otherwise.
   168 	*/
   169 	virtual TBool CanCreateSourceBuffer() {return ETrue;}
   170 
   171 	/**
   172 	Creates a source buffer.
   173 
   174 	This is a virtual function that each derived class must implement.
   175 
   176 	This function should create a buffer of length 0, the maximum length should be equal to the maximum
   177 	possible frame size. In the case of non framed data it should be set to an arbitrary size, which is
   178 	effectively a trade off between being too small which will affect performance as more source reads
   179 	are required, and being too large which will give very coarse positioning granularity. For pcm data,
   180 	a buffer size of 4K is a good compromise. The same compromise also applies when deciding to put multiple
   181 	audio frames into one format frame. The sink buffer size may also effect the format buffer size and
   182 	the controller may use this to suggest a buffer size to the format by calling the format's SuggestSourceBufferSize()
   183 	method. Alternatively the MDataSource::CreateSourceBufferL() function that takes the additional aSinkBuffer
   184 	parameter may also be used when deciding the source buffer maximum size of the created source buffer.
   185 
   186 	@param  aMediaId
   187 	        The media type ID.
   188 	@param  aReference
   189 	        If ETrue the MDataSource owns the buffer. If EFalse, then the caller owns the buffer. This
   190 	        should normally be set to EFalse as format plugins do not create the reference buffer.
   191 
   192 	@return The created source buffer.
   193 	*/
   194 	virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference)=0;
   195 
   196 	/**
   197 	Returns the source data type code for the specified media type ID.
   198 
   199 	Used by the CMMFDataPath for codec matching.
   200 
   201 	This is a virtual function that each derived class must implement.
   202 
   203 	@param  aMediaId
   204 	        The media type ID.
   205 
   206 	@return The source data type code.
   207 	*/
   208 	virtual TFourCC SourceDataTypeCode(TMediaId aMediaId)=0;
   209 
   210 	/**
   211 	@internalAll
   212 
   213     Adds a buffer to a clip.
   214 
   215 	@param  aBuffer
   216 	        The buffer to which the clip is added.
   217 	@param  aSupplier
   218 	        The data source.
   219 	@param  aMediaId
   220 	        The Media ID.
   221 	*/
   222 	inline virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId);
   223 
   224 	/**
   225 	Indicates the data source has filled the buffer.
   226 
   227 	Called by the CMMFFormat's MDataSource when it has filled the buffer.
   228 	The default implementation below would need overriding in cases where multiple
   229 	clip reads were required to fill the buffer from the data path.
   230 
   231 	@param  aBuffer
   232 	        The buffer to which the clip is added.
   233 	*/
   234 	virtual void BufferFilledL(CMMFBuffer* aBuffer) {iDataPath->BufferFilledL(aBuffer);}
   235 
   236 	/**
   237 	Tests whether a sink buffer can be created.
   238 
   239 	Format would normally pass its own buffer onto the CMMFClip, so
   240 	this may not be required. The default returns EFalse.
   241 
   242 	@return A boolean indicating if the sink buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   243 	*/
   244 	virtual TBool CanCreateSinkBuffer() {return EFalse;}
   245 
   246 	/**
   247 	Creates a sink buffer for the specified media ID. The default version returns NULL.
   248 
   249 	@param  aMediaId
   250 	        The media type ID.
   251 	@param  aReference
   252 	        If ETrue the MDataSink owns the buffer.
   253 	        If EFalse, then the caller owns the buffer.
   254 	@return The CMMFBuffer sink buffer.
   255 	*/
   256 	inline virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference);
   257 
   258 	/**
   259 	Returns the sink data type code for the specified media type ID.
   260 	This would be the same as the source data type four CC although
   261 	the clip is not going to need this info.
   262 
   263 	@param  aMediaId
   264 	        The media type id.
   265 
   266 	@return The sink data type code.
   267 	*/
   268 	inline virtual TFourCC SinkDataTypeCode(TMediaId aMediaId);
   269 
   270 	/**
   271 	Gets the number of meta data entries.
   272 
   273 	Meta Data support. The decode format is only capable of reading meta data entries from the clip.
   274 
   275 	This is an optional method, used to return the number of meta data entries present in the format.
   276 	A meta data entry is a format-specific field such as authorship, copyright, security details etc.
   277 	The function is optional as many formats do not provide support for such additional meta data fields.
   278 
   279 	The default leaves with KErrNotSupported.
   280 
   281 	@param  aNumberOfEntries
   282 	        A reference to the number of meta data entries supported by the format. On return, contains
   283 	        the number of meta data entries.
   284 	*/
   285 	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
   286 
   287 	/**
   288 	Returns the specified meta data entry.
   289 
   290 	This method is optional as many formats do not provide support for such additional meta data fields.
   291 
   292 	The default leaves with KErrNotSupported.
   293 
   294 	@param  aIndex
   295 	        The zero based meta data entry index to retrieve.
   296 
   297 	@return The meta data entry.
   298 	*/
   299 	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
   300 
   301 	//audio format methods
   302 
   303 	/**
   304 	Sets the number of channels.
   305 
   306 	The default returns KErrNotSupported.
   307 
   308 	There would normally be no need to override this function as the format decode plugin can normally
   309 	determine for itself the number of channels. It is only necessary to override this in cases where the
   310 	format decode plugin cannot determine for itself the number of channels.  This function should not be
   311 	used if the audio clip already exists; that is, in the "Open and Append" scenario, when the function's
   312 	behaviour is undefined.
   313 
   314 	@param  aChannels
   315 	        The number of channels.
   316 
   317 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   318             another of the system-wide error codes.
   319 	*/
   320 	inline virtual TInt SetNumChannels(TUint aChannels);
   321 
   322 	/**
   323 	Sets the sample rate.
   324 
   325 	The default implementation returns KErrNotSupported.
   326 
   327 	There would normally be no need to override this function as the format decode can normally determine
   328 	the sample rate for itself. It is only necessary to override this in cases where the format decode plugin
   329 	cannot determine for itself the sample rate.
   330 
   331 	@param  aSampleRate
   332 	        The sample rate.
   333 
   334 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   335 	        another of the system-wide error codes.
   336 	*/
   337 	inline virtual TInt SetSampleRate(TUint aSampleRate);
   338 
   339 	/**
   340 	Sets the bit rate.
   341 
   342 	The default implementation returns KErrNotSupported.
   343 
   344 	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can
   345 	not be directly calculated from the sample rate. There would normally be no need to override this
   346 	function as the format decode can normally determine the sample rate for itself. It is only necessary
   347 	to override this in cases where the format decode plugin cannot determine for itself the sample rate.
   348 
   349 	@param aBitRate
   350 	       The bit rate in bits per second.
   351 
   352 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   353 	        another of the system-wide error codes.
   354 	*/
   355 	inline virtual TInt SetBitRate(TUint aBitRate);
   356 
   357 	/**
   358 	Returns the number of channels.
   359 
   360 	The default implementation returns 0.
   361 
   362 	@return	The number of channels.
   363 	*/
   364 	virtual TUint NumChannels() {return 0;}
   365 
   366 	/**
   367 	Gets the sample rate.
   368 
   369 	The default implementation returns 0.
   370 
   371 	@return The sample rate.
   372 	*/
   373 	virtual TUint SampleRate() {return 0;}
   374 
   375 	/**
   376 	Gets the bit rate.
   377 
   378 	The default implementation returns 0.
   379 
   380 	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate 
   381 	can not be directly calculated from the sample rate. This function needs overriding for any format 
   382 	decode that supports audio.
   383 
   384 	@return The bit rate.
   385 	*/
   386 	virtual TUint BitRate() {return 0;}
   387 
   388 	/**
   389 	Gets the supported sample rates.
   390 
   391 	The default implementation leaves with KErrNotSupported.
   392 
   393 	This should return an array of sample rates supported by the format where applicable. Note 
   394 	that this refers to the possible sample rates supported by the format, not the actual sample rate,
   395 	which will be one of the supported sample rates. The implementation of this function is optional.
   396 
   397 	@param  aSampleRates
   398 	        Reference to an array of supported sample rates.
   399 	*/
   400 	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
   401 
   402 	/**
   403 	Gets the supported bit rates.
   404 
   405 	The default leaves with KErrNotSupported.
   406 
   407 	This should return an array of bit rates supported by the format where applicable. Note that this
   408 	refers to the possible bit rates supported by the format, not the actual bit rate, which will be
   409 	one of the supported bit rates. The implementation of this function is optional.
   410 
   411 	@param  aBitRates
   412 	        Reference to an array of supported bit rates.
   413 	*/
   414 	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
   415 
   416 	/**
   417 	Gets the supported number of channels.
   418 
   419 	The default leaves with KErrNotSupported.
   420 
   421 	The implementation of this procedure should return an array of channels supported by the format
   422 	where applicable. Note that this refers to the possible number of channels supported by the format,
   423 	not the actual number of channels, which will be one of the supported channels. For example, for a
   424 	format decode plugin capable of supporting mono and stereo the procedure would return an array of
   425 	length two the first array member containing the value 1 and the second containing the value 2. The
   426 	implementation of this function is optional.
   427 
   428 	@param  aNumChannels
   429 	        A reference to an array of supported number of channels.
   430 	*/
   431 	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
   432 
   433 	/**
   434 	Gets the supported data types for the given media type id.
   435 
   436 	The default leaves with KErrNotSupported.
   437 
   438     The implementation of this procedure should return an array of data types supported by the format where
   439 	applicable. Note that this refers to the possible data types that may be supported by the format, not the
   440 	actual data type of the format, which will be one of the supported data types. For example, for a format
   441 	decode plugin capable of supporting pcm16 and GSM610 the procedure would return an array of length two the
   442 	first array member containing the fourCC code ' P16' and the second containing the value GSM6. The
   443 	implementation of this function is optional.
   444 
   445 	@param  aMediaId
   446 	        The media type id.
   447 	@param  aDataTypes
   448 	        A reference to an array of supported data types.
   449 	*/
   450 	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
   451 
   452 	/**
   453 	Used by the sink to suggest a source buffer size.
   454 
   455 	This is an optional function provided so that a controller can suggest a buffer
   456 	size for the format. The controller should not assume that the format will accept
   457 	the suggested buffer size and there is no obligation on behalf of the format to
   458 	use the suggested buffer size.
   459 
   460 	@param  aSuggestedBufferSize
   461 	        A recommended buffer size that the format should create.
   462 	*/
   463 	inline virtual void SuggestSourceBufferSize(TUint aSuggestedBufferSize);
   464 
   465 	/**
   466 	Used to set the format's position.
   467 
   468 	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
   469 	setting to determine what data to provide.
   470 
   471 	The actual position the format sets itself may vary from this setting to ensure
   472 	that it is aligned to the sample boundaries ensuring consistent data output.
   473 
   474 	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
   475 
   476 	@param  aPosition
   477 	        The position the format should use.
   478 	*/
   479     inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
   480 
   481 
   482 	/**
   483 	Supplies the current position.
   484 
   485 	Subsequent data reads will commence from this position.
   486 
   487 	@return The current position in microseconds.
   488 	*/
   489 	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
   490 	
   491 protected:
   492 	//ConstructSourceL should never be called. The CMMFFormatDecode NewL functions should
   493 	//always be used to instantiate a CMMFFormatDecode object (not MDataSource::NewL)
   494 	/**
   495 	@internalAll
   496 	*/
   497 	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   498 
   499 	//ConstructSinkL should never be called. The CMMFFormatDecode NewL functions should
   500 	//always be used to instantiate a CMMFFormatDecode object (not MDataSink::NewL)
   501 	/**
   502 	@internalAll
   503 	*/
   504 	virtual void ConstructSinkL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   505 
   506 	/**
   507 	Default constructor
   508 	*/
   509 	CMMFFormatDecode() : MDataSource(KUidMmfFormatDecode), MDataSink(KUidMmfFormatDecode) {};
   510 
   511 	// Creates and initialises format plugin.
   512 	static CMMFFormatDecode* CreateFormatL(TUid aImplementationUid, MDataSource* aSource);
   513 protected:
   514 
   515 	/**
   516 	The clip is the source for the decode format.
   517 	*/
   518 	MDataSource* iClip;
   519 
   520 	/** 
   521 	The data path is the sink for the decode format.
   522 	*/
   523 	MDataSink* iDataPath;
   524 private:
   525 	TUid iDtor_ID_Key; 			// do not move - referenced inline in ~CMMFFormatDecode()
   526 	TUid iImplementationUid;	// do not move - referenced inline in ImplementationUid()
   527 	};
   528 
   529 
   530 /**
   531 Extension class to allow derived classes to support custom interfaces
   532 
   533 @publishedPartner
   534 @prototype
   535 */
   536 
   537 class CMMFFormatDecode2 : public CMMFFormatDecode
   538 	{
   539 public:
   540 	/**
   541 	Gets a custom interface.
   542 
   543 	@param aInterfaceId
   544 			The Uid of the particular interface required.
   545  
   546 	@return Custom interface pointer. NULL if the requested interface is not supported.
   547 	*/
   548 	virtual TAny* CustomInterface(TUid aInterfaceId)=0;
   549 	};
   550 
   551 
   552 /**
   553 @publishedAll
   554 @released
   555 
   556 Base class from which sink formats can be derived from.   
   557 
   558 The intended usage is for controllers that can support more than one type of format.
   559 The class is an MDataSink as far as the data path is concerned but is an MDataSource to the clip
   560 that is the sink of the actual data. All CMMFFormatEncode plugin DLLs must include 
   561 interface_uid = KMmfUidPluginInterfaceFormatEncode in their .rss files.
   562 */
   563 class CMMFFormatEncode : public CBase, public MDataSource, public MDataSink
   564 	{
   565 public:
   566 	// ECOM creation.
   567 	IMPORT_C static CMMFFormatEncode* NewL( TUid aUid, MDataSink* aSink );
   568 	IMPORT_C static CMMFFormatEncode* NewL( const TDesC& aFileName, MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   569 	IMPORT_C static CMMFFormatEncode* NewL( const TDesC8& aSourceHeader,  MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   570 	IMPORT_C static CMMFFormatEncode* NewL( MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   571 
   572 	/**
   573 	Destructor.
   574 	*/
   575 	virtual ~CMMFFormatEncode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);}
   576 
   577 	// returns ECOM plugin uid of this format
   578 	/**
   579 	Gets the ECom plugin UID of this format.
   580 	
   581 	@return The plugin UID.
   582 	*/
   583 	TUid ImplementationUid() const {return iImplementationUid;}
   584 
   585 	/**
   586 	Returns the time interval for one frame for the specified media type.
   587 
   588 	This is a virtual function that each derived class must implement.
   589 
   590 	@param  aMediaType
   591 	        The media type ID.
   592 	@return The frame time interval in microseconds.
   593 	*/
   594 	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
   595 
   596 	/**
   597 	Returns the duration of the sink clip for the specified media type.
   598 
   599 	This is a virtual function that each derived class must implement.
   600 
   601 	@param  aMediaType
   602 	        The media type ID.
   603 	
   604 	@return The duration of the sink clip.
   605 	*/
   606 	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
   607 
   608 	/**
   609 	@internalAll
   610 	
   611 	Request from CMMFDataPath to fill the specified buffer.
   612 
   613 	@param  aBuffer
   614 	        The buffer to fill.
   615 	@param  aConsumer
   616 	        The consumer.
   617 	@param  aMediaId
   618 	        The media ID.
   619 	*/
   620 	inline virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId);
   621 
   622 	/**
   623 	Called by the clip when it has added the data to the file.
   624 
   625 	@param  aBuffer
   626 	        The emptied buffer.
   627 	*/
   628 	virtual void BufferEmptiedL(CMMFBuffer* aBuffer) {iDataPath->BufferEmptiedL(aBuffer);}
   629 
   630 	/**
   631 	Tests whether a source buffer can be created.
   632 
   633 	The default implementation returns EFalse.
   634 
   635 	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   636 	*/
   637 	virtual TBool CanCreateSourceBuffer() {return EFalse;}
   638 
   639 	/**
   640 	Creates a source buffer. The default returns NULL.
   641 
   642 	@param  aMediaId
   643 	        The media type id.
   644 	@param  aReference
   645 	        If ETrue the MDataSource owns the buffer.
   646 	        If EFalse, then the caller owns the buffer.
   647 
   648 	@return	Source buffer.
   649 	*/
   650 	inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference);
   651 
   652 	/**
   653 	Returns the source data type code for the specified media type ID.
   654 
   655 	This is a virtual function that each derived class must implement.
   656 
   657 	@param  aMediaId
   658 	        The media type id.
   659 
   660 	@return The source data type code.
   661 	*/
   662 	inline virtual TFourCC SourceDataTypeCode(TMediaId aMediaId);
   663 
   664 	/**
   665 	Adds a buffer to a clip.
   666 
   667 	Called by CMMFDataPath.
   668 	(from MDataSink - CMMFFormatEncode is a MDataSink to a CMMFDataPath)
   669 
   670 	This is a virtual function that each derived class must implement.
   671 
   672 	@param  aBuffer
   673 	        The buffer to which the clip is added.
   674 	@param  aSupplier
   675 	        The data source.
   676 	@param	aMediaId
   677 	        The media type ID.
   678 	*/
   679 	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
   680 
   681 	/**
   682 	@internalAll
   683 
   684 	Called by the CMMFDataPath's MDataSource when it has filled the buffer.
   685 
   686 	@param  aBuffer
   687 	        The buffer that has been filled.
   688 	*/
   689 	inline virtual void BufferFilledL(CMMFBuffer* aBuffer);
   690 
   691 	/**
   692 	Tests whether a sink buffer can be created.
   693 
   694 	Format would normally pass its own buffer onto the CMMFClip, so
   695 	this may not be required. The default returns ETrue.
   696 
   697 	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   698 	*/
   699 	virtual TBool CanCreateSinkBuffer() {return ETrue;}
   700 
   701 	/**
   702 	Creates a sink buffer for the specified media ID.
   703 
   704 	This is a virtual function that each derived class must implement.
   705 
   706 	@param  aMediaId
   707 	        The media type ID.
   708 	@param  aReference
   709 	        If ETrue then MDataSink owns the buffer.
   710 	        If EFalse, then the caller owns the buffer.
   711 
   712 	@return A pointer to the CMMFBuffer sink buffer.
   713 	*/
   714 	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
   715 
   716 	/**
   717 	Returns the sink data type code for the specified media type ID.
   718 
   719 	This would be the same as the source data type four CC although the clip
   720 	is not going to need this info.
   721 
   722 	This is a virtual function that each derived class must implement.
   723 
   724 	@param  aMediaId
   725 	        The media type ID.
   726 
   727 	@return The sink data type code.
   728 	*/
   729 	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
   730 
   731 	/**
   732 	This function is used to truncate the sink ie. a CMMFClip,
   733 
   734 	If aToEnd = ETrue the sink is cropped from the aPosition to the	end of the clip.
   735 	If aToEnd = EFalse then the sink is cropped from the start of the clip to aPosition.
   736 
   737 	This function would be called by the CMMFController. The default implementation leaves
   738 	with KErrNotSupported.
   739 
   740 	@param  aPosition
   741 	        The position within the clip.
   742 	@param  aToEnd
   743 	        Flag to determine which part of the clip to delete.
   744 	*/
   745 	inline virtual void CropL(TTimeIntervalMicroSeconds aPosition, TBool aToEnd = ETrue);
   746 
   747 
   748 	/**
   749 	Gets the number of meta data entries.
   750 
   751 	The encode format is capable of reading and writing meta data to the clip.
   752 
   753 	The default implementation leaves with KErrNotSupported.
   754 
   755 	@param  aNumberOfEntries
   756 	        On return, contains the number of meta data entries.
   757 	*/
   758 	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
   759 
   760 	/**
   761 	Returns the specified meta data entry.
   762 
   763 	The default implementation leaves with KErrNotSupported.
   764 
   765 	@param  aIndex
   766 	        The zero based meta data entry index to retrieve.
   767 
   768 	@return The meta data entry.
   769 	*/
   770 	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
   771 
   772 	/**
   773 	Adds the specified meta data entry to the clip.
   774 
   775 	The default implementation leaves with KErrNotSupported.
   776 
   777 	@param  aNewEntry
   778 	        The meta data entry to add.
   779 	*/
   780 	inline virtual void AddMetaDataEntryL(const CMMFMetaDataEntry& aNewEntry);
   781 
   782 	/**
   783 	Removes the specified meta data entry.
   784 
   785 	The default implementation returns KErrNotSupported.
   786 
   787 	@param  aIndex
   788 	        The zero based meta data entry index to remove.
   789 
   790 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   791 	        another of the system-wide error codes.
   792 	 */
   793 	inline virtual TInt RemoveMetaDataEntry(TInt aIndex);
   794 
   795 	/**
   796 	Replaces the specified meta data entry with the entry supplied in aNewEntry.
   797 
   798 	The default implementation leaves with KErrNotSupported.
   799 
   800 	@param  aIndex
   801 	        The zero based meta data entry index to replace.
   802 	@param  aNewEntry
   803 	        The meta data entry to replace.
   804 	*/
   805 	inline virtual void ReplaceMetaDataEntryL(TInt aIndex, const CMMFMetaDataEntry& aNewEntry);
   806 
   807 	//audio format methods
   808 
   809 	/**
   810 	Sets the number of channels.
   811 
   812 	The default implementation returns KErrNotSupported.
   813 
   814 	@param  aChannels
   815 	        The number of channels.
   816 
   817 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   818 	        another of the system-wide error codes.
   819 	*/
   820 	inline virtual TInt SetNumChannels(TUint aChannels);
   821 
   822 	/**
   823 	Sets the sample rate.
   824 
   825 	The default implementation returns KErrNotSupported.
   826 
   827 	@param  aSampleRate
   828 	        The sample rate.
   829 
   830 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   831 	        another of the system-wide error codes.
   832 	*/
   833 	inline virtual TInt SetSampleRate(TUint aSampleRate);
   834 
   835 	/**
   836 	Sets the bit rate.
   837 
   838 	The default implementation returns KErrNotSupported.
   839 
   840 	@param  aBitRate
   841 	        The bit rate.
   842 
   843 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   844 	        another of the system-wide error codes.
   845 	*/
   846 	inline virtual TInt SetBitRate(TUint aBitRate);
   847 
   848 	/**
   849 	Returns the number of channels.
   850 
   851 	The default implementation returns 0.
   852 
   853 	@return The number of channels.
   854 	*/
   855 	virtual TUint NumChannels() {return 0;}
   856 
   857 	/**
   858 	Returns the sample rate.
   859 
   860 	The default implementation returns 0.
   861 
   862 	@return The sample rate.
   863 	*/
   864 	virtual TUint SampleRate() {return 0;}
   865 
   866 	/**
   867 	Returns the default sample rate.
   868 
   869 	The default returns 0.
   870 
   871 	@return The default sample rate.
   872 	*/
   873 	virtual TUint GetDefaultSampleRate() {return 0;}
   874 
   875 	/**
   876 	Returns the bit rate.
   877 
   878 	The default returns 0.
   879 
   880 	@return The bit rate.
   881 	*/
   882 	virtual TUint BitRate() {return 0;}
   883 
   884 	/**
   885 	Returns the bytes per second.
   886 
   887 	The default returns 0.
   888 
   889 	@return The bytes per second.
   890 	*/
   891 	virtual TInt64 BytesPerSecond() {return 0;}
   892 
   893 	/**
   894 	Gets the supported sample rates.
   895 
   896 	The default implementation leaves with KErrNotSupported.
   897 
   898 	@param  aSampleRates
   899 	        A reference to an array of supported sample rates.
   900 	*/
   901 	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
   902 
   903 	/**
   904 	Gets the supported bit rates.
   905 
   906 	The default implementation leaves with KErrNotSupported.
   907 
   908 	@param  aBitRates
   909 	        A reference to an array of supported bit rates.
   910 	*/
   911 	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
   912 
   913 	/**
   914 	Gets the supported number of channels.
   915 
   916 	The default implementation leaves with KErrNotSupported.
   917 
   918 	@param  aNumChannels
   919 	        A reference to an array of supported number of channels.
   920 	*/
   921 	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
   922 
   923 	/**
   924 	Gets the supported data types for the given media type ID.
   925 
   926 	The default implementation leaves with KErrNotSupported.
   927 
   928 	@param  aMediaId
   929 	        The media type id.
   930 	@param  aDataTypes
   931 	        A reference to an array of supported data types.
   932 	*/
   933 	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
   934 
   935 	/**
   936 	Sets the maximum clip size.
   937 
   938 	The default implementation leaves with KErrNotSupported.
   939 
   940 	@param  aBytes
   941 	        The maximum clip size.
   942 	*/
   943 	inline virtual void SetMaximumClipSizeL(TInt aBytes);
   944 
   945 	/**
   946 	Returns the maximum clip size.
   947 
   948 	The default returns 0.
   949 
   950 	@return The maximum clip size.
   951 	*/
   952 	virtual TInt MaximumClipSize() { return 0;}
   953 
   954 	/**
   955 	Used to set the format's position.
   956 
   957 	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
   958 	setting to determine what data to provide.
   959 
   960 	The actual position the format sets itself may vary to this setting to ensure
   961 	that it is aligned to the sample boundaries ensuring consistent data output.
   962 
   963 	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
   964 
   965 	@param  aPosition
   966 	        The position the format should use.
   967 	*/
   968     inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
   969 
   970 
   971 	/**
   972 	Supplies the current position.
   973 
   974 	Subsequent data reads will commence from this position.
   975 
   976 	@return The current position in microseconds.
   977 	*/
   978 	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
   979 
   980 
   981 protected:
   982 	//ConstructSourceL should never be called. The CMMFFormatEncode NewL functions should
   983 	//always be used to instantiate a CMMFFormatEncode object (not MDataSource::NewL)
   984 	/**
   985 	@internalAll
   986 	*/
   987 	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   988 	//ConstructSinkL should never be called. The CMMFFormatEncode NewL functions should
   989 	//always be used to instantiate a CMMFFormatEncode object (not MDataSink::NewL)
   990 	/**
   991 	@internalAll
   992 	*/
   993 	virtual void ConstructSinkL(  const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   994 
   995 	/**
   996 	Default constructor
   997 	*/
   998 	CMMFFormatEncode() : MDataSource(KUidMmfFormatEncode), MDataSink(KUidMmfFormatEncode) {};
   999 
  1000 	// Creates and initialises format plugin.
  1001 	static CMMFFormatEncode* CreateFormatL(TUid aImplementationUid, MDataSink* aSink);
  1002 protected:
  1003 
  1004 	/** 
  1005 	The Data path is the source for the encode format.
  1006 	*/
  1007 	MDataSource* iDataPath;
  1008 	
  1009 	/** 
  1010 	The clip is the sink for the encode format.
  1011 	*/
  1012 	MDataSink* iClip;
  1013 private:
  1014 	TUid iDtor_ID_Key;				// do not move - referenced inline in ~CMMFFormatDecode()
  1015 	TUid iImplementationUid;		// do not move - referenced inline in ImplementationUid()
  1016 	};
  1017 
  1018 
  1019 class CMMFFormatPluginSelectionParameters;
  1020 
  1021 /**
  1022 @publishedAll
  1023 @released
  1024 
  1025 Provides an internal utility function to choose a format plugin from ECom.
  1026 */
  1027 class MMFFormatEcomUtilities
  1028 	{
  1029 public:
  1030 	//Internal utility function to choose a format plugin from ECOM
  1031 	static TUid SelectFormatPluginL(const CMMFFormatPluginSelectionParameters& aSelectParams);
  1032 
  1033 	// Internal utility function to instantiate each format decode plugin in turn
  1034 	// until we find one that works
  1035 	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource);
  1036 
  1037 	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource, TBool& aSupportsCustomInterfaces);
  1038 	};
  1039 
  1040 #include "mmfformat.inl"
  1041 
  1042 #endif