<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8" xml:lang="en"><title>Writing

a controller plugin</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This document explains how to write a controller plugin. </p>

<section id="GUID-215B50CF-605A-58BA-8E87-CAB942F11741"><title>Purpose</title> <p>A

controller plugin is the main type of multimedia framework (MMF) plugin. A

controller plugin typically supports playing or recording one or more multimedia

formats, <codeph>mp3</codeph> or <codeph>avi</codeph> for example. A controller

plugin is able to read data from one or more sources, apply any required data

transformations and write the data to the appropriate sink. </p> <p><b>Required

Background</b> </p> <p>You need to be familiar with the Symbian platform Plugin

Framework. </p> </section>

<section id="GUID-0DB9E8B5-8B2A-4EB3-998F-376762CAC3D5"><title>Using the Controller

Plugin </title> <p>The following tasks will be covered in this tutorial: </p> <ul>

<li id="GUID-BDA97F96-C90A-5F4E-BEBE-93478FB24453"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-3C8AEA0B-5FE3-5691-B108-05C87F229D07">Implementing the core controller plugin interface</xref>  </p> </li>

<li id="GUID-501F72DA-77B8-5FC8-81AB-CCDE9490DF2D"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-C5696F98-4ECF-5086-AC1A-BF17BCFECC29">Implementing the standard custom command interfaces</xref>  </p> </li>

<li id="GUID-94D36263-EC2D-5145-9D22-F0C1BDDB209B"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-A305F052-58F4-57B9-AB0F-C172768E462F">Interaction with MMF Base Classes and other plugins</xref>  </p> </li>

<li id="GUID-9A37DC2C-2E8D-55FC-9C85-A34008FC4F9C"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-9FD6AAA8-4024-578F-9AB4-48F7017D3EB6">Integrating the controller into the ECom plugin framework</xref>  </p> </li>

<li id="GUID-B53B937C-2D8A-5311-92E2-6458B0CEF2B0"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-0F96339A-BF77-570C-908D-A59AFD2036DB">Testing</xref>  </p> </li>

</ul> <p><b>Basic

Procedure</b> </p> <p>The basic steps for writing a controller plugin are

shown here: </p> <ol id="GUID-D235DD92-682F-542D-AE6D-0EF5B7199E10">

<li id="GUID-5806F6ED-FBDA-5BCC-80C8-C70DEBDAB3A9"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-3C8AEA0B-5FE3-5691-B108-05C87F229D07">Implementing the core controller plugin interface</xref>  </p> </li>

<li id="GUID-00D29242-1610-5ACD-9E97-C87945CF7D4C"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-C5696F98-4ECF-5086-AC1A-BF17BCFECC29">Implementing the standard custom command interfaces</xref>  </p> </li>

<li id="GUID-B925D042-C292-51B4-8490-5D4DD769A307"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-A305F052-58F4-57B9-AB0F-C172768E462F">Interaction with MMF Base Classes and other plugins</xref>  </p> </li>

<li id="GUID-4F7B6585-23AC-5C0E-9BB6-9354C41BD27A"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-9FD6AAA8-4024-578F-9AB4-48F7017D3EB6">Integrating the controller into the ECom plugin framework</xref>  </p> </li>

<li id="GUID-6F8A6A17-29BC-5268-95D9-FACB91622C3E"><p><xref href="GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8.dita#GUID-528BDE53-327A-5D34-B4BF-CB2421BE43C8/GUID-0F96339A-BF77-570C-908D-A59AFD2036DB">Testing</xref>  </p> </li>

</ol> </section>

<section id="GUID-3C8AEA0B-5FE3-5691-B108-05C87F229D07"><title>Implementing

the core controller plugin interface</title> <p>The controller plugin API

is defined by the controller framework element of the MMF. All controller

plugin implementations must derive from the abstract class <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita"><apiname>CMMFController</apiname></xref> and

implement its pure virtual methods. </p> <p>As well as providing the controller

API, the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita"><apiname>CMMFController</apiname></xref> base class also provides functionality

such as instantiation of controller plugins via the <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> plugin

framework, inter-thread message decoding and parameter unpacking, an object

reference counting mechanism and a few utility methods for use by controller

plugins. </p> <p>The following sections describe how to implement the controller

API. </p> <p><b>Sources and sinks </b> </p> <p>Sources and sinks are themselves <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> plugins and provide

an interface that allows the controller to read and write raw data buffers.

The type of source or sink, along with any source- specific or sink-specific

initialisation parameters (for example, the file name for a file source),

is specified by the client. The source or sink is then created and owned by

the controller framework. It is then passed into the controller plugin via

a call to <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-11623B04-A83E-3E32-A06E-6454D8407ADB"><apiname>CMMFController::AddDataSourceL()</apiname></xref> or <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-8842FF05-7822-317A-A650-225775B758FD"><apiname>CMMFController::AddDataSinkL()</apiname></xref> for

a data source or a data sink respectively. </p> <p> <b> Note :</b> The ownership

of a source or sink always remains with the controller framework and not with

the controller plugin, and that a controller plugin should never delete a

source or sink. If the controller plugin leaves during the call to <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-11623B04-A83E-3E32-A06E-6454D8407ADB"><apiname>CMMFController::AddDataSourceL()</apiname></xref> or <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-8842FF05-7822-317A-A650-225775B758FD"><apiname>CMMFController::AddDataSinkL()</apiname></xref>, the source or sink will be destroyed by the controller framework. </p> <p>There

is no limit on the number of sources or sinks that can be added to a particular

controller plugin, other than the limit provided by the plugin itself. For

example, an audio controller would have one source and one sink. A video playing

controller would have one source and two sinks (display and speaker). </p> <p>Sources

and sinks can also be removed from the controller plugin by the client. The

reference of the particular source or sink being removed is passed into either

the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-6CA27841-ACBE-303B-84A6-225F77B6CC53"><apiname>CMMFController::RemoveDataSourceL()</apiname></xref> or <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-FD6A61E9-B355-36BA-9FF5-AA5E694F76FA"><apiname>CMMFController::RemoveDataSinkL()</apiname></xref> method

to remove a data source or a data sink respectively. The controller plugin

should remove any reference that it has to the source or sink; the source

or sink will then be deleted by the controller framework. </p> <p> <b>Note:</b> If

the controller plugin leaves during these calls (for example, if it does not

support the removal of sources or sinks), the controller framework will not

delete the source or sink. </p> <p><b>Controller states </b> </p> <p>The Controller plugin states, along with

the commands to transition the plugin between the states, are: </p> <ul>

<li id="GUID-15FEBAAD-0C40-5029-B8ED-080967BD5980"><p> <codeph>Open</codeph>,

this is the current state of the controller, after it has been created. Once

the controller has been configured, it moves to the <codeph>Stopped</codeph> state.

This transition typically involves adding the source(s) and sink(s) and configuring

any utility objects or other plugins owned by the controller. </p> </li>

<li id="GUID-4BD7C0FB-AB98-5373-B7A8-BFCF8E6ECC76"><p> <codeph>Stopped</codeph>,

in this state the controller should not have any resources or buffers allocated,

and the position should be zero. </p> </li>

<li id="GUID-BBDACB71-F927-5AB0-B6CA-838DB6B48422"><p> <codeph>Primed</codeph>,

in moving to the primed state, the controller should allocate any buffers

and resources that will be required to perform playback. The playback or recording

position should also be stored when the controllere is in the <codeph>primed</codeph> state.

Controllers should only be moved into this state just before play, otherwise

unnecessary memory and resources will be used. </p> </li>

<li id="GUID-8D3C5466-1A8E-5F0B-9607-AFE4CF651D23"><p> <codeph>Playing</codeph>,

when in this state, the controller plugin should be transferring data between

source(s) and sink(s). </p> </li>

</ul> <p>Calling <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-AA743B27-C597-3D6A-B10C-C51224EC78FA"><apiname>CMMFController::ResetL()</apiname></xref> on the controller

plugin should cause it to revert back to the <codeph>Open</codeph> state.

This will involve stopping playback, deleting any allocated resources, and

removing any references to sources and sinks. </p> <p><b>Position and Duration </b> </p> <p>Position and duration can be set by

deriving from the pure virtual methods <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-01BBB3DC-0178-392C-9A8C-F2B8A563FC1B"><apiname>CMMFController::PositionL()</apiname></xref>, <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-8DA4E77A-07EF-304B-9AA6-0A744C6CD3B4"><apiname>CMMFController::SetPositionL()</apiname></xref> and <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-D61C8034-587A-3FEC-9659-155E547F9042"><apiname>CMMFController::DurationL()</apiname></xref>. </p> <p> <codeph>Note:</codeph> The <i>position</i> has

meaning only in the <codeph>Primed</codeph> and <codeph>Playing</codeph> states.

The controller plugin should leave with <codeph>KErrNotReady</codeph> if an

attempt is made to set or get the position when the controller is in any other

state. However, it should be possible to query the duration as soon as the

data source or data sink has been added. </p> <p><b>Custom Commands </b> </p> <p>Custom commands allow controller plugin writers

to extend the basic controller API. They sends messages from the client through

the controller framework to the controller plugin. </p> <p>The <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-C3ADC1F7-97DB-3324-9C3C-CFD391AC7F35"><apiname>CMMFController::CustomCommand()</apiname></xref> method

can be implemented in the controller plugin to support custom commands. The

default implementation provided by the base class is to complete the message

with <codeph>KErrNotSupported</codeph>. </p> <p> <b>Note:</b> It is imperative

that the message is always completed by this method and that this method cannot

leave. Any error that occurs must be passed back to the client by completing

the message with the error code. </p> <p>Each <xref href="GUID-3AF511EA-1E66-3286-9FD0-B90EC22BFAC1.dita"><apiname>TMMFMessage</apiname></xref> has

an associated interface UID which should be checked before handling any message

to make sure that the command is supported. </p> <p>The following code illustrates

a typical custom command implementation. </p> <codeblock id="GUID-88B2D503-D009-502A-923A-EA683A28061B" xml:space="preserve">void CMyController::CustomCommand(TMMFMessage&amp; aMessage)

    {

    // First, check we can handle message by checking its interface id

    if (aMessage.InterfaceId() != KUidMyControllerCustomCommandInterface)

       {

        aMessage.Complete(KErrNotSupported);

        return;

       }

    // Next, dispatch the command to the appropriate method.

    TInt error = KErrNone;

    switch (aMessage.Function())

        {

    case EMyCustomCommandOne:

        error = HandleCustomCommandOne(aMessage);

        break;

    case EMyCustomCommandTwo:

        error = HandleCustomCommandTwo(aMessage);

        break;

    default:

        error = KErrNotSupported;

break;

        }

    aMessage.Complete(error);

    }

</codeblock> <p>The above example shows synchronous command handling. If the

plugin needs to do some task that requires a long time, the <codeph>aMessage</codeph> parameter

should be copied, stored and completed later when processing has finished. </p> <p>The

methods <codeph>HandleCustomCommandOne</codeph> and <codeph>HandleCustomCommandTwo</codeph> above,

copy any data to and from the client. This can be done using the appropriate <xref href="GUID-3AF511EA-1E66-3286-9FD0-B90EC22BFAC1.dita"><apiname>TMMFMessage</apiname></xref> methods. </p> <p><b>Asynchronous Error Reporting </b> </p> <p>The <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-35FFB275-95ED-323C-B0AC-7914CBA2319D"><apiname>CMMFController::DoSendEventToClient()</apiname></xref> utility

method allows a controller plugin to send an event to its client. </p> <p>The

multimedia client utilities listen for specific event types and error codes.

If the controller plugin is accessed by clients that are using the multimedia

client utility APIs (which will usually be the case) then those event types

and error codes should be used. The event types and error codes for which

the multimedia client utilities listen are listed below: </p> <table id="GUID-4BE6C78B-5E14-50EF-94EB-05AFA08DFD2D">

<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>

<tbody>

<row>

<entry><p> <b>Client utility</b>  </p> </entry>

<entry><p> <b>Event type</b>  </p> </entry>

<entry><p> <b>Error code</b>  </p> </entry>

<entry><p> <b>Meaning</b>  </p> </entry>

</row>

<row>

<entry><p>Audio Player Utility (<xref href="GUID-778D24B5-A68E-3C91-B66A-69007FBA4791.dita"><apiname>CMdaAudioPlayerUtility</apiname></xref>) </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrOverflow </p> </entry>

<entry><p>Playback complete, the end of the data was reached. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrEof </p> </entry>

<entry><p>Playback complete, the end of the data was reached. </p> </entry>

</row>

<row>

<entry><p>Audio Recorder Utility (<xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref>) </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrOverflow </p> </entry>

<entry><p>Playback complete, the end of the data was reached. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrUnderflow </p> </entry>

<entry><p>Recording complete, no more source data from microphone. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrEof </p> </entry>

<entry><p>Playback or recording complete, end of data reached. </p> </entry>

</row>

<row>

<entry><p>Audio Converter Utility (<xref href="GUID-810D29DA-8332-3E63-8A63-5B8A04EC9688.dita"><apiname>CMdaAudioConvertUtility</apiname></xref>) </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrOverflow </p> </entry>

<entry><p>Conversion complete, end of data reached. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrEof </p> </entry>

<entry><p>Conversion complete, end of data reached. </p> </entry>

</row>

<row>

<entry><p>Video Player Utility (<xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref>) </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrOverflow </p> </entry>

<entry><p>Playback complete, end of data reached. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>KErrEof </p> </entry>

<entry><p>Playback complete, end of data reached. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>KMMFEventCategory VideoOpenComplete </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>Open complete. Must be used otherwise clients will not be notified

when the clip has been opened. This is used because video clips can take a

long time to process on opening. The error code is passed back to the client. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>KMMFEventCategory PlaybackComplete </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>Playback complete. Can be used instead of <codeph>KErrOverflow</codeph> or <codeph>KErrEof</codeph>.

The error code is passed back to the client. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>KMMFEventCategory VideoRebufferStarted </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>Re-buffering has begun. Client will be notified so it can update

its UI. </p> </entry>

</row>

<row>

<entry><p> </p> </entry>

<entry><p>KMMFEventCategory VideoRebufferComplete </p> </entry>

<entry><p>Any </p> </entry>

<entry><p>Re-buffering has finished. Client will be notified so it can update

its UI. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>MMF Objects </b> </p> <p>The controller framework contains an object referencing

mechanism that allows a client to send messages to arbitrary objects in the

controller thread without having to go via the controller plugin itself. In

order to achieve this, the arbitrary object must be derived from <xref href="GUID-C2938956-C3DE-34F0-AD68-4E502F252FE4.dita"><apiname>CMMFObject</apiname></xref> and

added to the object container. The object container can be accessed via the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-C13AA1D6-94D3-33EA-B901-C4EFBA127D3A"><apiname>CMMFController::MMFObjectContainerL()</apiname></xref> method. </p> <p>Sources and sinks have a <xref href="GUID-C2938956-C3DE-34F0-AD68-4E502F252FE4.dita"><apiname>CMMFObject</apiname></xref> wrapper placed around

them by the controller framework, and can receive messages from the client.

This mechanism is also used to reference source(s) and sink(s), so the client

can specify exactly the source or sink when calling the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-6CA27841-ACBE-303B-84A6-225F77B6CC53"><apiname>CMMFController::RemoveDataSourceL()</apiname></xref> or <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-FD6A61E9-B355-36BA-9FF5-AA5E694F76FA"><apiname>CMMFController::RemoveDataSinkL()</apiname></xref> methods. </p> <p> <b>Note:</b> The objects added to the <xref href="GUID-C2B766A9-493D-3B90-B205-F7915B39EBAF.dita"><apiname>CMMFObjectContainer</apiname></xref> are

owned by the <codeph>CMMFObjectContainer</codeph>. </p> <p>Each object added

to the <codeph>CMMFObjectContainer</codeph> is assigned a handle. This handle

must be passed back to the client in order for the client to be able to send

messages directly to the object. </p> <p>The client should use this handle

to set the handle of the <xref href="GUID-40C533CC-ACA4-3DBC-B31C-F17DACB7F321.dita"><apiname>TMMFMessageDestination</apiname></xref> parameter

in the <xref href="GUID-9DEDFB0F-C963-3FB7-9237-DDDB276C8841.dita#GUID-9DEDFB0F-C963-3FB7-9237-DDDB276C8841/GUID-A3976673-6919-307E-AA6A-4E6B18D96619"><apiname>RMMFController::CustomCommandAsync()</apiname></xref> or <xref href="GUID-9DEDFB0F-C963-3FB7-9237-DDDB276C8841.dita#GUID-9DEDFB0F-C963-3FB7-9237-DDDB276C8841/GUID-E0CBE252-799E-3972-8C14-B1C6E135C458"><apiname>RMMFController::CustomCommandSync()</apiname></xref> method

for asynchronous or synchronous operation respectively. The custom command

will then be routed directly to the <xref href="GUID-C2938956-C3DE-34F0-AD68-4E502F252FE4.dita"><apiname>CMMFObject</apiname></xref> by the controller

framework. </p> </section>

<section id="GUID-C5696F98-4ECF-5086-AC1A-BF17BCFECC29"><title>Implementing

the standard custom command interfaces</title> <p>The core controller plugin

API provides only basic support for controlling the flow of data. The application-level

multimedia utility APIs (for example, <xref href="GUID-778D24B5-A68E-3C91-B66A-69007FBA4791.dita"><apiname>CMdaAudioPlayerUtility</apiname></xref> )

contain much richer functionality. The application-level multimedia utility

APIs provide clients with a concrete API to access extended controller functionality,

and to give controller plugins a concrete mixin API to implement. </p> <p>Several

sets of standard custom command APIs have been defined. The following table

shows which of these classes must be implemented to allow the controller plugin

to be used properly from each of the application-level utility APIs. </p> <table id="GUID-2B37F10D-C1B3-5449-A211-77192872974E">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Application-level Utility API</b>  </p> </entry>

<entry><p> <b>Required Custom Command APIs</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-47EA759D-94C2-3655-B6E8-6C87F8F449A9.dita"><apiname>CmdaAudioPlayerUtility</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-9004EBF7-A519-3825-91DC-0CB5EE2AE91E.dita"><apiname>MMMFAudioPlayDeviceCustomCommandImplementor</apiname></xref>  </p> <p> <xref href="GUID-9EBEDC0D-2AE8-3A15-A72F-E18999056879.dita"><apiname>MMMFAudioPlayControllerCustomCommandImplementor</apiname></xref> </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E83933DA-64D2-3B7F-ACF6-0A72E6132E16.dita"><apiname>CmdaAudioRecorderUtility</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-9004EBF7-A519-3825-91DC-0CB5EE2AE91E.dita"><apiname>MMMFAudioPlayDeviceCustomCommandImplementor</apiname></xref>  </p> <p> <xref href="GUID-6257431B-91C0-3F11-B9B8-6CA07BE81DF0.dita"><apiname>MMMFAudioRecordDeviceCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-9EBEDC0D-2AE8-3A15-A72F-E18999056879.dita"><apiname>MMMFAudioPlayControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-955A29AB-D7FE-3747-A451-A75B01867675.dita"><apiname>MMMFAudioRecordControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-B9EF7125-3D50-375D-904E-2148F650765D.dita"><apiname>MMMFAudioControllerCustomCommandImplementor</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A11E409C-894A-3C91-8924-5CF6C53D7F7D.dita"><apiname>CmdaAudioConvertUtility</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-9EBEDC0D-2AE8-3A15-A72F-E18999056879.dita"><apiname>MMMFAudioPlayControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-955A29AB-D7FE-3747-A451-A75B01867675.dita"><apiname>MMMFAudioRecordControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-B9EF7125-3D50-375D-904E-2148F650765D.dita"><apiname>MMMFAudioControllerCustomCommandImplementor</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-3F3FEBAA-DA64-3D83-999C-33AF27B9F0B2.dita"><apiname>CvideoPlayerUtility</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-4D1C7814-76D6-3A1C-9441-4091C4787826.dita"><apiname>MMMFVideoControllerCustomCommandImplementor</apiname></xref>  </p> <p> <xref href="GUID-1FBF69A5-100C-30D6-B934-AD208C320C52.dita"><apiname>MMMFVideoPlayControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-9004EBF7-A519-3825-91DC-0CB5EE2AE91E.dita"><apiname>MMMFAudioPlayDeviceCustomCommandImplementor</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-EA89F469-D402-34B4-9038-895ABA696AF6.dita"><apiname>CvideoRecorderUtility</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-4D1C7814-76D6-3A1C-9441-4091C4787826.dita"><apiname>MMMFVideoControllerCustomCommandImplementor</apiname></xref>  </p> <p> <xref href="GUID-E66BBFA9-17C5-30C0-88F0-2680825585D6.dita"><apiname>MMMFVideoRecordControllerCustomCommandImplementor</apiname></xref> </p> <p> <xref href="GUID-6257431B-91C0-3F11-B9B8-6CA07BE81DF0.dita"><apiname>MMMFAudioRecordDeviceCustomCommandImplementor</apiname></xref> </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>In order to implement the required custom command APIs, the controller

plugin should derive from the mixins shown in the table above, and use the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-DAB14DA3-E897-3C57-ADAC-8748D6B06E7B"><apiname>CMMFController::AddCustomCommandParserL()</apiname></xref> method

to register itself as being able to handle that API. </p> <p>The <xref href="GUID-92F9FFAA-1A8F-34B4-98E4-7BAF505BDE45.dita"><apiname>CMMFCustomCommandParserBase</apiname></xref> derived

object decodes the custom command on behalf of the controller plugin and calls

the concrete API via the mixin interface. The following table shows which <xref href="GUID-92F9FFAA-1A8F-34B4-98E4-7BAF505BDE45.dita"><apiname>CMMFCustomCommandParserBase</apiname></xref> object

should be used with each mixin class. </p> <table id="GUID-7C4650A0-ED5A-5B9B-8349-3B348D16DCBB">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Mixin Interface</b>  </p> </entry>

<entry><p> <b>Custom Command Parser</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B9EF7125-3D50-375D-904E-2148F650765D.dita"><apiname>MMMFAudioControllerCustomCommandImplementor</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-0E8AE2BE-D2E4-31D1-A9EE-8C134AC08A44.dita"><apiname>CMMFAudioControllerCustomCommandParser</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9EBEDC0D-2AE8-3A15-A72F-E18999056879.dita"><apiname>MMMFAudioPlayControllerCustomCommandImplementor</apiname></xref> </p> </entry>

<entry><p> <xref href="GUID-4446548D-A1C6-37E9-8C93-5DE06BC9733F.dita"><apiname>CMMFAudioPlayControllerCustomCommandParser</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-955A29AB-D7FE-3747-A451-A75B01867675.dita"><apiname>MMMFAudioRecordControllerCustomCommandImplementor</apiname></xref> </p> </entry>

<entry><p> <xref href="GUID-F37B8FE6-ABD8-311A-89CA-3495FE88EE32.dita"><apiname>CMMFAudioRecordControllerCustomCommandParser</apiname></xref> </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-4D1C7814-76D6-3A1C-9441-4091C4787826.dita"><apiname>MMMFVideoControllerCustomCommandImplementor</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-4C75EEA6-3F0E-3EDE-B02C-83B8AE6F4563.dita"><apiname>CMMFVideoControllerCustomCommandParser</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-1FBF69A5-100C-30D6-B934-AD208C320C52.dita"><apiname>MMMFVideoPlayControllerCustomCommandImplementor</apiname></xref> </p> </entry>

<entry><p> <xref href="GUID-E45B8292-04DE-3929-8E10-46E8D259A3B3.dita"><apiname>CMMFVideoPlayControllerCustomCommandParser</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E66BBFA9-17C5-30C0-88F0-2680825585D6.dita"><apiname>MMMFVideoRecordControllerCustomCommandImplementor</apiname></xref> </p> </entry>

<entry><p> <xref href="GUID-7BF02827-4A99-3127-873A-BA5D5CD1DFDB.dita"><apiname>CMMFVideoRecordControllerCustomCommandParser</apiname></xref> </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9004EBF7-A519-3825-91DC-0CB5EE2AE91E.dita"><apiname>MMMFAudioPlayDeviceCustomCommandImplementor</apiname></xref>  </p> </entry>

<entry><p> <xref href="GUID-C27DB2A9-1AD6-3AA2-A9A7-F97D8B493B20.dita"><apiname>CMMFAudioPlayDeviceCustomCommandParser</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-6257431B-91C0-3F11-B9B8-6CA07BE81DF0.dita"><apiname>MMMFAudioRecordDeviceCustomCommandImplementor</apiname></xref> </p> </entry>

<entry><p> <xref href="GUID-CAB4C3DA-43E3-37C5-B9BD-0DE3341A7D59.dita"><apiname>CMMFAudioRecordDeviceCustomCommandParser</apiname></xref>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The following example code shows how the controller should register

itself with the controller framework to receive standard custom commands. </p> <codeblock id="GUID-DDC6EA9D-C01D-599D-9ADA-F3445675D252" xml:space="preserve">class CMyControllerPlugin : public    CMMFController,

                                      MMMFAudioControllerCustomCommandImplementor,

                                      MMMFAudioPlayDeviceCustomCommandImplementor

    {

...

private:

    void ConstructL();

    };

void CMyControllerPlugin::ConstructL()

    {

...

    // Construct custom command parsers

    CMMFAudioControllerCustomCommandParser* audConParser =

                                     CMMFAudioControllerCustomCommandParser::NewL(*this);

    CleanupStack::PushL(audParser);

    AddCustomCommandParserL(*audConParser); //parser now owned by controller framework

    CleanupStack::Pop(audConParser);

    CMMFAudioPlayDeviceCustomCommandParser* audPlayDevParser = 

                                     CMMFAudioPlayDeviceCustomCommandParser::NewL(*this);

    CleanupStack::PushL(audPlayDevParser);

    AddCustomCommandParserL(*audPlayDevParser); //parser now owned by controller framework

    CleanupStack::Pop();//audPlayDevParser

    }

</codeblock> <p>It is also possible for controller plugins to define their

own standard custom command classes. This might be useful if a group of plugins

have the same API (for example, a group of <codeph>MIDI</codeph> controller

plugins). Clients would then be able to access equivalent functionality in

each plugin using the same API. </p> </section>

<section id="GUID-A305F052-58F4-57B9-AB0F-C172768E462F"><title>Interaction

with MMF Base Classes and other Plugins</title> <p>The MMF provides a set

of utility classes and other types of plugins to aid with writing controller

plugins. All utility classes are provided in the library <codeph>MMFServerBaseClasses.DLL</codeph>.

A brief description of each of the classes follows. </p> <p> <b>Note:</b> The

use of data sources, data sinks and buffers is mandatory. The use of the other

classes is optional. </p> <ul>

<li id="GUID-55EAC53C-8F71-5A3B-AE7C-695EBC3C53D0"><p>Data Sources and Sinks </p> </li>

<li id="GUID-EF0BF115-FF08-56FE-90C7-CF48D85A6C0B"><p>Buffers </p> </li>

<li id="GUID-4B99F28F-8EB3-5B66-B9BF-8AEE3DA5253E"><p>Datapath </p> </li>

<li id="GUID-C5CAE5D5-7C82-5068-9AAB-6D9E66DE5D6B"><p>Codecs </p> </li>

<li id="GUID-174E2D35-3208-5AEA-8257-4952E147F72D"><p>Formats </p> </li>

</ul> <p><b>Data Sources and Sinks </b> </p> <p>Data sources and sinks are <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> plugins,

and are derived from the base class <xref href="GUID-2230F976-A798-30EB-ABA6-09C86716A4B5.dita"><apiname>MDataSource</apiname></xref> or <xref href="GUID-708A7583-5C55-3FE1-8238-974C8821588D.dita"><apiname>MDataSink</apiname></xref> respectively.

The currently available data sources and sinks are listed below: </p> <ul>

<li id="GUID-E7874D8E-528E-50BE-9BBE-1F3B721D0274"><p> <xref href="GUID-9914ABBD-B15F-3CDB-9F4E-1C9002A30269.dita"><apiname>CMMFFile</apiname></xref>  </p> </li>

<li id="GUID-52F6F014-B4AA-5301-A099-19A7B3415CD0"><p> <xref href="GUID-ADF29263-C4FB-31A8-AB06-0E10E39B7C39.dita"><apiname>CMMFDescriptor</apiname></xref>  </p> </li>

<li id="GUID-52A43340-E2C7-56BE-BA1E-AF96A49DD8F2"><p> <xref href="GUID-D9BCF418-34D3-3D47-8968-A70C5C01E5DF.dita"><apiname>CMMFAudioInput</apiname></xref>  </p> </li>

<li id="GUID-C95CADA7-9917-5C4E-A93D-1E16CB34171F"><p> <xref href="GUID-CB3745FF-6DC0-325A-95CC-70BF5112DD70.dita"><apiname>CMMFAudioOutput</apiname></xref> <xref href="GUID-D9BCF418-34D3-3D47-8968-A70C5C01E5DF.dita"><apiname>CMMFAudioInput</apiname></xref> </p> </li>

</ul> <p>They are created by the controller framework and passed into the

controller plugin by reference using the <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-11623B04-A83E-3E32-A06E-6454D8407ADB"><apiname>CMMFController::AddDataSourceL()</apiname></xref> or <xref href="GUID-123B3A78-9E84-3283-AB73-6B4293939A5D.dita#GUID-123B3A78-9E84-3283-AB73-6B4293939A5D/GUID-8842FF05-7822-317A-A650-225775B758FD"><apiname>CMMFController::AddDataSinkL()</apiname></xref> method. </p> <p>Some sources and sinks have extended APIs that allow the controller plugin

to perform actions, such as setting the volume. The type of the source or

sink can be checked by the controller plugin using the methods <xref href="GUID-2230F976-A798-30EB-ABA6-09C86716A4B5.dita#GUID-2230F976-A798-30EB-ABA6-09C86716A4B5/GUID-D931704C-4349-36EE-9E05-BADF10253373"><apiname>MDataSource::DataSourceType()</apiname></xref> and <xref href="GUID-708A7583-5C55-3FE1-8238-974C8821588D.dita#GUID-708A7583-5C55-3FE1-8238-974C8821588D/GUID-E03D973E-75A5-3FBA-9D24-04A5F6B23A7C"><apiname>MDataSink::DataSinkType()</apiname></xref>. These methods return a UID which can be checked against known UIDs to identify

the extended API of the source or sink. For example, the following code would

be used to set the volume of a speaker sink. </p> <codeblock id="GUID-8CCA0B72-6A76-5235-B397-17745DAB1A18" xml:space="preserve">MMMFAudioOutput* audioOutput = static_cast(MMMFAudioOutput*,(iDataSink));

audioOutput->SoundDevice().SetVolume(14);

</codeblock> <p>It is possible dynamically to add new data sources and sinks

to the system, see <xref href="GUID-2062A92D-2A3C-5D38-B25E-6D4CF3E4BC98.dita">writing

a Source/Sink plugin</xref> for information. </p> <p><b>Buffers </b> </p> <p>Buffers are used to contain data as it is being transferred

from a source to a sink. There are several buffer types all derived from a

common base class <xref href="GUID-9A7A83ED-592B-3A0C-BABB-3B90099BCF7C.dita"><apiname>CMMFBuffer</apiname></xref>: <xref href="GUID-AE26E6A4-C1AD-3B35-B5F7-CE0AB60169BB.dita"><apiname>CMMFDataBuffer</apiname></xref>, <xref href="GUID-74A246CD-24ED-3506-9E98-0C6A7EFD1AC3.dita"><apiname>CMMFDescriptorBuffer</apiname></xref> and <xref href="GUID-4899998E-6DE7-3A9F-874B-6B4524CE33E4.dita"><apiname>CMMFTransferBuffer</apiname></xref>. </p> <p><b>Datapath </b> </p> <p>The datapath is a utility class that transfers data

from a single source to a single sink, via a codec plugin if the source and

sink data types differ. The API of the datapath is very similar to that of

the basic controller plugin API, and much of the complexity of controller

plugins can be avoided by using the datapath. </p> <p>The datapath can be

used either through: </p> <ul>

<li id="GUID-12E661D0-9317-551F-8D9E-876AF0153CCC"><p> <xref href="GUID-930A17D8-92C9-379A-A524-176AA68FE8E3.dita"><apiname>CMMFDataPath</apiname></xref>,

in which case the data will be transferred from the source to the sink in

the main thread of the controller plugin. </p> </li>

<li id="GUID-B7B80AD5-7977-56C7-92A6-A722C66FA7EA"><p> <xref href="GUID-1869F1F6-AEAE-3932-8A9C-54B641CE9CD5.dita"><apiname>RMMFDataPath</apiname></xref>,

in which case a new thread will be launched to transfer the data from the

source to the sink. This is useful if a controller has multiple sources and

sinks (a video controller for example). The multiple datapaths can each be

executed in their own thread to improve performance. </p> </li>

</ul> <p>If the source and sink data types are the same then no codec is required

and the datapath will use a <codeph>null</codeph> codec and the buffers will

be transferred straight from the source to the sink without being copied in

between. </p> <p><b>Codecs </b> </p> <p>Codec plugins are derived from <xref href="GUID-18F4082A-D301-3007-88DD-0E13AB81C74A.dita"><apiname>CMMFCodec</apiname></xref> and

can be used by controller plugins to convert data from one data type to another.

Codec plugins are designed to be used by different controller plugins, for

example both an audio controller and a video controller might want to make

use of a <codeph>PCM8</codeph> to <codeph>PCM16</codeph> codec. </p> <p>See <xref href="GUID-7261FEC6-5AA6-555C-AB72-2173BD3F1FA5.dita">writing a codec plugin</xref> for

details of how to implement codec plugins. </p> <p><b>Formats </b> </p> <p>Controller plugin writers may wish to implement their

format support by writing format plugins. While format plugins can only be

used by one controller plugin, this does make it much easier to dynamically

extend the formats supported by the controller plugin without providing a

whole new controller plugin. See <xref href="GUID-BDC081CA-FB0D-5F56-8C1B-F7AC9DD6875D.dita">writing

a format plugin</xref> for details of how to implement format plugins. </p> </section>

<section id="GUID-9FD6AAA8-4024-578F-9AB4-48F7017D3EB6"><title>Integrating

the Controller into the ECom Plugin Framework</title> <p>This section describes

how to write the ECom plugin registry file. See <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> for

generic instructions on how to write an ECom plugin. </p> <p>The controller

plugin resolver is decides which controller plugin should be used to provide

support for a particular format. Controller plugins provide information in

their <codeph>ECom</codeph> resource file which allows the controller framework

(and ultimately the client application) to determine: </p> <ul>

<li id="GUID-B14BEDD7-34F4-5EB6-A0C3-EAFD2427254D"><p>The display name and

supplier of the controller plugin. </p> </li>

<li id="GUID-CCE1BACF-7EA4-5160-A132-387BB2E27BE1"><p>The media types supported

by the controller plugin (e.g. audio or video). </p> </li>

<li id="GUID-2207F37F-C06F-5E7C-A92F-2B07D4E19CDE"><p>The formats the controller

plugin can play and record. </p> </li>

</ul> <p>For each format supported, for both playing and recording, the information

below is provided: </p> <ul>

<li id="GUID-9BE53029-AE39-5A88-802D-7907936D23D4"><p>Display Name of the

format. </p> </li>

<li id="GUID-D4E3EA7C-BE26-5CC5-ABFA-80F37C662D9C"><p>Supplier of the format

(in case support for this format was provided by a different party to the

controller plugin). </p> </li>

<li id="GUID-0222405C-A868-5C71-900D-0181F071E718"><p>The Media Types supported

by the format. </p> </li>

<li id="GUID-3D9FE26B-DF8A-58D8-BDDC-CCD55FEEBBF9"><p>The MIME types applicable

to the format. </p> </li>

<li id="GUID-EC8EB39A-6C09-50AD-90F8-48C7E7A9B356"><p>The file extensions

that identify files that can be handled by the format. </p> </li>

<li id="GUID-EF2278A1-9878-5408-B689-A27A181C5855"><p>Any header data segments

that could be matched to the first few bytes of multimedia data to identify

that the data could be handled using this format. </p> </li>

</ul> <p>Most of the information outlined above is provided by the plugin

in the <codeph>opaque_data</codeph> field of the ECom resource file. This

field takes an 8-bit string and is limited to 127 characters in length. A

tagged data scheme is used to separate the different types of data. The tags

are all three characters in length, and the scheme only uses opening tags

(i.e. no end tags) to reduce overhead and complexity. The tags available are: </p> <table id="GUID-1F208E5B-912E-5973-BB47-0A84F917CF23">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p>Tag </p> </entry>

<entry><p>Usage </p> </entry>

<entry><p>Description </p> </entry>

</row>

<row>

<entry><p>&lt;s&gt; </p> </entry>

<entry><p>Controller, Format </p> </entry>

<entry><p>The supplier of the plugin. </p> </entry>

</row>

<row>

<entry><p>&lt;i&gt; </p> </entry>

<entry><p>Controller, Format </p> </entry>

<entry><p>A media ID supported by this plugin. Multiple entries can be included. </p> </entry>

</row>

<row>

<entry><p>&lt;p&gt; </p> </entry>

<entry><p>Controller </p> </entry>

<entry><p>The UID of the play format collection for this controller (see below). </p> </entry>

</row>

<row>

<entry><p>&lt;r&gt; </p> </entry>

<entry><p>Controller </p> </entry>

<entry><p>The UID of the record format collection for this controller (see