<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-3AB05112-0580-5FD2-AD61-5721090062F8"><title>Playing a DTMF Tone </title><shortdesc>This tutorial describes about how to play a DTMF(Dual and Multi-Frequency) Tone. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><context id="GUID-854FEBE3-1B14-58B6-9611-726B35221199"><p>You have to configure DevSound in order to play a DTMF tone. </p> <p>The following settings can be configured before or during DTMF tone play: </p> <ul><li id="GUID-CA520BAE-8D2C-529F-8B7C-86F54C9F9E5F"><p>To set the duration of tone on, tone off and tone pause to be used during the DTMF tone playback, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-4ABD974B-581A-3140-9B77-61DAA415F707"><apiname>CMMFDevSound::SetDTMFLengths()</apiname></xref> method. </p> <codeblock id="GUID-0A41F048-4C1F-5EED-993B-D60AAFCA4FAD" xml:space="preserve">IMPORT_C void SetDTMFLengths(TTimeIntervalMicroSeconds32 &amp;aToneOnLength,

TTimeIntervalMicroSeconds32 &aToneOffLength, TTimeIntervalMicroSeconds32

&amp;aPauseLength);</codeblock> <p>This method has three parameters: </p> <ul><li id="GUID-F99B5C58-B8F0-529B-9034-F3F452DA4292"><p> <codeph>&amp;aToneOnLength</codeph> - the period over which the tone is to be played. </p> </li> <li id="GUID-541A2E02-9B7D-591D-A528-7E1061F01D0C"><p> <codeph>&amp;aToneOffLength</codeph> - the period over which no tone is to be played. </p> </li> <li id="GUID-FFED4A25-5CDE-5089-94B2-9C6616DF45CF"><p> <codeph>&amp;aPauseLength</codeph> - the period over which tone playing is to be paused. </p> </li> </ul> <p>The internal configuration set by <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-4ABD974B-581A-3140-9B77-61DAA415F707"><apiname>CMMFDevSound::SetDTMFLengths()</apiname></xref> lasts until it is recalled or for the lifetime of the current DevSound. </p> <p> <b>Note:</b> The <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-4ABD974B-581A-3140-9B77-61DAA415F707"><apiname>CMMFDevSound::SetDTMFLengths()</apiname></xref> function is only available during tone play. </p> </li> <li id="GUID-CA645A0A-8C12-5C23-A204-586F36512811"><p>To change the volume of the audio device to a specific value, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-C93E8531-F569-3F6B-AE65-A36749FCE7DF"><apiname>CMMFDevSound::SetVolume()</apiname></xref> function. The volume can be set to any value from 0 to <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-1BFCB3CB-17C7-399B-9089-3ADFF43044BA"><apiname>CMMFDevSound::MaxVolume()</apiname></xref>. </p> <p>To define a period over which the volume rises from 0 to the normal volume level, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-AF47B65D-DEFA-3D11-B6AB-2DC876D25EF7"><apiname>CMMFDevSound::SetVolumeRamp()</apiname></xref> function. </p> <p> <b>Note:</b> The <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-AF47B65D-DEFA-3D11-B6AB-2DC876D25EF7"><apiname>CMMFDevSound::SetVolumeRamp()</apiname></xref> function is only available during tone play. </p> </li> <li id="GUID-050B5D58-E553-5AFB-A2E2-47D18A7348EF"><p>To set the speaker balance, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-0D55BCC4-9882-3F49-B1AD-922B48264F79"><apiname>CMMFDevSound::SetPlayBalanceL()</apiname></xref> function. This function has two parameters: </p> <ul><li id="GUID-9BC592DA-3FA0-5E53-9A6B-FCE8E96BE571"><p> <codeph>aLeftPercentage</codeph> - the left speaker volume percentage. </p> </li> <li id="GUID-1665ED4B-A1F5-53A3-9E52-AD1563DE38B5"><p> <codeph>aRightPercentage</codeph> - the right speaker volume percentage. </p> </li> </ul> </li> <li id="GUID-15C166D6-6A38-5ED0-8577-2DA83495D78D"><p>To set the priority setting for this instance of DevSound to access the audio device, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-1B3B1694-EED8-3B33-B424-C48DDAFBE75A"><apiname>CMMFDevSound::SetPrioritySettings()</apiname></xref> method. Priority settings are used by the Audio Policy component to resolve multiple requests to access the audio hardware. </p> </li> </ul> </context> <steps-unordered id="GUID-8A80C27C-595F-52F1-A63A-FF51BA577D73"><step id="GUID-D25C17DC-DFC2-52EA-98E7-DD624C9584C4"><cmd/><info>Call the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-3E9E0095-DC9A-3ABF-90E9-1B2ED469BBC4"><apiname>CMMFDevSound::PlayDTMFStringL(const TDesC

                &amp;)</apiname></xref> function to start playing a DTMF tone. </info> <info> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-BFB5A0E2-4B6F-3ABA-BC7E-BA125B24FC13"><apiname>CMMFDevSound::PlayDTMFStringL()</apiname></xref> has one parameter, <codeph>&amp;aDTMFString</codeph>, the DTMF sequence in a descriptor. </info> </step> <step id="GUID-B08CA1F1-6F7E-5306-9C3D-E3CB4CD15334"><cmd/><info>If <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-4ABD974B-581A-3140-9B77-61DAA415F707"><apiname>CMMFDevSound::SetDTMFLengths()</apiname></xref> is called during play, it takes effect when the next tone is generated. </info> </step> <step id="GUID-06B40730-06FA-5A08-9AF2-52B771FB6460"><cmd/><info>When an attempt to play DTMF tones has completed, successfully or otherwise, DevSound calls the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-8AD3FCA2-84C3-3BFC-B0A9-CEAF132D0BF5"><apiname>MDevSoundObserver::ToneFinished(TInt)</apiname></xref> function. </info> <info> Note: Further calls to <codeph>CMMFDevSound::PlayDTMFStringL(const TDesC &amp;)</codeph> can be made both before and after the <codeph>MDevSoundObserver::ToneFinished(TInt)</codeph> callback is received. </info> </step> </steps-unordered> </taskbody><related-links><link href="GUID-DD8BFFF1-15C7-59B0-A107-C5CC90DBF4CC.dita"><linktext>Pausing and

                Resuming a Tone</linktext> </link> </related-links></task>