Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Creating a Format Decode Plugin

Format decode plugin implementations derive from the CMMFFormatDecode abstract class and several of the MDataSource and MDataSink mixin functions.


CMMFFormatDecode Implementation

Derived classes must implement the CMMFFormatDecode pure virtual functions and may implement any of the virtual functions.

Format Decode Plugin Instantiation

A derived plugin need only implement the CMMFFormatDecode::NewL() instantiation method.

A client using a format plugin would always instantiate a specific CMMFFormatDecode by using one of the four base class NewL() instantiation functions. It would not instantiate the format decode plugin via the derived class directly.

The derived NewL() function is expected to parse the format by reading the appropriate data from the supplied source in order to set all its internal settings for the format. Examples of this might be, for a typical audio format, the sample rate, stereo/mono and the data type.

The NewL() function should also determine the data type where possible so that the CMMFFormatDecode::SourceDataTypeCode() method can return the correct FourCC code. The NewL() function is also responsible for determining whether the source is of the instantiated format. For example, if a derived NewL() function is called in response to instantiating a CMMFFormatDecode using a file with an .mp3 extension, and the file is not a valid mp3 file, then the NewL() function should leave with KErrCorrupt.

The ECom TImplementationProxy table, which defines the NewL() for a specific format plugin UID, needs to be defined in a .cpp file.

Audio-Specific Decode Functions

The CMMFFormatDecode base class contains a number of audio-specific functions. Default implementations are provided so there is no need to override these if the format decode plugin only supports video:

General CMMFFormatDecode Functions

The CMMFFormatDecode::SourceDataTypeCode() function must be implemented by the derived format decode plugin. It should return the data type via a FourCC code of the source for the specified media ID. The data type can be determined on instantiation or in the implementation of this function. The data type for a particular format is usually determined by information in the header, although some formats can only have one data type: for example, for the mp3 format the data type is always mp3. For a WAV file the data type could be pcm8, pcm16, IMA, ADPCM or GSM610. If no data type is applicable to the specified media ID, for example if this function was called on an mp3 format plugin with the media ID of KUidMediaTypeVideo, then the function should return the default TFourCC code of NULL.

Other CMMFFormatDecode functions that need to be implemented by a format decode plugin are: CMMFFormatDecode::Streams(), CMMFFormatDecode::FrameTimeInterval(), CMMFFormatDecode::Duration(), CMMFFormatDecode::CanCreateSourceBuffer() and CMMFFormatDecode::CreateSourceBufferL().

In addition: CMMFFormatDecode::SuggestSourceBufferSize(), CMMFFormatDecode::GetNumberOfMetaDataEntriesL() and CMMFFormatDecode::MetaDataEntryL() may optionally be implemented.

[Top]


Format Decode MDataSource and MDataSink Implementation

Format decode MDataSource and MDataSink implementation is described in the following sections:

Format Decode Buffer Fill

A CMMFFormatDecode derived plugin is a source of data (usually for a datapath). It therefore derives from the MDataSource mixin class. The MDataSource mixin method concerned with getting data from the format is MDataSource ::FillBufferL().

MDataSink::BufferFilledL(), which is the call back method of MDataSource::FillBufferL() called on the source (i.e. the format decode plugin being the sink to the data source), is optional. The default implementation propagates the call-back onto the datapath. If any format-specific processing is required after the buffer is filled, such as setting the timestamp on the buffer, sample rate conversions etc, then the MDataSink::BufferFilledL() function must be overridden.

Format Decode State Functions

The MDataSource mixin provides a number of state-related functions that are used to inform a source that the datapath has made a transition to a particular state. These state transition functions are usually called on the source from the datapath and so will be called on the CMMFFormatDecode plugin. These functions are not pure virtual, so it is not compulsory to implement them on the format decode plugin (they have no default implementation in the CMMFFormatDecode base class). In many cases it will be necessary to override these functions even if only to propagate the state change onto the actual source as seen by the controller. The state functions are MDataSource::SourceThreadLogon() and MDataSource::SourcePrimeL(). Note the format decode plugin should propagate these onto its own MDataSource.

In addition, the functions MDataSource::SourcePlayL(), MDataSource::SourcePauseL(), MDataSource::SourceStopL() and MDataSource::SouceThreadLogoff() would not generally have any format decode-specific implementations.

Other MDataSource Functions

It may, for some formats, be necessary to override the MDataSource::SetSourceDataTypeCode() method in cases where the format decode is unable to obtain the data type. The RAW format is an example of this as it has no header information by which the data type can be obtained.

No implementation of the MDataSource::BufferEmptiedL(), MDataSink::EmptyBufferL(), MDataSink::CanCreateSinkBuffer() and MDataSink::CreateSinkBufferL() functions are required in a derived decode plugin.