epoc32/include/mmf/server/mmfformat.h
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/mmf/server/mmfformat.h	Tue Mar 16 16:12:26 2010 +0000
     1.3 @@ -0,0 +1,1042 @@
     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 +//
    1.18 +
    1.19 +#ifndef __MMF_SERVER_FORMAT_H__
    1.20 +#define __MMF_SERVER_FORMAT_H__
    1.21 +
    1.22 +#include <mmf/server/mmfdatasink.h>
    1.23 +#include <mmf/server/mmfdatasource.h>
    1.24 +#include <ecom/ecom.h>
    1.25 +#include <mmfplugininterfaceuids.hrh>
    1.26 +
    1.27 +const TUint KMMFFormatDefaultFrameSize = 0x1000;  //4K
    1.28 +
    1.29 +/**
    1.30 +@publishedAll
    1.31 +@released
    1.32 +
    1.33 +Base class from which source formats can be derived from. The intended usage is for controllers that can support more
    1.34 +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
    1.35 +that is the source of the actual data.
    1.36 +
    1.37 +All CMMFFormatDecode plugin DLLs must include interface_uid = KMmfUidPluginInterfaceFormatDecode in their .rss files.
    1.38 +*/
    1.39 +class CMMFFormatDecode : public CBase, public MDataSource, public MDataSink
    1.40 +	{
    1.41 +public:
    1.42 +	// ECOM creation.
    1.43 +	IMPORT_C static CMMFFormatDecode* NewL( TUid aUid, MDataSource* aSource );
    1.44 +
    1.45 +	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    1.46 +	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    1.47 +	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
    1.48 +
    1.49 +	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    1.50 +	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    1.51 +	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
    1.52 +
    1.53 +	/**
    1.54 +	Destructor.
    1.55 +	*/
    1.56 +	virtual ~CMMFFormatDecode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);};
    1.57 +
    1.58 +	/**
    1.59 +	Returns the ECom plugin UID of this format.
    1.60 +
    1.61 +	@return The plugin UID.
    1.62 +	*/
    1.63 +	TUid ImplementationUid() const {return iImplementationUid;}
    1.64 +
    1.65 +	/**
    1.66 +	Gets the number of streams of the specified media type.
    1.67 +
    1.68 +	This is a virtual function that each derived class must implement.
    1.69 +
    1.70 +	@param  aMediaType
    1.71 +	        The UID of the media type, for example KUidMediaTypeAudio or KUidMediaTypeVideo.
    1.72 +
    1.73 +	@return	The number of streams of multimedia data in the format for the specified media type.
    1.74 +	        For example, for a WAV or mp3 audio file this procedure would return 1 for a media
    1.75 +	        type of audio and 0 for a media type of video. More complex multimedia formats (for
    1.76 +	        example AVI and mp4) can support multiple streams of both video and audio.
    1.77 +	*/
    1.78 +	virtual TUint Streams(TUid aMediaType) const = 0;
    1.79 +
    1.80 +	/**
    1.81 +	Returns the time interval for one frame for the specified media type.
    1.82 +
    1.83 +	This is a virtual function that each derived class must implement.
    1.84 +
    1.85 +	In the case of video, a frame would usually be one frame of video. In the case of
    1.86 +	audio, a frame may correspond to a frame of audio, if the particular audio data type
    1.87 +	is framed eg mp3. There are two definitions of a frame. A format frame, which may
    1.88 +	consist of several frames of a particular framed audio data type. This may be the case,
    1.89 +	for example for GSM610 (a low quality audio data type used in telephony) where a frame
    1.90 +	is only 65 bytes large. In this case a format frame consists of several GSM610 data type
    1.91 +	frames as passing the data out 65 bytes at a time would be inefficient. In the case of
    1.92 +	non-framed data such as pcm, a frame can be an arbitrary size determined by the format plugin.
    1.93 +
    1.94 +	@param  aMediaType
    1.95 +	        The media type id.
    1.96 +
    1.97 +	@return	The frame time interval
    1.98 +	*/
    1.99 +	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
   1.100 +
   1.101 +
   1.102 +	/**
   1.103 +	Returns the duration of the clip for the specified media type.
   1.104 +
   1.105 +	This is a virtual function that each derived class must implement.
   1.106 +
   1.107 +	@param  aMediaType
   1.108 +	        The media type ID.
   1.109 +
   1.110 +	@return The duration of the clip.
   1.111 +	*/
   1.112 +	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
   1.113 +
   1.114 +	/**
   1.115 +	Request from CMMFDataPath to fill the specified buffer.
   1.116 +	The CMMFFormat needs to break this down into one or more reads from the clip
   1.117 +	(from MDataSource - CMMFFormatDecode is a MDataSource to a CMMFDataPath consumer).
   1.118 +
   1.119 +	This is a virtual function that each derived class must implement.
   1.120 +
   1.121 +	This method is the means by which data is obtained from the data source. aBuffer is
   1.122 +	the buffer that needs filling from the source data stream as identified by aMediaId. The
   1.123 +	format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
   1.124 +	method. From this the format should be able to determine the actual position of the data on
   1.125 +	the data source. The technique here depends on the nature of the format. For a linear audio
   1.126 +	format, the position can be obtained by a simple calculation of the frame size, the header size
   1.127 +	and where appropriate the datatype.
   1.128 +
   1.129 +	For non-linear formats either an index table of frame number and location will need to be
   1.130 +	created in the NewL() or some form of approximating algorithm will be required. Some formats have
   1.131 +	an index table as part of the format e.g. AVI. If no random access is required then no index table
   1.132 +	is required, the format can keep track of the current read position and increment it on each access,
   1.133 +	and reset it if the frame number is reset to 0 or 1. Given that for non-linear i.e. variable bit rate
   1.134 +	formats, the size of the data read may vary from frame to frame, then the format should either set
   1.135 +	the request size of the buffer for the required frame or call the source's ReadBufferL() (either
   1.136 +	CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or CMMFFile::ReadBufferL()) function that
   1.137 +	takes the aLength parameter.
   1.138 +
   1.139 +	It is the responsibility of the format decode to determine the size and position of the source data
   1.140 +	for each frame. For linear audio formats, the format decode should fill the buffer up to its maximum
   1.141 +	length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively acting as a demultiplexor,
   1.142 +	and must obtain the appropriate data from the source depending on the aMediaId.
   1.143 +
   1.144 +	@param  aBuffer
   1.145 +	        The buffer to fill.
   1.146 +	@param  aConsumer
   1.147 +	        The consumer.
   1.148 +	@param  aMediaId
   1.149 +	        The media type ID.
   1.150 +	*/
   1.151 +	virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId)=0;
   1.152 +
   1.153 +	/**
   1.154 +	@internalAll
   1.155 +
   1.156 +	Indicates data has been added to the file.
   1.157 +
   1.158 +	@param  aBuffer
   1.159 +	        The emptied buffer.
   1.160 +    */
   1.161 +	inline virtual void BufferEmptiedL(CMMFBuffer* aBuffer);
   1.162 +
   1.163 +	/**
   1.164 +	Tests whether a source buffer can be created.
   1.165 +
   1.166 +	The format knows what type of source buffer it requires so default returns ETrue.
   1.167 +	It doesn't usually need to set the size of this buffer.
   1.168 +
   1.169 +	@return	A boolean indicating whether a buffer can be created. ETrue if the buffer can be created,
   1.170 +	        EFalse otherwise.
   1.171 +	*/
   1.172 +	virtual TBool CanCreateSourceBuffer() {return ETrue;}
   1.173 +
   1.174 +	/**
   1.175 +	Creates a source buffer.
   1.176 +
   1.177 +	This is a virtual function that each derived class must implement.
   1.178 +
   1.179 +	This function should create a buffer of length 0, the maximum length should be equal to the maximum
   1.180 +	possible frame size. In the case of non framed data it should be set to an arbitrary size, which is
   1.181 +	effectively a trade off between being too small which will affect performance as more source reads
   1.182 +	are required, and being too large which will give very coarse positioning granularity. For pcm data,
   1.183 +	a buffer size of 4K is a good compromise. The same compromise also applies when deciding to put multiple
   1.184 +	audio frames into one format frame. The sink buffer size may also effect the format buffer size and
   1.185 +	the controller may use this to suggest a buffer size to the format by calling the format's SuggestSourceBufferSize()
   1.186 +	method. Alternatively the MDataSource::CreateSourceBufferL() function that takes the additional aSinkBuffer
   1.187 +	parameter may also be used when deciding the source buffer maximum size of the created source buffer.
   1.188 +
   1.189 +	@param  aMediaId
   1.190 +	        The media type ID.
   1.191 +	@param  aReference
   1.192 +	        If ETrue the MDataSource owns the buffer. If EFalse, then the caller owns the buffer. This
   1.193 +	        should normally be set to EFalse as format plugins do not create the reference buffer.
   1.194 +
   1.195 +	@return The created source buffer.
   1.196 +	*/
   1.197 +	virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference)=0;
   1.198 +
   1.199 +	/**
   1.200 +	Returns the source data type code for the specified media type ID.
   1.201 +
   1.202 +	Used by the CMMFDataPath for codec matching.
   1.203 +
   1.204 +	This is a virtual function that each derived class must implement.
   1.205 +
   1.206 +	@param  aMediaId
   1.207 +	        The media type ID.
   1.208 +
   1.209 +	@return The source data type code.
   1.210 +	*/
   1.211 +	virtual TFourCC SourceDataTypeCode(TMediaId aMediaId)=0;
   1.212 +
   1.213 +	/**
   1.214 +	@internalAll
   1.215 +
   1.216 +    Adds a buffer to a clip.
   1.217 +
   1.218 +	@param  aBuffer
   1.219 +	        The buffer to which the clip is added.
   1.220 +	@param  aSupplier
   1.221 +	        The data source.
   1.222 +	@param  aMediaId
   1.223 +	        The Media ID.
   1.224 +	*/
   1.225 +	inline virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId);
   1.226 +
   1.227 +	/**
   1.228 +	Indicates the data source has filled the buffer.
   1.229 +
   1.230 +	Called by the CMMFFormat's MDataSource when it has filled the buffer.
   1.231 +	The default implementation below would need overriding in cases where multiple
   1.232 +	clip reads were required to fill the buffer from the data path.
   1.233 +
   1.234 +	@param  aBuffer
   1.235 +	        The buffer to which the clip is added.
   1.236 +	*/
   1.237 +	virtual void BufferFilledL(CMMFBuffer* aBuffer) {iDataPath->BufferFilledL(aBuffer);}
   1.238 +
   1.239 +	/**
   1.240 +	Tests whether a sink buffer can be created.
   1.241 +
   1.242 +	Format would normally pass its own buffer onto the CMMFClip, so
   1.243 +	this may not be required. The default returns EFalse.
   1.244 +
   1.245 +	@return A boolean indicating if the sink buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   1.246 +	*/
   1.247 +	virtual TBool CanCreateSinkBuffer() {return EFalse;}
   1.248 +
   1.249 +	/**
   1.250 +	Creates a sink buffer for the specified media ID. The default version returns NULL.
   1.251 +
   1.252 +	@param  aMediaId
   1.253 +	        The media type ID.
   1.254 +	@param  aReference
   1.255 +	        If ETrue the MDataSink owns the buffer.
   1.256 +	        If EFalse, then the caller owns the buffer.
   1.257 +	@return The CMMFBuffer sink buffer.
   1.258 +	*/
   1.259 +	inline virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference);
   1.260 +
   1.261 +	/**
   1.262 +	Returns the sink data type code for the specified media type ID.
   1.263 +	This would be the same as the source data type four CC although
   1.264 +	the clip is not going to need this info.
   1.265 +
   1.266 +	@param  aMediaId
   1.267 +	        The media type id.
   1.268 +
   1.269 +	@return The sink data type code.
   1.270 +	*/
   1.271 +	inline virtual TFourCC SinkDataTypeCode(TMediaId aMediaId);
   1.272 +
   1.273 +	/**
   1.274 +	Gets the number of meta data entries.
   1.275 +
   1.276 +	Meta Data support. The decode format is only capable of reading meta data entries from the clip.
   1.277 +
   1.278 +	This is an optional method, used to return the number of meta data entries present in the format.
   1.279 +	A meta data entry is a format-specific field such as authorship, copyright, security details etc.
   1.280 +	The function is optional as many formats do not provide support for such additional meta data fields.
   1.281 +
   1.282 +	The default leaves with KErrNotSupported.
   1.283 +
   1.284 +	@param  aNumberOfEntries
   1.285 +	        A reference to the number of meta data entries supported by the format. On return, contains
   1.286 +	        the number of meta data entries.
   1.287 +	*/
   1.288 +	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
   1.289 +
   1.290 +	/**
   1.291 +	Returns the specified meta data entry.
   1.292 +
   1.293 +	This method is optional as many formats do not provide support for such additional meta data fields.
   1.294 +
   1.295 +	The default leaves with KErrNotSupported.
   1.296 +
   1.297 +	@param  aIndex
   1.298 +	        The zero based meta data entry index to retrieve.
   1.299 +
   1.300 +	@return The meta data entry.
   1.301 +	*/
   1.302 +	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
   1.303 +
   1.304 +	//audio format methods
   1.305 +
   1.306 +	/**
   1.307 +	Sets the number of channels.
   1.308 +
   1.309 +	The default returns KErrNotSupported.
   1.310 +
   1.311 +	There would normally be no need to override this function as the format decode plugin can normally
   1.312 +	determine for itself the number of channels. It is only necessary to override this in cases where the
   1.313 +	format decode plugin cannot determine for itself the number of channels.  This function should not be
   1.314 +	used if the audio clip already exists; that is, in the "Open and Append" scenario, when the function's
   1.315 +	behaviour is undefined.
   1.316 +
   1.317 +	@param  aChannels
   1.318 +	        The number of channels.
   1.319 +
   1.320 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.321 +            another of the system-wide error codes.
   1.322 +	*/
   1.323 +	inline virtual TInt SetNumChannels(TUint aChannels);
   1.324 +
   1.325 +	/**
   1.326 +	Sets the sample rate.
   1.327 +
   1.328 +	The default implementation returns KErrNotSupported.
   1.329 +
   1.330 +	There would normally be no need to override this function as the format decode can normally determine
   1.331 +	the sample rate for itself. It is only necessary to override this in cases where the format decode plugin
   1.332 +	cannot determine for itself the sample rate.
   1.333 +
   1.334 +	@param  aSampleRate
   1.335 +	        The sample rate.
   1.336 +
   1.337 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.338 +	        another of the system-wide error codes.
   1.339 +	*/
   1.340 +	inline virtual TInt SetSampleRate(TUint aSampleRate);
   1.341 +
   1.342 +	/**
   1.343 +	Sets the bit rate.
   1.344 +
   1.345 +	The default implementation returns KErrNotSupported.
   1.346 +
   1.347 +	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can
   1.348 +	not be directly calculated from the sample rate. There would normally be no need to override this
   1.349 +	function as the format decode can normally determine the sample rate for itself. It is only necessary
   1.350 +	to override this in cases where the format decode plugin cannot determine for itself the sample rate.
   1.351 +
   1.352 +	@param aBitRate
   1.353 +	       The bit rate in bits per second.
   1.354 +
   1.355 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.356 +	        another of the system-wide error codes.
   1.357 +	*/
   1.358 +	inline virtual TInt SetBitRate(TUint aBitRate);
   1.359 +
   1.360 +	/**
   1.361 +	Returns the number of channels.
   1.362 +
   1.363 +	The default implementation returns 0.
   1.364 +
   1.365 +	@return	The number of channels.
   1.366 +	*/
   1.367 +	virtual TUint NumChannels() {return 0;}
   1.368 +
   1.369 +	/**
   1.370 +	Gets the sample rate.
   1.371 +
   1.372 +	The default implementation returns 0.
   1.373 +
   1.374 +	@return The sample rate.
   1.375 +	*/
   1.376 +	virtual TUint SampleRate() {return 0;}
   1.377 +
   1.378 +	/**
   1.379 +	Gets the bit rate.
   1.380 +
   1.381 +	The default implementation returns 0.
   1.382 +
   1.383 +	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate 
   1.384 +	can not be directly calculated from the sample rate. This function needs overriding for any format 
   1.385 +	decode that supports audio.
   1.386 +
   1.387 +	@return The bit rate.
   1.388 +	*/
   1.389 +	virtual TUint BitRate() {return 0;}
   1.390 +
   1.391 +	/**
   1.392 +	Gets the supported sample rates.
   1.393 +
   1.394 +	The default implementation leaves with KErrNotSupported.
   1.395 +
   1.396 +	This should return an array of sample rates supported by the format where applicable. Note 
   1.397 +	that this refers to the possible sample rates supported by the format, not the actual sample rate,
   1.398 +	which will be one of the supported sample rates. The implementation of this function is optional.
   1.399 +
   1.400 +	@param  aSampleRates
   1.401 +	        Reference to an array of supported sample rates.
   1.402 +	*/
   1.403 +	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
   1.404 +
   1.405 +	/**
   1.406 +	Gets the supported bit rates.
   1.407 +
   1.408 +	The default leaves with KErrNotSupported.
   1.409 +
   1.410 +	This should return an array of bit rates supported by the format where applicable. Note that this
   1.411 +	refers to the possible bit rates supported by the format, not the actual bit rate, which will be
   1.412 +	one of the supported bit rates. The implementation of this function is optional.
   1.413 +
   1.414 +	@param  aBitRates
   1.415 +	        Reference to an array of supported bit rates.
   1.416 +	*/
   1.417 +	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
   1.418 +
   1.419 +	/**
   1.420 +	Gets the supported number of channels.
   1.421 +
   1.422 +	The default leaves with KErrNotSupported.
   1.423 +
   1.424 +	The implementation of this procedure should return an array of channels supported by the format
   1.425 +	where applicable. Note that this refers to the possible number of channels supported by the format,
   1.426 +	not the actual number of channels, which will be one of the supported channels. For example, for a
   1.427 +	format decode plugin capable of supporting mono and stereo the procedure would return an array of
   1.428 +	length two the first array member containing the value 1 and the second containing the value 2. The
   1.429 +	implementation of this function is optional.
   1.430 +
   1.431 +	@param  aNumChannels
   1.432 +	        A reference to an array of supported number of channels.
   1.433 +	*/
   1.434 +	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
   1.435 +
   1.436 +	/**
   1.437 +	Gets the supported data types for the given media type id.
   1.438 +
   1.439 +	The default leaves with KErrNotSupported.
   1.440 +
   1.441 +    The implementation of this procedure should return an array of data types supported by the format where
   1.442 +	applicable. Note that this refers to the possible data types that may be supported by the format, not the
   1.443 +	actual data type of the format, which will be one of the supported data types. For example, for a format
   1.444 +	decode plugin capable of supporting pcm16 and GSM610 the procedure would return an array of length two the
   1.445 +	first array member containing the fourCC code ' P16' and the second containing the value GSM6. The
   1.446 +	implementation of this function is optional.
   1.447 +
   1.448 +	@param  aMediaId
   1.449 +	        The media type id.
   1.450 +	@param  aDataTypes
   1.451 +	        A reference to an array of supported data types.
   1.452 +	*/
   1.453 +	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
   1.454 +
   1.455 +	/**
   1.456 +	Used by the sink to suggest a source buffer size.
   1.457 +
   1.458 +	This is an optional function provided so that a controller can suggest a buffer
   1.459 +	size for the format. The controller should not assume that the format will accept
   1.460 +	the suggested buffer size and there is no obligation on behalf of the format to
   1.461 +	use the suggested buffer size.
   1.462 +
   1.463 +	@param  aSuggestedBufferSize
   1.464 +	        A recommended buffer size that the format should create.
   1.465 +	*/
   1.466 +	inline virtual void SuggestSourceBufferSize(TUint aSuggestedBufferSize);
   1.467 +
   1.468 +	/**
   1.469 +	Used to set the format's position.
   1.470 +
   1.471 +	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
   1.472 +	setting to determine what data to provide.
   1.473 +
   1.474 +	The actual position the format sets itself may vary from this setting to ensure
   1.475 +	that it is aligned to the sample boundaries ensuring consistent data output.
   1.476 +
   1.477 +	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
   1.478 +
   1.479 +	@param  aPosition
   1.480 +	        The position the format should use.
   1.481 +	*/
   1.482 +    inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
   1.483 +
   1.484 +
   1.485 +	/**
   1.486 +	Supplies the current position.
   1.487 +
   1.488 +	Subsequent data reads will commence from this position.
   1.489 +
   1.490 +	@return The current position in microseconds.
   1.491 +	*/
   1.492 +	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
   1.493 +	
   1.494 +protected:
   1.495 +	//ConstructSourceL should never be called. The CMMFFormatDecode NewL functions should
   1.496 +	//always be used to instantiate a CMMFFormatDecode object (not MDataSource::NewL)
   1.497 +	/**
   1.498 +	@internalAll
   1.499 +	*/
   1.500 +	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   1.501 +
   1.502 +	//ConstructSinkL should never be called. The CMMFFormatDecode NewL functions should
   1.503 +	//always be used to instantiate a CMMFFormatDecode object (not MDataSink::NewL)
   1.504 +	/**
   1.505 +	@internalAll
   1.506 +	*/
   1.507 +	virtual void ConstructSinkL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   1.508 +
   1.509 +	/**
   1.510 +	Default constructor
   1.511 +	*/
   1.512 +	CMMFFormatDecode() : MDataSource(KUidMmfFormatDecode), MDataSink(KUidMmfFormatDecode) {};
   1.513 +
   1.514 +	// Creates and initialises format plugin.
   1.515 +	static CMMFFormatDecode* CreateFormatL(TUid aImplementationUid, MDataSource* aSource);
   1.516 +protected:
   1.517 +
   1.518 +	/**
   1.519 +	The clip is the source for the decode format.
   1.520 +	*/
   1.521 +	MDataSource* iClip;
   1.522 +
   1.523 +	/** 
   1.524 +	The data path is the sink for the decode format.
   1.525 +	*/
   1.526 +	MDataSink* iDataPath;
   1.527 +private:
   1.528 +	TUid iDtor_ID_Key; 			// do not move - referenced inline in ~CMMFFormatDecode()
   1.529 +	TUid iImplementationUid;	// do not move - referenced inline in ImplementationUid()
   1.530 +	};
   1.531 +
   1.532 +
   1.533 +/**
   1.534 +Extension class to allow derived classes to support custom interfaces
   1.535 +
   1.536 +@publishedPartner
   1.537 +@prototype
   1.538 +*/
   1.539 +
   1.540 +class CMMFFormatDecode2 : public CMMFFormatDecode
   1.541 +	{
   1.542 +public:
   1.543 +	/**
   1.544 +	Gets a custom interface.
   1.545 +
   1.546 +	@param aInterfaceId
   1.547 +			The Uid of the particular interface required.
   1.548 + 
   1.549 +	@return Custom interface pointer. NULL if the requested interface is not supported.
   1.550 +	*/
   1.551 +	virtual TAny* CustomInterface(TUid aInterfaceId)=0;
   1.552 +	};
   1.553 +
   1.554 +
   1.555 +/**
   1.556 +@publishedAll
   1.557 +@released
   1.558 +
   1.559 +Base class from which sink formats can be derived from.   
   1.560 +
   1.561 +The intended usage is for controllers that can support more than one type of format.
   1.562 +The class is an MDataSink as far as the data path is concerned but is an MDataSource to the clip
   1.563 +that is the sink of the actual data. All CMMFFormatEncode plugin DLLs must include 
   1.564 +interface_uid = KMmfUidPluginInterfaceFormatEncode in their .rss files.
   1.565 +*/
   1.566 +class CMMFFormatEncode : public CBase, public MDataSource, public MDataSink
   1.567 +	{
   1.568 +public:
   1.569 +	// ECOM creation.
   1.570 +	IMPORT_C static CMMFFormatEncode* NewL( TUid aUid, MDataSink* aSink );
   1.571 +	IMPORT_C static CMMFFormatEncode* NewL( const TDesC& aFileName, MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   1.572 +	IMPORT_C static CMMFFormatEncode* NewL( const TDesC8& aSourceHeader,  MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   1.573 +	IMPORT_C static CMMFFormatEncode* NewL( MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
   1.574 +
   1.575 +	/**
   1.576 +	Destructor.
   1.577 +	*/
   1.578 +	virtual ~CMMFFormatEncode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);}
   1.579 +
   1.580 +	// returns ECOM plugin uid of this format
   1.581 +	/**
   1.582 +	Gets the ECom plugin UID of this format.
   1.583 +	
   1.584 +	@return The plugin UID.
   1.585 +	*/
   1.586 +	TUid ImplementationUid() const {return iImplementationUid;}
   1.587 +
   1.588 +	/**
   1.589 +	Returns the time interval for one frame for the specified media type.
   1.590 +
   1.591 +	This is a virtual function that each derived class must implement.
   1.592 +
   1.593 +	@param  aMediaType
   1.594 +	        The media type ID.
   1.595 +	@return The frame time interval in microseconds.
   1.596 +	*/
   1.597 +	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
   1.598 +
   1.599 +	/**
   1.600 +	Returns the duration of the sink clip for the specified media type.
   1.601 +
   1.602 +	This is a virtual function that each derived class must implement.
   1.603 +
   1.604 +	@param  aMediaType
   1.605 +	        The media type ID.
   1.606 +	
   1.607 +	@return The duration of the sink clip.
   1.608 +	*/
   1.609 +	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
   1.610 +
   1.611 +	/**
   1.612 +	@internalAll
   1.613 +	
   1.614 +	Request from CMMFDataPath to fill the specified buffer.
   1.615 +
   1.616 +	@param  aBuffer
   1.617 +	        The buffer to fill.
   1.618 +	@param  aConsumer
   1.619 +	        The consumer.
   1.620 +	@param  aMediaId
   1.621 +	        The media ID.
   1.622 +	*/
   1.623 +	inline virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId);
   1.624 +
   1.625 +	/**
   1.626 +	Called by the clip when it has added the data to the file.
   1.627 +
   1.628 +	@param  aBuffer
   1.629 +	        The emptied buffer.
   1.630 +	*/
   1.631 +	virtual void BufferEmptiedL(CMMFBuffer* aBuffer) {iDataPath->BufferEmptiedL(aBuffer);}
   1.632 +
   1.633 +	/**
   1.634 +	Tests whether a source buffer can be created.
   1.635 +
   1.636 +	The default implementation returns EFalse.
   1.637 +
   1.638 +	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   1.639 +	*/
   1.640 +	virtual TBool CanCreateSourceBuffer() {return EFalse;}
   1.641 +
   1.642 +	/**
   1.643 +	Creates a source buffer. The default returns NULL.
   1.644 +
   1.645 +	@param  aMediaId
   1.646 +	        The media type id.
   1.647 +	@param  aReference
   1.648 +	        If ETrue the MDataSource owns the buffer.
   1.649 +	        If EFalse, then the caller owns the buffer.
   1.650 +
   1.651 +	@return	Source buffer.
   1.652 +	*/
   1.653 +	inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference);
   1.654 +
   1.655 +	/**
   1.656 +	Returns the source data type code for the specified media type ID.
   1.657 +
   1.658 +	This is a virtual function that each derived class must implement.
   1.659 +
   1.660 +	@param  aMediaId
   1.661 +	        The media type id.
   1.662 +
   1.663 +	@return The source data type code.
   1.664 +	*/
   1.665 +	inline virtual TFourCC SourceDataTypeCode(TMediaId aMediaId);
   1.666 +
   1.667 +	/**
   1.668 +	Adds a buffer to a clip.
   1.669 +
   1.670 +	Called by CMMFDataPath.
   1.671 +	(from MDataSink - CMMFFormatEncode is a MDataSink to a CMMFDataPath)
   1.672 +
   1.673 +	This is a virtual function that each derived class must implement.
   1.674 +
   1.675 +	@param  aBuffer
   1.676 +	        The buffer to which the clip is added.
   1.677 +	@param  aSupplier
   1.678 +	        The data source.
   1.679 +	@param	aMediaId
   1.680 +	        The media type ID.
   1.681 +	*/
   1.682 +	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
   1.683 +
   1.684 +	/**
   1.685 +	@internalAll
   1.686 +
   1.687 +	Called by the CMMFDataPath's MDataSource when it has filled the buffer.
   1.688 +
   1.689 +	@param  aBuffer
   1.690 +	        The buffer that has been filled.
   1.691 +	*/
   1.692 +	inline virtual void BufferFilledL(CMMFBuffer* aBuffer);
   1.693 +
   1.694 +	/**
   1.695 +	Tests whether a sink buffer can be created.
   1.696 +
   1.697 +	Format would normally pass its own buffer onto the CMMFClip, so
   1.698 +	this may not be required. The default returns ETrue.
   1.699 +
   1.700 +	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
   1.701 +	*/
   1.702 +	virtual TBool CanCreateSinkBuffer() {return ETrue;}
   1.703 +
   1.704 +	/**
   1.705 +	Creates a sink buffer for the specified media ID.
   1.706 +
   1.707 +	This is a virtual function that each derived class must implement.
   1.708 +
   1.709 +	@param  aMediaId
   1.710 +	        The media type ID.
   1.711 +	@param  aReference
   1.712 +	        If ETrue then MDataSink owns the buffer.
   1.713 +	        If EFalse, then the caller owns the buffer.
   1.714 +
   1.715 +	@return A pointer to the CMMFBuffer sink buffer.
   1.716 +	*/
   1.717 +	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
   1.718 +
   1.719 +	/**
   1.720 +	Returns the sink data type code for the specified media type ID.
   1.721 +
   1.722 +	This would be the same as the source data type four CC although the clip
   1.723 +	is not going to need this info.
   1.724 +
   1.725 +	This is a virtual function that each derived class must implement.
   1.726 +
   1.727 +	@param  aMediaId
   1.728 +	        The media type ID.
   1.729 +
   1.730 +	@return The sink data type code.
   1.731 +	*/
   1.732 +	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
   1.733 +
   1.734 +	/**
   1.735 +	This function is used to truncate the sink ie. a CMMFClip,
   1.736 +
   1.737 +	If aToEnd = ETrue the sink is cropped from the aPosition to the	end of the clip.
   1.738 +	If aToEnd = EFalse then the sink is cropped from the start of the clip to aPosition.
   1.739 +
   1.740 +	This function would be called by the CMMFController. The default implementation leaves
   1.741 +	with KErrNotSupported.
   1.742 +
   1.743 +	@param  aPosition
   1.744 +	        The position within the clip.
   1.745 +	@param  aToEnd
   1.746 +	        Flag to determine which part of the clip to delete.
   1.747 +	*/
   1.748 +	inline virtual void CropL(TTimeIntervalMicroSeconds aPosition, TBool aToEnd = ETrue);
   1.749 +
   1.750 +
   1.751 +	/**
   1.752 +	Gets the number of meta data entries.
   1.753 +
   1.754 +	The encode format is capable of reading and writing meta data to the clip.
   1.755 +
   1.756 +	The default implementation leaves with KErrNotSupported.
   1.757 +
   1.758 +	@param  aNumberOfEntries
   1.759 +	        On return, contains the number of meta data entries.
   1.760 +	*/
   1.761 +	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
   1.762 +
   1.763 +	/**
   1.764 +	Returns the specified meta data entry.
   1.765 +
   1.766 +	The default implementation leaves with KErrNotSupported.
   1.767 +
   1.768 +	@param  aIndex
   1.769 +	        The zero based meta data entry index to retrieve.
   1.770 +
   1.771 +	@return The meta data entry.
   1.772 +	*/
   1.773 +	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
   1.774 +
   1.775 +	/**
   1.776 +	Adds the specified meta data entry to the clip.
   1.777 +
   1.778 +	The default implementation leaves with KErrNotSupported.
   1.779 +
   1.780 +	@param  aNewEntry
   1.781 +	        The meta data entry to add.
   1.782 +	*/
   1.783 +	inline virtual void AddMetaDataEntryL(const CMMFMetaDataEntry& aNewEntry);
   1.784 +
   1.785 +	/**
   1.786 +	Removes the specified meta data entry.
   1.787 +
   1.788 +	The default implementation returns KErrNotSupported.
   1.789 +
   1.790 +	@param  aIndex
   1.791 +	        The zero based meta data entry index to remove.
   1.792 +
   1.793 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.794 +	        another of the system-wide error codes.
   1.795 +	 */
   1.796 +	inline virtual TInt RemoveMetaDataEntry(TInt aIndex);
   1.797 +
   1.798 +	/**
   1.799 +	Replaces the specified meta data entry with the entry supplied in aNewEntry.
   1.800 +
   1.801 +	The default implementation leaves with KErrNotSupported.
   1.802 +
   1.803 +	@param  aIndex
   1.804 +	        The zero based meta data entry index to replace.
   1.805 +	@param  aNewEntry
   1.806 +	        The meta data entry to replace.
   1.807 +	*/
   1.808 +	inline virtual void ReplaceMetaDataEntryL(TInt aIndex, const CMMFMetaDataEntry& aNewEntry);
   1.809 +
   1.810 +	//audio format methods
   1.811 +
   1.812 +	/**
   1.813 +	Sets the number of channels.
   1.814 +
   1.815 +	The default implementation returns KErrNotSupported.
   1.816 +
   1.817 +	@param  aChannels
   1.818 +	        The number of channels.
   1.819 +
   1.820 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.821 +	        another of the system-wide error codes.
   1.822 +	*/
   1.823 +	inline virtual TInt SetNumChannels(TUint aChannels);
   1.824 +
   1.825 +	/**
   1.826 +	Sets the sample rate.
   1.827 +
   1.828 +	The default implementation returns KErrNotSupported.
   1.829 +
   1.830 +	@param  aSampleRate
   1.831 +	        The sample rate.
   1.832 +
   1.833 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.834 +	        another of the system-wide error codes.
   1.835 +	*/
   1.836 +	inline virtual TInt SetSampleRate(TUint aSampleRate);
   1.837 +
   1.838 +	/**
   1.839 +	Sets the bit rate.
   1.840 +
   1.841 +	The default implementation returns KErrNotSupported.
   1.842 +
   1.843 +	@param  aBitRate
   1.844 +	        The bit rate.
   1.845 +
   1.846 +	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
   1.847 +	        another of the system-wide error codes.
   1.848 +	*/
   1.849 +	inline virtual TInt SetBitRate(TUint aBitRate);
   1.850 +
   1.851 +	/**
   1.852 +	Returns the number of channels.
   1.853 +
   1.854 +	The default implementation returns 0.
   1.855 +
   1.856 +	@return The number of channels.
   1.857 +	*/
   1.858 +	virtual TUint NumChannels() {return 0;}
   1.859 +
   1.860 +	/**
   1.861 +	Returns the sample rate.
   1.862 +
   1.863 +	The default implementation returns 0.
   1.864 +
   1.865 +	@return The sample rate.
   1.866 +	*/
   1.867 +	virtual TUint SampleRate() {return 0;}
   1.868 +
   1.869 +	/**
   1.870 +	Returns the default sample rate.
   1.871 +
   1.872 +	The default returns 0.
   1.873 +
   1.874 +	@return The default sample rate.
   1.875 +	*/
   1.876 +	virtual TUint GetDefaultSampleRate() {return 0;}
   1.877 +
   1.878 +	/**
   1.879 +	Returns the bit rate.
   1.880 +
   1.881 +	The default returns 0.
   1.882 +
   1.883 +	@return The bit rate.
   1.884 +	*/
   1.885 +	virtual TUint BitRate() {return 0;}
   1.886 +
   1.887 +	/**
   1.888 +	Returns the bytes per second.
   1.889 +
   1.890 +	The default returns 0.
   1.891 +
   1.892 +	@return The bytes per second.
   1.893 +	*/
   1.894 +	virtual TInt64 BytesPerSecond() {return 0;}
   1.895 +
   1.896 +	/**
   1.897 +	Gets the supported sample rates.
   1.898 +
   1.899 +	The default implementation leaves with KErrNotSupported.
   1.900 +
   1.901 +	@param  aSampleRates
   1.902 +	        A reference to an array of supported sample rates.
   1.903 +	*/
   1.904 +	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
   1.905 +
   1.906 +	/**
   1.907 +	Gets the supported bit rates.
   1.908 +
   1.909 +	The default implementation leaves with KErrNotSupported.
   1.910 +
   1.911 +	@param  aBitRates
   1.912 +	        A reference to an array of supported bit rates.
   1.913 +	*/
   1.914 +	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
   1.915 +
   1.916 +	/**
   1.917 +	Gets the supported number of channels.
   1.918 +
   1.919 +	The default implementation leaves with KErrNotSupported.
   1.920 +
   1.921 +	@param  aNumChannels
   1.922 +	        A reference to an array of supported number of channels.
   1.923 +	*/
   1.924 +	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
   1.925 +
   1.926 +	/**
   1.927 +	Gets the supported data types for the given media type ID.
   1.928 +
   1.929 +	The default implementation leaves with KErrNotSupported.
   1.930 +
   1.931 +	@param  aMediaId
   1.932 +	        The media type id.
   1.933 +	@param  aDataTypes
   1.934 +	        A reference to an array of supported data types.
   1.935 +	*/
   1.936 +	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
   1.937 +
   1.938 +	/**
   1.939 +	Sets the maximum clip size.
   1.940 +
   1.941 +	The default implementation leaves with KErrNotSupported.
   1.942 +
   1.943 +	@param  aBytes
   1.944 +	        The maximum clip size.
   1.945 +	*/
   1.946 +	inline virtual void SetMaximumClipSizeL(TInt aBytes);
   1.947 +
   1.948 +	/**
   1.949 +	Returns the maximum clip size.
   1.950 +
   1.951 +	The default returns 0.
   1.952 +
   1.953 +	@return The maximum clip size.
   1.954 +	*/
   1.955 +	virtual TInt MaximumClipSize() { return 0;}
   1.956 +
   1.957 +	/**
   1.958 +	Used to set the format's position.
   1.959 +
   1.960 +	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
   1.961 +	setting to determine what data to provide.
   1.962 +
   1.963 +	The actual position the format sets itself may vary to this setting to ensure
   1.964 +	that it is aligned to the sample boundaries ensuring consistent data output.
   1.965 +
   1.966 +	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
   1.967 +
   1.968 +	@param  aPosition
   1.969 +	        The position the format should use.
   1.970 +	*/
   1.971 +    inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
   1.972 +
   1.973 +
   1.974 +	/**
   1.975 +	Supplies the current position.
   1.976 +
   1.977 +	Subsequent data reads will commence from this position.
   1.978 +
   1.979 +	@return The current position in microseconds.
   1.980 +	*/
   1.981 +	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
   1.982 +
   1.983 +
   1.984 +protected:
   1.985 +	//ConstructSourceL should never be called. The CMMFFormatEncode NewL functions should
   1.986 +	//always be used to instantiate a CMMFFormatEncode object (not MDataSource::NewL)
   1.987 +	/**
   1.988 +	@internalAll
   1.989 +	*/
   1.990 +	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   1.991 +	//ConstructSinkL should never be called. The CMMFFormatEncode NewL functions should
   1.992 +	//always be used to instantiate a CMMFFormatEncode object (not MDataSink::NewL)
   1.993 +	/**
   1.994 +	@internalAll
   1.995 +	*/
   1.996 +	virtual void ConstructSinkL(  const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
   1.997 +
   1.998 +	/**
   1.999 +	Default constructor
  1.1000 +	*/
  1.1001 +	CMMFFormatEncode() : MDataSource(KUidMmfFormatEncode), MDataSink(KUidMmfFormatEncode) {};
  1.1002 +
  1.1003 +	// Creates and initialises format plugin.
  1.1004 +	static CMMFFormatEncode* CreateFormatL(TUid aImplementationUid, MDataSink* aSink);
  1.1005 +protected:
  1.1006 +
  1.1007 +	/** 
  1.1008 +	The Data path is the source for the encode format.
  1.1009 +	*/
  1.1010 +	MDataSource* iDataPath;
  1.1011 +	
  1.1012 +	/** 
  1.1013 +	The clip is the sink for the encode format.
  1.1014 +	*/
  1.1015 +	MDataSink* iClip;
  1.1016 +private:
  1.1017 +	TUid iDtor_ID_Key;				// do not move - referenced inline in ~CMMFFormatDecode()
  1.1018 +	TUid iImplementationUid;		// do not move - referenced inline in ImplementationUid()
  1.1019 +	};
  1.1020 +
  1.1021 +
  1.1022 +class CMMFFormatPluginSelectionParameters;
  1.1023 +
  1.1024 +/**
  1.1025 +@publishedAll
  1.1026 +@released
  1.1027 +
  1.1028 +Provides an internal utility function to choose a format plugin from ECom.
  1.1029 +*/
  1.1030 +class MMFFormatEcomUtilities
  1.1031 +	{
  1.1032 +public:
  1.1033 +	//Internal utility function to choose a format plugin from ECOM
  1.1034 +	static TUid SelectFormatPluginL(const CMMFFormatPluginSelectionParameters& aSelectParams);
  1.1035 +
  1.1036 +	// Internal utility function to instantiate each format decode plugin in turn
  1.1037 +	// until we find one that works
  1.1038 +	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource);
  1.1039 +
  1.1040 +	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource, TBool& aSupportsCustomInterfaces);
  1.1041 +	};
  1.1042 +
  1.1043 +#include "mmfformat.inl"
  1.1044 +
  1.1045 +#endif