<?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-CADAFAF2-24E9-5007-9C2F-5453E8062074" xml:lang="en"><title>Initializing

DevSound Functionality Tutorial</title><shortdesc>DevSound provides a common interface to the audio hardware for

all audio functionality. DevSound is responsible for providing access to available

audio resources, initialization and configuration of hardware devices, and

playing and recording audio. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-5364D394-21F7-5327-BCD3-8F91DB5EEC8D-GENID-1-10-1-19-1-1-12-1-5-1-4-1-5-1-4-1-3-1"><title>Required background</title> <p>Before

you start, you must: </p> <ul>

<li id="GUID-67BD381F-4B0B-5B87-9439-7B72DBF29AFD"><p>Understand the <xref href="GUID-170A1D9C-12CB-502A-BCB3-9E2AEBB207FA.dita">A3F DevSound Component</xref> to

which the DevSound library belongs. </p> </li>

<li id="GUID-1E1F544F-06EF-5EFD-981B-8B179E37136E"><p>Understand the architectural

relationship of the DevSound. For information see <xref href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita">DevSound

Overview</xref>. </p> </li>

</ul> </section>

<section><title>Introduction</title> <p>DevSound's functionality is provided

by the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita"><apiname>CMMFDevSound</apiname></xref> class. </p> <p><b>Construction

and initialization</b> </p> <p>Each client using audio resources must have

an instance of the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita"><apiname>CMMFDevSound</apiname></xref> class associated with it.

The <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-088CC167-C46D-3A2B-BE00-D7AEB98254AE"><apiname>CMMFDevSound::NewL()</apiname></xref> method is used to construct a

new instance of DevSound. </p> <codeblock id="GUID-7E5C8C3A-B09B-5CC3-870E-1A28C75C50CF" xml:space="preserve">static IMPORT_C CMMFDevSound *NewL();</codeblock> <p>Once

created, the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> method is used

to initialize DevSound to play and record. There are three versions of the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> method,

differing in type and number of parameters. The three versions are: </p> <ul>

<li id="GUID-5492383B-33F4-5884-A926-567B49C44948"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> -

initializes CMMFDevSound object to play and record PCM16 raw audio data with

sampling rate of 8 KHz. </p> <codeblock id="GUID-3FC67F03-CE07-5174-B70A-82C3AC55AC4C" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &amp;aDevSoundObserver, TMMFState

aMode);</codeblock> <p>This method has two parameters: </p> <ul>

<li id="GUID-84931A64-8268-5E15-9FD1-0D8F33CD243B"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> -

a reference to a DevSound Observer instance. </p> </li>

<li id="GUID-AE152880-C8E8-5923-97C6-A3D44B65515B"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> -

the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li>

</ul> </li>

<li id="GUID-67B42425-FBD1-5FFA-8382-68E0CD4D2EA8"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> -

initializes DevSound object for the mode <codeph>aMode</codeph> for processing

audio data with hardware device <codeph>aHWDev</codeph>. </p> <codeblock id="GUID-168BD108-045C-52E9-BB97-BDA05643022F" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &amp;aDevSoundObserver, TUid aHWDev,

TMMFState aMode);</codeblock> <p>This method has three parameters: </p> <ul>

<li id="GUID-917DF4D4-FD55-59EA-B0E8-64A7B5F5F35B"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> -

a reference to a DevSound Observer instance. </p> </li>

<li id="GUID-760E73CF-E957-57B2-9F7B-9C2AACA7B3F3"><p> <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita"><apiname>TUid</apiname></xref> -

the <xref href="GUID-E18CF25C-82DE-3C69-BD86-5DF67579C1A6.dita"><apiname>CMMFHwDevice</apiname></xref> implementation identifier. </p> </li>

<li id="GUID-33E8A5C9-4609-5B4B-8050-438DF9317BAA"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> -

the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li>

</ul> </li>

<li id="GUID-A88F2138-5F4E-527D-8BEA-B27F2D330B83"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> -

initializes DevSound object for the mode <codeph>aMode</codeph> for processing

audio data with hardware device supporting FourCC <codeph>aDesiredFourCC</codeph>. </p> <codeblock id="GUID-415E6B82-08A9-5CB8-BA49-F4FA6005E529" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &amp;aDevSoundObserver, TFourCC

aDesiredFourCC, TMMFState aMode);</codeblock> <p>This method has three parameters: </p> <ul>

<li id="GUID-6C1B960C-4455-504A-B115-7FB416D7A288"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> -

a reference to a DevSound Observer instance. </p> </li>

<li id="GUID-7D427CCC-6248-5C79-BB21-8D0E2C43C633"><p> <xref href="GUID-691F7FFC-D026-30D5-B08D-A06915272C92.dita"><apiname>TFourCC</apiname></xref> -

the <xref href="GUID-E18CF25C-82DE-3C69-BD86-5DF67579C1A6.dita"><apiname>CMMFHwDevice</apiname></xref> implementation FourCC code. </p> </li>

<li id="GUID-D459814C-4892-5A30-B86A-AC125BC9B0F7"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> -

the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li>

</ul> </li>

</ul> <p>All versions of <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> require

a reference to a DevSound Observer instance. As soon as initialization of

DevSound has completed, successfully or otherwise, the callback function <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-089CF9C1-92EF-3F40-8669-A5EF5C064AD4"><apiname>MDevSoundObserver::InitializeComplete()</apiname></xref> is

called. </p> <p><b>The

DevSound Observer</b> </p> <p>Most methods in the CMMFDevSound class are asynchronous.

Callbacks occur through the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> class. <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> is

an interface to a set of DevSound callback functions. It serves as the method

of communication between the client and the DevSound. A class that uses DevSound

will typically inherit from <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref>. </p> <p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> handles

the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-089CF9C1-92EF-3F40-8669-A5EF5C064AD4"><apiname>MDevSoundObserver::InitializeComplete()</apiname></xref> initialization

completion event. </p> </section>

<section><title>Purpose</title> <p>Refer to the following sections for detailed

information on how to use the main features of DevSound: </p> <ul>

<li id="GUID-5FC7D66B-50C0-5229-A343-80FA4E865828"><p><xref href="GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita">Playing

Audio</xref>  </p> </li>

<li id="GUID-E5B271E4-F39B-5E75-BEEA-34AF087B8DDF"><p><xref href="GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita">Recording

Audio</xref>  </p> </li>

<li id="GUID-BCC46964-D281-50B3-82E6-1A3CDC025455"><p><xref href="GUID-14BAAB7C-35CD-5A43-B362-79F88C7712DE.dita">Playing

Tones</xref>  </p> </li>

</ul> </section>

<section><title>Example uses</title> <p>These examples describe some different

uses of DevSound: </p> <p><b>Recording

a WAV file</b> </p> <p>In this example, a client application wants to record

a WAV file. As WAV is a standard file format supported by the MMF controller

framework, the <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client API is used

to interact with DevSound. </p> <p>The main steps in recording the WAV file

are: </p> <ol id="GUID-24DBEAE0-D054-53CD-965E-A89B7F66410C">

<li id="GUID-0A785BE2-5896-5490-9C6D-7C66BB575BF5"><p>The client application

gives a request to record to the MMF <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client

API. </p> </li>

<li id="GUID-14622FA3-A7FD-5DDD-9BD6-AD7B4CB9F04C"><p>The MMF <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client

API passes the command down through the controller framework to the MMF controller

plug-in. </p> </li>

<li id="GUID-F0400FAB-4644-5764-B806-FC4F9B3A42DF"><p>The MMF controller plug-in

initializes DevSound for recording. </p> </li>

<li id="GUID-692A4C69-6E04-52CE-9835-FD4E2B59D498"><p>Recording starts and

continues until the client stops the recording or the limit on the file size

is reached. </p> </li>

<li id="GUID-579CFF58-4C6D-51F1-9249-CB1BCCC7D08F"><p>Upon completion, the

client gives a request to the MMF controller framework to stop the recording.

The controller framework passes the command down to the MMF controller plug-in. </p> </li>

<li id="GUID-8F3214E6-DFA0-533A-BE7F-86657BFE82E0"><p>The MMF controller plug-in

stops DevSound and sends the completion event back to the client via controller

framework. </p> </li>

</ol> <p><b>Playing

a DTMF tone</b> </p> <p>In this example, a client application wants to play

a Dual-Tone Multi-Frequency (DTMF) tone. The MMF <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> client

API is used to play the DTMF tone. Unlike other MMF APIs, the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> does

not require a controller plug-in. This is because the input and output of

the API is already in a known data format and does not require encoding or

decoding. The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> communicates directly

with DevSound. </p> <p>The main steps in playing the DTMF tone are: </p> <ol id="GUID-653E4665-1469-5EDA-B83E-94DB580ECFB0">

<li id="GUID-5B600730-C908-5D5E-9C7E-05B8FAE685AA"><p>The client application

prepares the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> to play a DTMF tone. </p> </li>

<li id="GUID-EA9E73E1-AACE-52E8-BF8A-B11FE2117D2C"><p>The client application

asks the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> to start playing the tone. </p> </li>

<li id="GUID-4DE7CB4B-3873-5B5E-ADCF-2AC712ADB2C0"><p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> asks

DevSound to play the tone. </p> </li>

<li id="GUID-016EA63D-DF56-5ACC-9A8A-536092EE145F"><p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> informs

the client application that the playing of the tone is complete. </p> </li>

</ol> <p><b>Playing

an AVI file</b> </p> <p>In this example, a client application wants to play

an Audio Video Interleaved (AVI) file; output is to a screen and speakers.

The AVI file contains audio and video data, so the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref> class

that can manipulate both types of data is used. </p> <p>The main steps in

playing the AVI file are: </p> <ol id="GUID-D1F0C730-45BF-5B58-BBCE-3483C951BD72">

<li id="GUID-83EF3725-22BE-5140-96C6-8F530DC7AAA3"><p>The client application

requests to play an AVI file to the MMF CVideoPlayerUtility class. </p> </li>

<li id="GUID-C8C8E7D2-982F-5561-A707-BCC5131E7C8D"><p>The MMF CVideoPlayerUtility

class passes the request to the MMF controller framework. The controller framework

loads the AVI controller </p> </li>

<li id="GUID-980A38CF-CAA3-5A54-8888-A54AACF538B6"><p>The AVI controller plug-in

initializes the DevSound and DevVideo. </p> </li>

<li id="GUID-46DD25A9-62C1-5B6F-8BC8-21E57BB706F2"><p>The AVI controller plug-in

reads the data in the AVI file and sends the audio data to DevSound and the

video data to DevVideo. </p> </li>

<li id="GUID-CFDEDC57-E5BD-5680-AC20-1A8F10A6328D"><p>DevSound outputs the

audio data.</p> </li>

<li id="GUID-AB78F54C-76B8-419A-AC24-F22371AFB506"><p>DevVideo sends the video

data to be decoded to the corresponding codec. The decoded video data is then

displayed on the screen. </p></li>

</ol><note> AVI files support Dolby audio also. The client application requests

for Dolby play back are processed in the similar way.</note></section>

</conbody><related-links>

<link href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita"><linktext>DevSound

Overview</linktext></link>