sl@0: // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #ifndef __MMF_SERVER_FORMAT_H__
sl@0: #define __MMF_SERVER_FORMAT_H__
sl@0: 
sl@0: #include <mmf/server/mmfdatasink.h>
sl@0: #include <mmf/server/mmfdatasource.h>
sl@0: #include <ecom/ecom.h>
sl@0: #include <mmf/plugin/mmfplugininterfaceuids.hrh>
sl@0: 
sl@0: const TUint KMMFFormatDefaultFrameSize = 0x1000;  //4K
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: Base class from which source formats can be derived from. The intended usage is for controllers that can support more
sl@0: 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
sl@0: that is the source of the actual data.
sl@0: 
sl@0: All CMMFFormatDecode plugin DLLs must include interface_uid = KMmfUidPluginInterfaceFormatDecode in their .rss files.
sl@0: */
sl@0: class CMMFFormatDecode : public CBase, public MDataSource, public MDataSink
sl@0: 	{
sl@0: public:
sl@0: 	// ECOM creation.
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( TUid aUid, MDataSource* aSource );
sl@0: 
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier ) ;
sl@0: 
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC& aFileName, MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( const TDesC8& aSourceHeader,  MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
sl@0: 	IMPORT_C static CMMFFormatDecode* NewL( MDataSource* aSource, const TDesC& aPreferredSupplier, TBool& aSupportsCustomInterfaces ) ;
sl@0: 
sl@0: 	/**
sl@0: 	Destructor.
sl@0: 	*/
sl@0: 	virtual ~CMMFFormatDecode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);};
sl@0: 
sl@0: 	/**
sl@0: 	Returns the ECom plugin UID of this format.
sl@0: 
sl@0: 	@return The plugin UID.
sl@0: 	*/
sl@0: 	TUid ImplementationUid() const {return iImplementationUid;}
sl@0: 
sl@0: 	/**
sl@0: 	Gets the number of streams of the specified media type.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaType
sl@0: 	        The UID of the media type, for example KUidMediaTypeAudio or KUidMediaTypeVideo.
sl@0: 
sl@0: 	@return	The number of streams of multimedia data in the format for the specified media type.
sl@0: 	        For example, for a WAV or mp3 audio file this procedure would return 1 for a media
sl@0: 	        type of audio and 0 for a media type of video. More complex multimedia formats (for
sl@0: 	        example AVI and mp4) can support multiple streams of both video and audio.
sl@0: 	*/
sl@0: 	virtual TUint Streams(TUid aMediaType) const = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the time interval for one frame for the specified media type.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	In the case of video, a frame would usually be one frame of video. In the case of
sl@0: 	audio, a frame may correspond to a frame of audio, if the particular audio data type
sl@0: 	is framed eg mp3. There are two definitions of a frame. A format frame, which may
sl@0: 	consist of several frames of a particular framed audio data type. This may be the case,
sl@0: 	for example for GSM610 (a low quality audio data type used in telephony) where a frame
sl@0: 	is only 65 bytes large. In this case a format frame consists of several GSM610 data type
sl@0: 	frames as passing the data out 65 bytes at a time would be inefficient. In the case of
sl@0: 	non-framed data such as pcm, a frame can be an arbitrary size determined by the format plugin.
sl@0: 
sl@0: 	@param  aMediaType
sl@0: 	        The media type id.
sl@0: 
sl@0: 	@return	The frame time interval
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Returns the duration of the clip for the specified media type.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaType
sl@0: 	        The media type ID.
sl@0: 
sl@0: 	@return The duration of the clip.
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Request from CMMFDataPath to fill the specified buffer.
sl@0: 	The CMMFFormat needs to break this down into one or more reads from the clip
sl@0: 	(from MDataSource - CMMFFormatDecode is a MDataSource to a CMMFDataPath consumer).
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	This method is the means by which data is obtained from the data source. aBuffer is
sl@0: 	the buffer that needs filling from the source data stream as identified by aMediaId. The
sl@0: 	format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()
sl@0: 	method. From this the format should be able to determine the actual position of the data on
sl@0: 	the data source. The technique here depends on the nature of the format. For a linear audio
sl@0: 	format, the position can be obtained by a simple calculation of the frame size, the header size
sl@0: 	and where appropriate the datatype.
sl@0: 
sl@0: 	For non-linear formats either an index table of frame number and location will need to be
sl@0: 	created in the NewL() or some form of approximating algorithm will be required. Some formats have
sl@0: 	an index table as part of the format e.g. AVI. If no random access is required then no index table
sl@0: 	is required, the format can keep track of the current read position and increment it on each access,
sl@0: 	and reset it if the frame number is reset to 0 or 1. Given that for non-linear i.e. variable bit rate
sl@0: 	formats, the size of the data read may vary from frame to frame, then the format should either set
sl@0: 	the request size of the buffer for the required frame or call the source's ReadBufferL() (either
sl@0: 	CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or CMMFFile::ReadBufferL()) function that
sl@0: 	takes the aLength parameter.
sl@0: 
sl@0: 	It is the responsibility of the format decode to determine the size and position of the source data
sl@0: 	for each frame. For linear audio formats, the format decode should fill the buffer up to its maximum
sl@0: 	length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively acting as a demultiplexor,
sl@0: 	and must obtain the appropriate data from the source depending on the aMediaId.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer to fill.
sl@0: 	@param  aConsumer
sl@0: 	        The consumer.
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 	*/
sl@0: 	virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId)=0;
sl@0: 
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 
sl@0: 	Indicates data has been added to the file.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The emptied buffer.
sl@0:     */
sl@0: 	inline virtual void BufferEmptiedL(CMMFBuffer* aBuffer);
sl@0: 
sl@0: 	/**
sl@0: 	Tests whether a source buffer can be created.
sl@0: 
sl@0: 	The format knows what type of source buffer it requires so default returns ETrue.
sl@0: 	It doesn't usually need to set the size of this buffer.
sl@0: 
sl@0: 	@return	A boolean indicating whether a buffer can be created. ETrue if the buffer can be created,
sl@0: 	        EFalse otherwise.
sl@0: 	*/
sl@0: 	virtual TBool CanCreateSourceBuffer() {return ETrue;}
sl@0: 
sl@0: 	/**
sl@0: 	Creates a source buffer.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	This function should create a buffer of length 0, the maximum length should be equal to the maximum
sl@0: 	possible frame size. In the case of non framed data it should be set to an arbitrary size, which is
sl@0: 	effectively a trade off between being too small which will affect performance as more source reads
sl@0: 	are required, and being too large which will give very coarse positioning granularity. For pcm data,
sl@0: 	a buffer size of 4K is a good compromise. The same compromise also applies when deciding to put multiple
sl@0: 	audio frames into one format frame. The sink buffer size may also effect the format buffer size and
sl@0: 	the controller may use this to suggest a buffer size to the format by calling the format's SuggestSourceBufferSize()
sl@0: 	method. Alternatively the MDataSource::CreateSourceBufferL() function that takes the additional aSinkBuffer
sl@0: 	parameter may also be used when deciding the source buffer maximum size of the created source buffer.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 	@param  aReference
sl@0: 	        If ETrue the MDataSource owns the buffer. If EFalse, then the caller owns the buffer. This
sl@0: 	        should normally be set to EFalse as format plugins do not create the reference buffer.
sl@0: 
sl@0: 	@return The created source buffer.
sl@0: 	*/
sl@0: 	virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the source data type code for the specified media type ID.
sl@0: 
sl@0: 	Used by the CMMFDataPath for codec matching.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 
sl@0: 	@return The source data type code.
sl@0: 	*/
sl@0: 	virtual TFourCC SourceDataTypeCode(TMediaId aMediaId)=0;
sl@0: 
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 
sl@0:     Adds a buffer to a clip.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer to which the clip is added.
sl@0: 	@param  aSupplier
sl@0: 	        The data source.
sl@0: 	@param  aMediaId
sl@0: 	        The Media ID.
sl@0: 	*/
sl@0: 	inline virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId);
sl@0: 
sl@0: 	/**
sl@0: 	Indicates the data source has filled the buffer.
sl@0: 
sl@0: 	Called by the CMMFFormat's MDataSource when it has filled the buffer.
sl@0: 	The default implementation below would need overriding in cases where multiple
sl@0: 	clip reads were required to fill the buffer from the data path.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer to which the clip is added.
sl@0: 	*/
sl@0: 	virtual void BufferFilledL(CMMFBuffer* aBuffer) {iDataPath->BufferFilledL(aBuffer);}
sl@0: 
sl@0: 	/**
sl@0: 	Tests whether a sink buffer can be created.
sl@0: 
sl@0: 	Format would normally pass its own buffer onto the CMMFClip, so
sl@0: 	this may not be required. The default returns EFalse.
sl@0: 
sl@0: 	@return A boolean indicating if the sink buffer can be created. ETrue if buffer can be created, EFalse otherwise.
sl@0: 	*/
sl@0: 	virtual TBool CanCreateSinkBuffer() {return EFalse;}
sl@0: 
sl@0: 	/**
sl@0: 	Creates a sink buffer for the specified media ID. The default version returns NULL.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 	@param  aReference
sl@0: 	        If ETrue the MDataSink owns the buffer.
sl@0: 	        If EFalse, then the caller owns the buffer.
sl@0: 	@return The CMMFBuffer sink buffer.
sl@0: 	*/
sl@0: 	inline virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the sink data type code for the specified media type ID.
sl@0: 	This would be the same as the source data type four CC although
sl@0: 	the clip is not going to need this info.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type id.
sl@0: 
sl@0: 	@return The sink data type code.
sl@0: 	*/
sl@0: 	inline virtual TFourCC SinkDataTypeCode(TMediaId aMediaId);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the number of meta data entries.
sl@0: 
sl@0: 	Meta Data support. The decode format is only capable of reading meta data entries from the clip.
sl@0: 
sl@0: 	This is an optional method, used to return the number of meta data entries present in the format.
sl@0: 	A meta data entry is a format-specific field such as authorship, copyright, security details etc.
sl@0: 	The function is optional as many formats do not provide support for such additional meta data fields.
sl@0: 
sl@0: 	The default leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aNumberOfEntries
sl@0: 	        A reference to the number of meta data entries supported by the format. On return, contains
sl@0: 	        the number of meta data entries.
sl@0: 	*/
sl@0: 	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the specified meta data entry.
sl@0: 
sl@0: 	This method is optional as many formats do not provide support for such additional meta data fields.
sl@0: 
sl@0: 	The default leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aIndex
sl@0: 	        The zero based meta data entry index to retrieve.
sl@0: 
sl@0: 	@return The meta data entry.
sl@0: 	*/
sl@0: 	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
sl@0: 
sl@0: 	//audio format methods
sl@0: 
sl@0: 	/**
sl@0: 	Sets the number of channels.
sl@0: 
sl@0: 	The default returns KErrNotSupported.
sl@0: 
sl@0: 	There would normally be no need to override this function as the format decode plugin can normally
sl@0: 	determine for itself the number of channels. It is only necessary to override this in cases where the
sl@0: 	format decode plugin cannot determine for itself the number of channels.  This function should not be
sl@0: 	used if the audio clip already exists; that is, in the "Open and Append" scenario, when the function's
sl@0: 	behaviour is undefined.
sl@0: 
sl@0: 	@param  aChannels
sl@0: 	        The number of channels.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0:             another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetNumChannels(TUint aChannels);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the sample rate.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	There would normally be no need to override this function as the format decode can normally determine
sl@0: 	the sample rate for itself. It is only necessary to override this in cases where the format decode plugin
sl@0: 	cannot determine for itself the sample rate.
sl@0: 
sl@0: 	@param  aSampleRate
sl@0: 	        The sample rate.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetSampleRate(TUint aSampleRate);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the bit rate.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can
sl@0: 	not be directly calculated from the sample rate. There would normally be no need to override this
sl@0: 	function as the format decode can normally determine the sample rate for itself. It is only necessary
sl@0: 	to override this in cases where the format decode plugin cannot determine for itself the sample rate.
sl@0: 
sl@0: 	@param aBitRate
sl@0: 	       The bit rate in bits per second.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetBitRate(TUint aBitRate);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the number of channels.
sl@0: 
sl@0: 	The default implementation returns 0.
sl@0: 
sl@0: 	@return	The number of channels.
sl@0: 	*/
sl@0: 	virtual TUint NumChannels() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Gets the sample rate.
sl@0: 
sl@0: 	The default implementation returns 0.
sl@0: 
sl@0: 	@return The sample rate.
sl@0: 	*/
sl@0: 	virtual TUint SampleRate() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Gets the bit rate.
sl@0: 
sl@0: 	The default implementation returns 0.
sl@0: 
sl@0: 	This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate 
sl@0: 	can not be directly calculated from the sample rate. This function needs overriding for any format 
sl@0: 	decode that supports audio.
sl@0: 
sl@0: 	@return The bit rate.
sl@0: 	*/
sl@0: 	virtual TUint BitRate() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported sample rates.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	This should return an array of sample rates supported by the format where applicable. Note 
sl@0: 	that this refers to the possible sample rates supported by the format, not the actual sample rate,
sl@0: 	which will be one of the supported sample rates. The implementation of this function is optional.
sl@0: 
sl@0: 	@param  aSampleRates
sl@0: 	        Reference to an array of supported sample rates.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported bit rates.
sl@0: 
sl@0: 	The default leaves with KErrNotSupported.
sl@0: 
sl@0: 	This should return an array of bit rates supported by the format where applicable. Note that this
sl@0: 	refers to the possible bit rates supported by the format, not the actual bit rate, which will be
sl@0: 	one of the supported bit rates. The implementation of this function is optional.
sl@0: 
sl@0: 	@param  aBitRates
sl@0: 	        Reference to an array of supported bit rates.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported number of channels.
sl@0: 
sl@0: 	The default leaves with KErrNotSupported.
sl@0: 
sl@0: 	The implementation of this procedure should return an array of channels supported by the format
sl@0: 	where applicable. Note that this refers to the possible number of channels supported by the format,
sl@0: 	not the actual number of channels, which will be one of the supported channels. For example, for a
sl@0: 	format decode plugin capable of supporting mono and stereo the procedure would return an array of
sl@0: 	length two the first array member containing the value 1 and the second containing the value 2. The
sl@0: 	implementation of this function is optional.
sl@0: 
sl@0: 	@param  aNumChannels
sl@0: 	        A reference to an array of supported number of channels.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported data types for the given media type id.
sl@0: 
sl@0: 	The default leaves with KErrNotSupported.
sl@0: 
sl@0:     The implementation of this procedure should return an array of data types supported by the format where
sl@0: 	applicable. Note that this refers to the possible data types that may be supported by the format, not the
sl@0: 	actual data type of the format, which will be one of the supported data types. For example, for a format
sl@0: 	decode plugin capable of supporting pcm16 and GSM610 the procedure would return an array of length two the
sl@0: 	first array member containing the fourCC code ' P16' and the second containing the value GSM6. The
sl@0: 	implementation of this function is optional.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type id.
sl@0: 	@param  aDataTypes
sl@0: 	        A reference to an array of supported data types.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
sl@0: 
sl@0: 	/**
sl@0: 	Used by the sink to suggest a source buffer size.
sl@0: 
sl@0: 	This is an optional function provided so that a controller can suggest a buffer
sl@0: 	size for the format. The controller should not assume that the format will accept
sl@0: 	the suggested buffer size and there is no obligation on behalf of the format to
sl@0: 	use the suggested buffer size.
sl@0: 
sl@0: 	@param  aSuggestedBufferSize
sl@0: 	        A recommended buffer size that the format should create.
sl@0: 	*/
sl@0: 	inline virtual void SuggestSourceBufferSize(TUint aSuggestedBufferSize);
sl@0: 
sl@0: 	/**
sl@0: 	Used to set the format's position.
sl@0: 
sl@0: 	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
sl@0: 	setting to determine what data to provide.
sl@0: 
sl@0: 	The actual position the format sets itself may vary from this setting to ensure
sl@0: 	that it is aligned to the sample boundaries ensuring consistent data output.
sl@0: 
sl@0: 	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
sl@0: 
sl@0: 	@param  aPosition
sl@0: 	        The position the format should use.
sl@0: 	*/
sl@0:     inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Supplies the current position.
sl@0: 
sl@0: 	Subsequent data reads will commence from this position.
sl@0: 
sl@0: 	@return The current position in microseconds.
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
sl@0: 	
sl@0: protected:
sl@0: 	//ConstructSourceL should never be called. The CMMFFormatDecode NewL functions should
sl@0: 	//always be used to instantiate a CMMFFormatDecode object (not MDataSource::NewL)
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 	*/
sl@0: 	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
sl@0: 
sl@0: 	//ConstructSinkL should never be called. The CMMFFormatDecode NewL functions should
sl@0: 	//always be used to instantiate a CMMFFormatDecode object (not MDataSink::NewL)
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 	*/
sl@0: 	virtual void ConstructSinkL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
sl@0: 
sl@0: 	/**
sl@0: 	Default constructor
sl@0: 	*/
sl@0: 	CMMFFormatDecode() : MDataSource(KUidMmfFormatDecode), MDataSink(KUidMmfFormatDecode) {};
sl@0: 
sl@0: 	// Creates and initialises format plugin.
sl@0: 	static CMMFFormatDecode* CreateFormatL(TUid aImplementationUid, MDataSource* aSource);
sl@0: protected:
sl@0: 
sl@0: 	/**
sl@0: 	The clip is the source for the decode format.
sl@0: 	*/
sl@0: 	MDataSource* iClip;
sl@0: 
sl@0: 	/** 
sl@0: 	The data path is the sink for the decode format.
sl@0: 	*/
sl@0: 	MDataSink* iDataPath;
sl@0: private:
sl@0: 	TUid iDtor_ID_Key; 			// do not move - referenced inline in ~CMMFFormatDecode()
sl@0: 	TUid iImplementationUid;	// do not move - referenced inline in ImplementationUid()
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: Extension class to allow derived classes to support custom interfaces
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: class CMMFFormatDecode2 : public CMMFFormatDecode
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Gets a custom interface.
sl@0: 
sl@0: 	@param aInterfaceId
sl@0: 			The Uid of the particular interface required.
sl@0:  
sl@0: 	@return Custom interface pointer. NULL if the requested interface is not supported.
sl@0: 	*/
sl@0: 	virtual TAny* CustomInterface(TUid aInterfaceId)=0;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: Base class from which sink formats can be derived from.   
sl@0: 
sl@0: The intended usage is for controllers that can support more than one type of format.
sl@0: The class is an MDataSink as far as the data path is concerned but is an MDataSource to the clip
sl@0: that is the sink of the actual data. All CMMFFormatEncode plugin DLLs must include 
sl@0: interface_uid = KMmfUidPluginInterfaceFormatEncode in their .rss files.
sl@0: */
sl@0: class CMMFFormatEncode : public CBase, public MDataSource, public MDataSink
sl@0: 	{
sl@0: public:
sl@0: 	// ECOM creation.
sl@0: 	IMPORT_C static CMMFFormatEncode* NewL( TUid aUid, MDataSink* aSink );
sl@0: 	IMPORT_C static CMMFFormatEncode* NewL( const TDesC& aFileName, MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
sl@0: 	IMPORT_C static CMMFFormatEncode* NewL( const TDesC8& aSourceHeader,  MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
sl@0: 	IMPORT_C static CMMFFormatEncode* NewL( MDataSink* aSink, const TDesC& aPreferredSupplier ) ;
sl@0: 
sl@0: 	/**
sl@0: 	Destructor.
sl@0: 	*/
sl@0: 	virtual ~CMMFFormatEncode()  {REComSession::DestroyedImplementation(iDtor_ID_Key);}
sl@0: 
sl@0: 	// returns ECOM plugin uid of this format
sl@0: 	/**
sl@0: 	Gets the ECom plugin UID of this format.
sl@0: 	
sl@0: 	@return The plugin UID.
sl@0: 	*/
sl@0: 	TUid ImplementationUid() const {return iImplementationUid;}
sl@0: 
sl@0: 	/**
sl@0: 	Returns the time interval for one frame for the specified media type.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaType
sl@0: 	        The media type ID.
sl@0: 	@return The frame time interval in microseconds.
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the duration of the sink clip for the specified media type.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaType
sl@0: 	        The media type ID.
sl@0: 	
sl@0: 	@return The duration of the sink clip.
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const = 0;
sl@0: 
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 	
sl@0: 	Request from CMMFDataPath to fill the specified buffer.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer to fill.
sl@0: 	@param  aConsumer
sl@0: 	        The consumer.
sl@0: 	@param  aMediaId
sl@0: 	        The media ID.
sl@0: 	*/
sl@0: 	inline virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer, TMediaId aMediaId);
sl@0: 
sl@0: 	/**
sl@0: 	Called by the clip when it has added the data to the file.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The emptied buffer.
sl@0: 	*/
sl@0: 	virtual void BufferEmptiedL(CMMFBuffer* aBuffer) {iDataPath->BufferEmptiedL(aBuffer);}
sl@0: 
sl@0: 	/**
sl@0: 	Tests whether a source buffer can be created.
sl@0: 
sl@0: 	The default implementation returns EFalse.
sl@0: 
sl@0: 	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
sl@0: 	*/
sl@0: 	virtual TBool CanCreateSourceBuffer() {return EFalse;}
sl@0: 
sl@0: 	/**
sl@0: 	Creates a source buffer. The default returns NULL.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type id.
sl@0: 	@param  aReference
sl@0: 	        If ETrue the MDataSource owns the buffer.
sl@0: 	        If EFalse, then the caller owns the buffer.
sl@0: 
sl@0: 	@return	Source buffer.
sl@0: 	*/
sl@0: 	inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the source data type code for the specified media type ID.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type id.
sl@0: 
sl@0: 	@return The source data type code.
sl@0: 	*/
sl@0: 	inline virtual TFourCC SourceDataTypeCode(TMediaId aMediaId);
sl@0: 
sl@0: 	/**
sl@0: 	Adds a buffer to a clip.
sl@0: 
sl@0: 	Called by CMMFDataPath.
sl@0: 	(from MDataSink - CMMFFormatEncode is a MDataSink to a CMMFDataPath)
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer to which the clip is added.
sl@0: 	@param  aSupplier
sl@0: 	        The data source.
sl@0: 	@param	aMediaId
sl@0: 	        The media type ID.
sl@0: 	*/
sl@0: 	virtual void EmptyBufferL(CMMFBuffer* aBuffer, MDataSource* aSupplier, TMediaId aMediaId)=0;
sl@0: 
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 
sl@0: 	Called by the CMMFDataPath's MDataSource when it has filled the buffer.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 	        The buffer that has been filled.
sl@0: 	*/
sl@0: 	inline virtual void BufferFilledL(CMMFBuffer* aBuffer);
sl@0: 
sl@0: 	/**
sl@0: 	Tests whether a sink buffer can be created.
sl@0: 
sl@0: 	Format would normally pass its own buffer onto the CMMFClip, so
sl@0: 	this may not be required. The default returns ETrue.
sl@0: 
sl@0: 	@return	A boolean indicating if the buffer can be created. ETrue if buffer can be created, EFalse otherwise.
sl@0: 	*/
sl@0: 	virtual TBool CanCreateSinkBuffer() {return ETrue;}
sl@0: 
sl@0: 	/**
sl@0: 	Creates a sink buffer for the specified media ID.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 	@param  aReference
sl@0: 	        If ETrue then MDataSink owns the buffer.
sl@0: 	        If EFalse, then the caller owns the buffer.
sl@0: 
sl@0: 	@return A pointer to the CMMFBuffer sink buffer.
sl@0: 	*/
sl@0: 	virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the sink data type code for the specified media type ID.
sl@0: 
sl@0: 	This would be the same as the source data type four CC although the clip
sl@0: 	is not going to need this info.
sl@0: 
sl@0: 	This is a virtual function that each derived class must implement.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type ID.
sl@0: 
sl@0: 	@return The sink data type code.
sl@0: 	*/
sl@0: 	virtual TFourCC SinkDataTypeCode(TMediaId aMediaId) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	This function is used to truncate the sink ie. a CMMFClip,
sl@0: 
sl@0: 	If aToEnd = ETrue the sink is cropped from the aPosition to the	end of the clip.
sl@0: 	If aToEnd = EFalse then the sink is cropped from the start of the clip to aPosition.
sl@0: 
sl@0: 	This function would be called by the CMMFController. The default implementation leaves
sl@0: 	with KErrNotSupported.
sl@0: 
sl@0: 	@param  aPosition
sl@0: 	        The position within the clip.
sl@0: 	@param  aToEnd
sl@0: 	        Flag to determine which part of the clip to delete.
sl@0: 	*/
sl@0: 	inline virtual void CropL(TTimeIntervalMicroSeconds aPosition, TBool aToEnd = ETrue);
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Gets the number of meta data entries.
sl@0: 
sl@0: 	The encode format is capable of reading and writing meta data to the clip.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aNumberOfEntries
sl@0: 	        On return, contains the number of meta data entries.
sl@0: 	*/
sl@0: 	inline virtual void GetNumberOfMetaDataEntriesL(TInt& aNumberOfEntries);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the specified meta data entry.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aIndex
sl@0: 	        The zero based meta data entry index to retrieve.
sl@0: 
sl@0: 	@return The meta data entry.
sl@0: 	*/
sl@0: 	inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);
sl@0: 
sl@0: 	/**
sl@0: 	Adds the specified meta data entry to the clip.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aNewEntry
sl@0: 	        The meta data entry to add.
sl@0: 	*/
sl@0: 	inline virtual void AddMetaDataEntryL(const CMMFMetaDataEntry& aNewEntry);
sl@0: 
sl@0: 	/**
sl@0: 	Removes the specified meta data entry.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	@param  aIndex
sl@0: 	        The zero based meta data entry index to remove.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	 */
sl@0: 	inline virtual TInt RemoveMetaDataEntry(TInt aIndex);
sl@0: 
sl@0: 	/**
sl@0: 	Replaces the specified meta data entry with the entry supplied in aNewEntry.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aIndex
sl@0: 	        The zero based meta data entry index to replace.
sl@0: 	@param  aNewEntry
sl@0: 	        The meta data entry to replace.
sl@0: 	*/
sl@0: 	inline virtual void ReplaceMetaDataEntryL(TInt aIndex, const CMMFMetaDataEntry& aNewEntry);
sl@0: 
sl@0: 	//audio format methods
sl@0: 
sl@0: 	/**
sl@0: 	Sets the number of channels.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	@param  aChannels
sl@0: 	        The number of channels.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetNumChannels(TUint aChannels);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the sample rate.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	@param  aSampleRate
sl@0: 	        The sample rate.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetSampleRate(TUint aSampleRate);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the bit rate.
sl@0: 
sl@0: 	The default implementation returns KErrNotSupported.
sl@0: 
sl@0: 	@param  aBitRate
sl@0: 	        The bit rate.
sl@0: 
sl@0: 	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
sl@0: 	        another of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline virtual TInt SetBitRate(TUint aBitRate);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the number of channels.
sl@0: 
sl@0: 	The default implementation returns 0.
sl@0: 
sl@0: 	@return The number of channels.
sl@0: 	*/
sl@0: 	virtual TUint NumChannels() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Returns the sample rate.
sl@0: 
sl@0: 	The default implementation returns 0.
sl@0: 
sl@0: 	@return The sample rate.
sl@0: 	*/
sl@0: 	virtual TUint SampleRate() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Returns the default sample rate.
sl@0: 
sl@0: 	The default returns 0.
sl@0: 
sl@0: 	@return The default sample rate.
sl@0: 	*/
sl@0: 	virtual TUint GetDefaultSampleRate() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Returns the bit rate.
sl@0: 
sl@0: 	The default returns 0.
sl@0: 
sl@0: 	@return The bit rate.
sl@0: 	*/
sl@0: 	virtual TUint BitRate() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Returns the bytes per second.
sl@0: 
sl@0: 	The default returns 0.
sl@0: 
sl@0: 	@return The bytes per second.
sl@0: 	*/
sl@0: 	virtual TInt64 BytesPerSecond() {return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported sample rates.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aSampleRates
sl@0: 	        A reference to an array of supported sample rates.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedSampleRatesL(RArray<TUint>& aSampleRates);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported bit rates.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aBitRates
sl@0: 	        A reference to an array of supported bit rates.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedBitRatesL(RArray<TUint>& aBitRates);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported number of channels.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aNumChannels
sl@0: 	        A reference to an array of supported number of channels.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedNumChannelsL(RArray<TUint>& aNumChannels);
sl@0: 
sl@0: 	/**
sl@0: 	Gets the supported data types for the given media type ID.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aMediaId
sl@0: 	        The media type id.
sl@0: 	@param  aDataTypes
sl@0: 	        A reference to an array of supported data types.
sl@0: 	*/
sl@0: 	inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray<TFourCC>& aDataTypes);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the maximum clip size.
sl@0: 
sl@0: 	The default implementation leaves with KErrNotSupported.
sl@0: 
sl@0: 	@param  aBytes
sl@0: 	        The maximum clip size.
sl@0: 	*/
sl@0: 	inline virtual void SetMaximumClipSizeL(TInt aBytes);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the maximum clip size.
sl@0: 
sl@0: 	The default returns 0.
sl@0: 
sl@0: 	@return The maximum clip size.
sl@0: 	*/
sl@0: 	virtual TInt MaximumClipSize() { return 0;}
sl@0: 
sl@0: 	/**
sl@0: 	Used to set the format's position.
sl@0: 
sl@0: 	Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this
sl@0: 	setting to determine what data to provide.
sl@0: 
sl@0: 	The actual position the format sets itself may vary to this setting to ensure
sl@0: 	that it is aligned to the sample boundaries ensuring consistent data output.
sl@0: 
sl@0: 	If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer
sl@0: 
sl@0: 	@param  aPosition
sl@0: 	        The position the format should use.
sl@0: 	*/
sl@0:     inline virtual void SetPositionL(const TTimeIntervalMicroSeconds& aPosition);
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Supplies the current position.
sl@0: 
sl@0: 	Subsequent data reads will commence from this position.
sl@0: 
sl@0: 	@return The current position in microseconds.
sl@0: 	*/
sl@0: 	virtual TTimeIntervalMicroSeconds PositionL() {User::Leave(KErrNotSupported);return TTimeIntervalMicroSeconds(0);}
sl@0: 
sl@0: 
sl@0: protected:
sl@0: 	//ConstructSourceL should never be called. The CMMFFormatEncode NewL functions should
sl@0: 	//always be used to instantiate a CMMFFormatEncode object (not MDataSource::NewL)
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 	*/
sl@0: 	virtual void ConstructSourceL( const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
sl@0: 	//ConstructSinkL should never be called. The CMMFFormatEncode NewL functions should
sl@0: 	//always be used to instantiate a CMMFFormatEncode object (not MDataSink::NewL)
sl@0: 	/**
sl@0: 	@internalAll
sl@0: 	*/
sl@0: 	virtual void ConstructSinkL(  const TDesC8& /*aInitData*/ ) {User::Leave(KErrNotSupported);}
sl@0: 
sl@0: 	/**
sl@0: 	Default constructor
sl@0: 	*/
sl@0: 	CMMFFormatEncode() : MDataSource(KUidMmfFormatEncode), MDataSink(KUidMmfFormatEncode) {};
sl@0: 
sl@0: 	// Creates and initialises format plugin.
sl@0: 	static CMMFFormatEncode* CreateFormatL(TUid aImplementationUid, MDataSink* aSink);
sl@0: protected:
sl@0: 
sl@0: 	/** 
sl@0: 	The Data path is the source for the encode format.
sl@0: 	*/
sl@0: 	MDataSource* iDataPath;
sl@0: 	
sl@0: 	/** 
sl@0: 	The clip is the sink for the encode format.
sl@0: 	*/
sl@0: 	MDataSink* iClip;
sl@0: private:
sl@0: 	TUid iDtor_ID_Key;				// do not move - referenced inline in ~CMMFFormatDecode()
sl@0: 	TUid iImplementationUid;		// do not move - referenced inline in ImplementationUid()
sl@0: 	};
sl@0: 
sl@0: 
sl@0: class CMMFFormatPluginSelectionParameters;
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: Provides an internal utility function to choose a format plugin from ECom.
sl@0: */
sl@0: class MMFFormatEcomUtilities
sl@0: 	{
sl@0: public:
sl@0: 	//Internal utility function to choose a format plugin from ECOM
sl@0: 	static TUid SelectFormatPluginL(const CMMFFormatPluginSelectionParameters& aSelectParams);
sl@0: 
sl@0: 	// Internal utility function to instantiate each format decode plugin in turn
sl@0: 	// until we find one that works
sl@0: 	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource);
sl@0: 
sl@0: 	static CMMFFormatDecode* SelectFormatDecodePluginL(const CMMFFormatPluginSelectionParameters& aSelectParams, MDataSource* aSource, TBool& aSupportsCustomInterfaces);
sl@0: 	};
sl@0: 
sl@0: #include <mmf/server/mmfformat.inl>
sl@0: 
sl@0: 
sl@0: #endif
sl@0: