Class CMMFFormatDecode

class CMMFFormatDecode : public CBase, public MDataSource, public MDataSink;

Description

Base class from which source formats can be derived from. The intended usage is for controllers that can support more 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 that is the source of the actual data.

All CMMFFormatDecode plugin DLLs must include interface_uid = KMmfUidPluginInterfaceFormatDecode in their .rss files.

Derivation

• MDataSink - Abstract class representing a data sink.
• MDataSource - Abstract class representing a data source.
• CBase - Base class for all classes to be instantiated on the heap.

• CMMFFormatDecode - ...

Members

Defined in CMMFFormatDecode:

• BitRate()Gets the bit rate.
• BufferFilledL(CMMFBuffer *)Indicates the data source has filled the buffer.
• CMMFFormatDecode()Default constructor
• CanCreateSinkBuffer()Tests whether a sink buffer can be created.
• CanCreateSourceBuffer()Tests whether a source buffer can be created.
• CreateSinkBufferL(TMediaId,TBool &)Creates a sink buffer for the specified media ID. The default version returns NU...
• CreateSourceBufferL(TMediaId,TBool &)Creates a source buffer.
• Duration(TMediaId)constReturns the duration of the clip for the specified media type.
• FillBufferL(CMMFBuffer *,MDataSink *,TMediaId)Request from CMMFDataPath to fill the specified buffer. The CMMFFormat needs to ...
• FrameTimeInterval(TMediaId)constReturns the time interval for one frame for the specified media type.
• GetNumberOfMetaDataEntriesL(TInt &)Gets the number of meta data entries.
• GetSupportedBitRatesL(RArray< TUint > &)Gets the supported bit rates.
• GetSupportedDataTypesL(TMediaId,RArray< TFourCC > &)Gets the supported data types for the given media type id.
• GetSupportedNumChannelsL(RArray< TUint > &)Gets the supported number of channels.
• GetSupportedSampleRatesL(RArray< TUint > &)Gets the supported sample rates.
• ImplementationUid()constReturns the ECom plugin UID of this format.
• MetaDataEntryL(TInt)Returns the specified meta data entry.
• NewL(MDataSource *,const TDesC &)Attempts to locate and instantiate a CMMFFormatDecode using data from MDataSourc...
• NewL(MDataSource *,const TDesC &,TBool &)Attempts to locate and instantiate a CMMFFormatDecode using data from MDataSourc...
• NewL(TUid,MDataSource *)Allocates and constructs an ECom format decode object.
• NewL(const TDesC &,MDataSource *,const TDesC &)
• NewL(const TDesC &,MDataSource *,const TDesC &,TBool &)
• NewL(const TDesC8 &,MDataSource *,const TDesC &)Attempts to locate and instantiate a CMMFFormatDecode using data in a buffer. Th...
• NewL(const TDesC8 &,MDataSource *,const TDesC &,TBool &)Attempts to locate and instantiate a CMMFFormatDecode using data in a buffer. Th...
• NumChannels()Returns the number of channels.
• PositionL()Supplies the current position.
• SampleRate()Gets the sample rate.
• SetBitRate(TUint)Sets the bit rate.
• SetNumChannels(TUint)Sets the number of channels.
• SetPositionL(const TTimeIntervalMicroSeconds &)Used to set the format's position.
• SetSampleRate(TUint)Sets the sample rate.
• SinkDataTypeCode(TMediaId)Returns the sink data type code for the specified media type ID. This would be t...
• SourceDataTypeCode(TMediaId)Returns the source data type code for the specified media type ID.
• Streams(TUid)constGets the number of streams of the specified media type.
• SuggestSourceBufferSize(TUint)Used by the sink to suggest a source buffer size.
• iClipThe clip is the source for the decode format.
• iDataPathThe data path is the sink for the decode format.
• ~CMMFFormatDecode()Destructor.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from MDataSink:

• ConstructSinkL(const TDesC8 &)Performs any sink construction dependant on the sink construction initialisation...
• DataSinkType()constReturns the UID identifying the type of data sink.
• EmptyBufferL(CMMFBuffer *,MDataSource *,TMediaId)Method called by a MDataSource to request the data sink to empty aBuffer of data...
• MDataSink(TUid)Protected constructor.
• NegotiateL(MDataSource &)Allows the data sink to negotiate with a data source.
• NewSinkL(TUid,const TDesC8 &)Instantiates a new data sink.
• SetSinkDataTypeCode(TFourCC,TMediaId)Sets the data type as a fourCC code for the data sink.
• SetSinkPrioritySettings(const TMMFPrioritySettings &)Sets the sink priority settings.
• SinkCustomCommand(TMMFMessage &)Calls a sink specific custom command.
• SinkPauseL()Function to 'pause' the data sink.
• SinkPlayL()Function 'play' the data sink.
• SinkPrimeL()Function to 'prime' the data sink.
• SinkStopL()Function to 'stop' the data sink.
• SinkThreadLogoff()Function to 'logoff' the data sink from the same thread that sink consumes data ...
• SinkThreadLogon(MAsyncEventHandler &)Function to 'logon' the data sink to the same thread that sink will be consuming...

Inherited from MDataSource:

• BufferEmptiedL(CMMFBuffer *)Function called by a data sink to pass back an emptied buffer to the source.
• ConstructSourceL(const TDesC8 &)Performs any source construction dependant on the source construction initialisa...
• CreateSourceBufferL(TMediaId,CMMFBuffer &,TBool &)Returns a buffer created by the data source.
• DataSourceType()constReturns the UID identifying the type of data source.
• MDataSource(TUid)Protected constructor.
• NegotiateSourceL(MDataSink &)Function to allow the data source to negotiate with a data sink
• NewSourceL(TUid,const TDesC8 &)Instantiates a data source.
• SetSourceDataTypeCode(TFourCC,TMediaId)Sets the data type as a fourCC code for the data source.
• SetSourcePrioritySettings(const TMMFPrioritySettings &)Function to set the source priority settings.
• SourceCustomCommand(TMMFMessage &)Function to call a source specific custom command.
• SourcePauseL()Function to 'pause' the data source.
• SourcePlayL()Function to 'play' the data source.
• SourcePrimeL()Function to 'prime' the data source.
• SourceSampleConvert()Indicates whether the data source supports sample rate conversion.
• SourceStopL()Function to 'stop' the data source.
• SourceThreadLogoff()Function to 'logoff' the data source from the same thread that source supplies d...
• SourceThreadLogon(MAsyncEventHandler &)Function to 'logon' the data source to the same thread that source will be suppl...

IMPORT_C static CMMFFormatDecode* NewL(TUid aUid, MDataSource *aSource);

Description

Allocates and constructs an ECom format decode object.

This is used to explicitly instantiate a format decoder where the UID is known. This method might be used by controllers that only support one type of format such that the UID of the format is already known. For example, if an mp3 controller has been instantiated, there is no need for any further format recognition as this has already been performed in the controller instantiation, thus the controller can instantiate an mp3 format directly from it’s UID.

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(const TDesC &aFileName, MDataSource *aSource, const TDesC &aPreferredSupplier);

Description

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(const TDesC8 &aSourceHeader, MDataSource *aSource, const TDesC &aPreferredSupplier);

Description

Attempts to locate and instantiate a CMMFFormatDecode using data in a buffer. The buffer is expected to contain header data (from a file, stream or descriptor).

Signatures (supplied by the plugin registry information) are sought in aSourceHeader.

This function uses the match string as a resolver parameter. The format base class uses the match string to find a match to the match string defined in the opaque_data field of the resource file. The match string would typically be a signature for a particular format usually defined in the format header.

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(MDataSource *aSource, const TDesC &aPreferredSupplier);

Description

Attempts to locate and instantiate a CMMFFormatDecode using data from MDataSource.

The data is expected to contain header data (from a file, stream or descriptor). Signatures (supplied by the plugin registry information) are sought in aSource.

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(const TDesC &aFileName, MDataSource *aSource, const TDesC &aPreferredSupplier, TBool &aSupportsCustomInterfaces);

Description

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(const TDesC8 &aSourceHeader, MDataSource *aSource, const TDesC &aPreferredSupplier, TBool &aSupportsCustomInterfaces);

Description

Attempts to locate and instantiate a CMMFFormatDecode using data in a buffer. The buffer is expected to contain header data (from a file, stream or descriptor).

Signatures (supplied by the plugin registry information) are sought in aSourceHeader.

This function uses the match string as a resolver parameter. The format base class uses the match string to find a match to the match string defined in the opaque_data field of the resource file. The match string would typically be a signature for a particular format usually defined in the format header.

Parameters

Return value

IMPORT_C static CMMFFormatDecode* NewL(MDataSource *aSource, const TDesC &aPreferredSupplier, TBool &aSupportsCustomInterfaces);

Description

Attempts to locate and instantiate a CMMFFormatDecode using data from MDataSource.

The data is expected to contain header data (from a file, stream or descriptor). Signatures (supplied by the plugin registry information) are sought in aSource.

Parameters

Return value

inline virtual ~CMMFFormatDecode();

Description

Destructor.

protected: inline CMMFFormatDecode();

Description

Default constructor

inline TUid ImplementationUid() const;

Description

Returns the ECom plugin UID of this format.

Return value

virtual TUint Streams(TUid aMediaType) const=0;

Description

Gets the number of streams of the specified media type.

This is a virtual function that each derived class must implement.

Parameters

Return value

virtual TTimeIntervalMicroSeconds FrameTimeInterval(TMediaId aMediaType) const=0;

Description

Returns the time interval for one frame for the specified media type.

This is a virtual function that each derived class must implement.

In the case of video, a frame would usually be one frame of video. In the case of audio, a frame may correspond to a frame of audio, if the particular audio data type is framed eg mp3. There are two definitions of a frame. A format frame, which may consist of several frames of a particular framed audio data type. This may be the case, for example for GSM610 (a low quality audio data type used in telephony) where a frame is only 65 bytes large. In this case a format frame consists of several GSM610 data type frames as passing the data out 65 bytes at a time would be inefficient. In the case of non-framed data such as pcm, a frame can be an arbitrary size determined by the format plugin.

Parameters

Return value

virtual TTimeIntervalMicroSeconds Duration(TMediaId aMediaType) const=0;

Description

Returns the duration of the clip for the specified media type.

This is a virtual function that each derived class must implement.

Parameters

Return value

virtual void FillBufferL(CMMFBuffer *aBuffer, MDataSink *aConsumer, TMediaId aMediaId)=0;

Description

Request from CMMFDataPath to fill the specified buffer. The CMMFFormat needs to break this down into one or more reads from the clip (from MDataSource - CMMFFormatDecode is a MDataSource to a CMMFDataPath consumer).

This is a virtual function that each derived class must implement.

This method is the means by which data is obtained from the data source. aBuffer is the buffer that needs filling from the source data stream as identified by aMediaId. The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber()const method. From this the format should be able to determine the actual position of the data on the data source. The technique here depends on the nature of the format. For a linear audio format, the position can be obtained by a simple calculation of the frame size, the header size and where appropriate the datatype.

For non-linear formats either an index table of frame number and location will need to be created in the CMMFFormatDecode::NewL(TUid,MDataSource *) or some form of approximating algorithm will be required. Some formats have an index table as part of the format e.g. AVI. If no random access is required then no index table is required, the format can keep track of the current read position and increment it on each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear i.e. variable bit rate formats, the size of the data read may vary from frame to frame, then the format should either set the request size of the buffer for the required frame or call the source's ReadBufferL() (either CMMFClip::ReadBufferL(TInt,CMMFBuffer *,TInt,MDataSink *), CMMFDescriptor ::ReadBufferL() or CMMFFile::ReadBufferL(TInt,CMMFBuffer *,TInt,MDataSink *)) function that takes the aLength parameter.

It is the responsibility of the format decode to determine the size and position of the source data for each frame. For linear audio formats, the format decode should fill the buffer up to its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively acting as a demultiplexor, and must obtain the appropriate data from the source depending on the aMediaId.

Parameters

inline virtual TBool CanCreateSourceBuffer();

Description

Tests whether a source buffer can be created.

The format knows what type of source buffer it requires so default returns ETrue. It doesn't usually need to set the size of this buffer.

Return value

virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference)=0;

Description

Creates a source buffer.

This is a virtual function that each derived class must implement.

This function should create a buffer of length 0, the maximum length should be equal to the maximum possible frame size. In the case of non framed data it should be set to an arbitrary size, which is effectively a trade off between being too small which will affect performance as more source reads are required, and being too large which will give very coarse positioning granularity. For pcm data, a buffer size of 4K is a good compromise. The same compromise also applies when deciding to put multiple audio frames into one format frame. The sink buffer size may also effect the format buffer size and the controller may use this to suggest a buffer size to the format by calling the format's CMMFFormatDecode::SuggestSourceBufferSize(TUint) method. Alternatively the MDataSource::CreateSourceBufferL(TMediaId,TBool &) function that takes the additional aSinkBuffer parameter may also be used when deciding the source buffer maximum size of the created source buffer.

Parameters

Return value

virtual TFourCC SourceDataTypeCode(TMediaId aMediaId)=0;

Description

Returns the source data type code for the specified media type ID.

Used by the CMMFDataPath for codec matching.

This is a virtual function that each derived class must implement.

Parameters

Return value

inline virtual void BufferFilledL(CMMFBuffer *aBuffer);

Description

Indicates the data source has filled the buffer.

Called by the CMMFFormat's MDataSource when it has filled the buffer. The default implementation below would need overriding in cases where multiple clip reads were required to fill the buffer from the data path.

Parameters

inline virtual TBool CanCreateSinkBuffer();

Description

Tests whether a sink buffer can be created.

Format would normally pass its own buffer onto the CMMFClip, so this may not be required. The default returns EFalse.

Return value

inline virtual CMMFBuffer* CreateSinkBufferL(TMediaId aMediaId, TBool &aReference);

Description

Creates a sink buffer for the specified media ID. The default version returns NULL.

Parameters

Return value

inline virtual TFourCC SinkDataTypeCode(TMediaId aMediaId);

Description

Returns the sink data type code for the specified media type ID. This would be the same as the source data type four CC although the clip is not going to need this info.

Parameters

Return value

inline virtual void GetNumberOfMetaDataEntriesL(TInt &aNumberOfEntries);

Description

Gets the number of meta data entries.

Meta Data support. The decode format is only capable of reading meta data entries from the clip.

This is an optional method, used to return the number of meta data entries present in the format. A meta data entry is a format-specific field such as authorship, copyright, security details etc. The function is optional as many formats do not provide support for such additional meta data fields.

The default leaves with KErrNotSupported.

Parameters

inline virtual CMMFMetaDataEntry* MetaDataEntryL(TInt aIndex);

Description

Returns the specified meta data entry.

This method is optional as many formats do not provide support for such additional meta data fields.

The default leaves with KErrNotSupported.

Parameters

Return value

inline virtual TInt SetNumChannels(TUint aChannels);

Description

Sets the number of channels.

The default returns KErrNotSupported.

There would normally be no need to override this function as the format decode plugin can normally determine for itself the number of channels. It is only necessary to override this in cases where the format decode plugin cannot determine for itself the number of channels. This function should not be used if the audio clip already exists; that is, in the "Open and Append" scenario, when the function's behaviour is undefined.

Parameters

Return value

inline virtual TInt SetSampleRate(TUint aSampleRate);

Description

Sets the sample rate.

The default implementation returns KErrNotSupported.

There would normally be no need to override this function as the format decode can normally determine the sample rate for itself. It is only necessary to override this in cases where the format decode plugin cannot determine for itself the sample rate.

Parameters

Return value

inline virtual TInt SetBitRate(TUint aBitRate);

Description

Sets the bit rate.

The default implementation returns KErrNotSupported.

This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can not be directly calculated from the sample rate. There would normally be no need to override this function as the format decode can normally determine the sample rate for itself. It is only necessary to override this in cases where the format decode plugin cannot determine for itself the sample rate.

Parameters

Return value

inline virtual TUint NumChannels();

Description

Returns the number of channels.

The default implementation returns 0.

Return value

inline virtual TUint SampleRate();

Description

Gets the sample rate.

The default implementation returns 0.

Return value

inline virtual TUint BitRate();

Description

Gets the bit rate.

The default implementation returns 0.

This method is mainly provided for variable bit rate formats, such as mp3, where the bit rate can not be directly calculated from the sample rate. This function needs overriding for any format decode that supports audio.

Return value

inline virtual void GetSupportedSampleRatesL(RArray< TUint > &aSampleRates);

Description

Gets the supported sample rates.

The default implementation leaves with KErrNotSupported.

This should return an array of sample rates supported by the format where applicable. Note that this refers to the possible sample rates supported by the format, not the actual sample rate, which will be one of the supported sample rates. The implementation of this function is optional.

Parameters

inline virtual void GetSupportedBitRatesL(RArray< TUint > &aBitRates);

Description

Gets the supported bit rates.

The default leaves with KErrNotSupported.

This should return an array of bit rates supported by the format where applicable. Note that this refers to the possible bit rates supported by the format, not the actual bit rate, which will be one of the supported bit rates. The implementation of this function is optional.

Parameters

inline virtual void GetSupportedNumChannelsL(RArray< TUint > &aNumChannels);

Description

Gets the supported number of channels.

The default leaves with KErrNotSupported.

The implementation of this procedure should return an array of channels supported by the format where applicable. Note that this refers to the possible number of channels supported by the format, not the actual number of channels, which will be one of the supported channels. For example, for a format decode plugin capable of supporting mono and stereo the procedure would return an array of length two the first array member containing the value 1 and the second containing the value 2. The implementation of this function is optional.

Parameters

inline virtual void GetSupportedDataTypesL(TMediaId aMediaId, RArray< TFourCC > &aDataTypes);

Description

Gets the supported data types for the given media type id.

The default leaves with KErrNotSupported.

The implementation of this procedure should return an array of data types supported by the format where applicable. Note that this refers to the possible data types that may be supported by the format, not the actual data type of the format, which will be one of the supported data types. For example, for a format decode plugin capable of supporting pcm16 and GSM610 the procedure would return an array of length two the first array member containing the fourCC code ' P16' and the second containing the value GSM6. The implementation of this function is optional.

Parameters

inline virtual void SuggestSourceBufferSize(TUint aSuggestedBufferSize);

Description

Used by the sink to suggest a source buffer size.

This is an optional function provided so that a controller can suggest a buffer size for the format. The controller should not assume that the format will accept the suggested buffer size and there is no obligation on behalf of the format to use the suggested buffer size.

Parameters

inline virtual void SetPositionL(const TTimeIntervalMicroSeconds &aPosition);

Description

Used to set the format's position.

Subsequent data reads should ignore the FrameNumber in the CMMFBuffer and use this setting to determine what data to provide.

The actual position the format sets itself may vary from this setting to ensure that it is aligned to the sample boundaries ensuring consistent data output.

If not supported, positional information should be extracted from the FrameNumber in CMMFBuffer

Parameters

inline virtual TTimeIntervalMicroSeconds PositionL();

Description

Supplies the current position.

Subsequent data reads will commence from this position.

Return value

protected: MDataSource * iClip;

Description

The clip is the source for the decode format.

protected: MDataSink * iDataPath;

Description

The data path is the sink for the decode format.