<?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-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1" xml:lang="en"><title>How to use the audio tone player utility</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The Audio Tone Player, provided by the class <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref>, has an interface for generating the following tones on all audio
capable devices. Using this class you can play the following tones: </p>
<ul>
<li id="GUID-6F7555FF-A11D-5D34-9602-75E9B9F4E70E"><p>Single tone
of a specified duration and frequency </p> </li>
<li id="GUID-B99BA7D8-E58F-5206-AAEE-55D47DC0629B"><p>Dual Tone Multi
Frequency (DTMF) strings </p> </li>
<li id="GUID-97874FB6-0884-53D7-9667-EC96604DEF30"><p>Sequences of
tones held in files or descriptors </p> </li>
<li id="GUID-B4704DBA-54C9-5B74-B518-2F5EBA1396C9"><p>Predefined (fixed)
sequences of tones held in any mobile equipment </p> </li>
</ul>
<p>Client applications such as ringtone applications, use <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> to generate the tones they produce.
The tone player in turn uses MMF for playing sounds and is also credited
for interfacing with the audio hardware. An active scheduler is needed
for all the clients applications for the use of active objects and
callbacks. </p>
<section id="GUID-B86646DF-E472-556C-B9AF-F82CBAEE468A"><title>Using
the tone player</title> <p>The tone player provides a simple interface
to generate single and multiple tones. Once the tone player object
has been constructed, multiple tones and tone sequences can be played
without having to create new instances of the object. </p> <p>Using
the tone player typically involves the following steps: </p> <fig id="GUID-BF7D8243-53BE-5AF8-B9EF-4E7DC202AA1F">
<title>              Tone Player Utility            </title>
<image href="GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e314379_href.png" placement="inline"/>
</fig> <ol id="GUID-11853890-B5E8-5797-918B-A1105C35F5BC">
<li id="GUID-C1ED28E3-AF25-562B-B2BC-E70F2790961C"><p><xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-B5EAD538-CB1F-556C-B38D-26A4327B6454">Constructing a tone player </xref>  </p> </li>
<li id="GUID-ED14F3E0-7FCF-5B7C-B9B3-FCC048480302"><p><xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-60775FAF-EB16-5462-9EDD-B18E9831CB70">Preparing a tone player </xref>  </p> </li>
<li id="GUID-657C713C-82D4-5579-ACBD-1DA372972012"><p><xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-BA2A90F5-C36C-547E-B415-C877C22F321A">Playing a tone </xref>  </p> </li>
<li id="GUID-18F9686A-740F-582C-B4C7-547338231F28"><p><xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-0E2324A3-9290-56B4-BF68-A00FEF8B26ED">Cancelling a tone </xref>  </p> </li>
<li id="GUID-BB3FE6DE-FE3B-5E1E-A482-2359D638EE69"><p><xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-9D861D80-F6E4-577F-80AB-BD321D413764">Retrieving a custom interface </xref>  </p> </li>
</ol> <p id="GUID-B5EAD538-CB1F-556C-B38D-26A4327B6454"><b>Constructing a tone
player</b> </p> <p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> object
can be constructed using the <codeph>NewL()</codeph> member function.
There are two versions of this constructor function: </p> <ul>
<li id="GUID-A395EF84-C992-57B2-9A7A-2F9EE94E4E1E"><p>create a tone
player with default priority settings: </p> <codeblock id="GUID-C4C5F891-A369-5819-965E-D879941247D1" xml:space="preserve">static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver&amp; aObserver, CMdaServer* aServer=NULL);</codeblock> </li>
<li id="GUID-9152BA40-7543-5915-A508-1E98EAD288FD"><p>create a tone
player with your own settings: </p> <codeblock id="GUID-F5D92EE4-66D5-5BA5-9328-113F2AD289A1" xml:space="preserve">static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver&amp; aObserver, CMdaServer* aServer, TInt aPriority,
TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality); </codeblock> </li>
</ul> <p>Both functions pass a reference of the <xref href="GUID-A6D27F43-AC44-38EA-B16F-31A14390582E.dita"><apiname>MMdaAudioToneObserver</apiname></xref> object to the tone player. The <xref href="GUID-A6D27F43-AC44-38EA-B16F-31A14390582E.dita"><apiname>MMdaAudioToneObserver</apiname></xref> is an observer interface to notifications from the member functions <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-60775FAF-EB16-5462-9EDD-B18E9831CB70">Prepare</xref>, <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-BA2A90F5-C36C-547E-B415-C877C22F321A">Play</xref>, and, <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-0E2324A3-9290-56B4-BF68-A00FEF8B26ED">CancelPlay</xref> callback functions. </p> <p id="GUID-60775FAF-EB16-5462-9EDD-B18E9831CB70"><b>Preparing a tone
player</b> </p> <p>Once the tone player object is created, it has
to be prepared to play a tone or a DTMF string. use one of the following
prepare member functions to get it ready for playing the corresponding
tone. </p> <ul>
<li id="GUID-6B9AFA66-9748-5E38-A712-188A8CA6BA77"><p> <codeph> PrepareToPlayTone()</codeph> - to play a single tone of a fixed frequency (Hz) and duration (microseconds).
For example: </p> <codeblock id="GUID-B6943FB2-A5E5-5A92-A0BC-31AC567FE647" xml:space="preserve">virtual void PrepareToPlayTone(TInt    aFrequency, const TTimeIntervalMicroSeconds&amp; aDuration);</codeblock> </li>
<li id="GUID-28A30DA0-F52D-59E4-B05D-9A1D8CFBCE2A"><p> <codeph>PrepareToPlayDTMFString()</codeph> - to play a DTMF string held in a descriptor. For example: </p> <codeblock id="GUID-2D18C9CF-86CC-554C-9336-5C656EDD71E5" xml:space="preserve">virtual void PrepareToPlayDTMFString(const TDesC&amp; aDTMF);</codeblock> </li>
<li id="GUID-0F67C0F8-E60F-5B42-9536-231FE9086AB7"><p> <codeph>PrepareToPlayFileSequence()</codeph> - to play a sequence of non-DTMF tones held in a file. For example: </p> <codeblock id="GUID-7BCD3441-7CA9-581B-96E0-D230FBF6A7E4" xml:space="preserve">virtual void PrepareToPlayFileSequence(const TDesC&amp; aFilename);</codeblock> </li>
<li id="GUID-09048A04-0869-5208-B3BE-51217690527D"><p> <codeph>PrepareToPlayDesSequence()</codeph> - to play a sequence of non-DTMF tones held in a descriptor. For
example: </p> <codeblock id="GUID-52063B5D-1131-5236-A06F-BFD67A09CF71" xml:space="preserve">virtual void PrepareToPlayDesSequence(const TDesC8&amp; aSequence);</codeblock> </li>
<li id="GUID-6328FB13-16F3-51BC-9B13-F00E8B8532DB"><p> <codeph> PrepareToPlayFixedSequence()</codeph> - to play a sequence of non-DTMF tones stored on the mobile equipment.
For example: </p> <codeblock id="GUID-839C7AFA-0D3E-5D05-BA0C-34CEF841D3F7" xml:space="preserve">virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber); </codeblock> </li>
<li id="GUID-EB7F1FA3-849F-5169-B88F-49512CD1E14C"><p> <codeph>PrepareToPlayDualTone()</codeph> - to play a dual tone. For example: </p> <codeblock id="GUID-FBE9AAAE-E188-58C9-8167-0B7049BCAB13" xml:space="preserve">void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds&amp; aDuration); </codeblock> <p>The two tones, aFrequencyOne and aFrequencyTwo, are measured
in Hz, and the duration of the tone, aDuration, is measured in microseconds. </p> </li>
</ul> <p>All the prepare member functions are asynchronous. In response
to each, <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> creates a <codeph>CMMFToneConfig</codeph> derived object that stores the data for the
type of tone to play. </p> <p>On completion of a prepare, the observer
function <xref href="GUID-A6D27F43-AC44-38EA-B16F-31A14390582E.dita#GUID-A6D27F43-AC44-38EA-B16F-31A14390582E/GUID-6B3BF4AC-3E50-3927-A09F-E4E5DDD1AECA"><apiname>MMdaAudioToneObserver::MatoPrepareComplete()</apiname></xref> is called, indicating the success or failure of the prepare operation.
If successful you can play the tone. </p> <p>You can cancel any prepare
function using <xref href="GUID-D4BCECEA-A42F-372D-85D7-66762D2F7B0D.dita"><apiname>CancelPrepare()</apiname></xref> (the observer callback
function is <i>not</i> called on completion of the cancel). </p> <p id="GUID-BA2A90F5-C36C-547E-B415-C877C22F321A"><b>Playing a tone</b> </p> <p>Once the player is prepared successfully, certain configurations
can be done before playing the tone as listed below: </p> <ul>
<li id="GUID-6FAFAB95-55B7-5C74-BF0B-31962859DF32"><p> <xref href="GUID-657CDF11-EA74-3074-9872-412D2C26F3E6.dita"><apiname>Volume()</apiname></xref> and <xref href="GUID-171667CD-06F4-3DF5-A4E1-360422F362D2.dita"><apiname>SetVolume()</apiname></xref> - This retrieves the current
volume settings and sets to a new value specified by the user respectively. </p> </li>
<li id="GUID-F5BC6F5F-57C0-5BEC-9783-AF06358A59E2"><p> <xref href="GUID-C2B76645-A50F-3DFF-943B-4F3D5A33ED31.dita"><apiname>GetBalanceL()</apiname></xref> and <xref href="GUID-D1856981-6A17-3CD9-80B5-65781A803BA4.dita"><apiname>SetBalanceL()</apiname></xref> - This retrieves the current
balance of the audio device and sets the audio balance specified by
the user respectively.. </p> </li>
<li id="GUID-06D4BAEF-52CF-5CD8-90A2-8163336B016F"><p> <xref href="GUID-A2BDF5F7-06F0-3788-905E-D53FC9C67446.dita"><apiname>SetPriority()</apiname></xref> - This sets the priority of the audio device. The priority is defined
to arbitrate between multiple objects trying to access the controller
at the same time. </p> </li>
<li id="GUID-0109EFE3-8CA8-5E5A-B4F5-693E87BEEE0E"><p> <xref href="GUID-5B03528A-E19C-3782-95E0-179E0C03B349.dita"><apiname>SetVolumeRamp()</apiname></xref> - This defines the period over which the volume level is to rise
(in microseconds) smoothly from zero to the specified volume level.
A value of <codeph>0</codeph> causes the tone to be played at the <codeph>SetVolume()</codeph> level for the full duration of the playback.
A value that is longer than the duration of the tone sequence means
that the tone never reaches the specified volume. </p> <codeblock id="GUID-AB8860AD-2E15-5DF1-97B2-BA9BDA2D5D38" xml:space="preserve">virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds &amp;aRampDuration);</codeblock> </li>
<li id="GUID-47A3F620-FA41-5A85-B9E4-3D8BA3D9251B"><p> <xref href="GUID-9BBB8929-42B9-3862-BEFF-D845D4EC8E4E.dita"><apiname>SetDTMFLengths() </apiname></xref> - This alters the duration of DTMF tone, the gaps between two DTMF
tones, and the pauses in microseconds. </p> </li>
<li id="GUID-5AC9A8EF-995D-5FD7-9AAD-309673819F33"><p> <xref href="GUID-CD5229CE-04B7-3CED-B997-688C9251D1B9.dita"><apiname>FixedSequenceCount() </apiname></xref> - This returns the number of available pre-defined tone sequences,
the number always being greater than zero. </p> </li>
<li id="GUID-A5118A3F-43BF-5A34-B552-C0B57937928B"><p> <xref href="GUID-ECB22EFB-F630-35FB-9153-6D130945412E.dita"><apiname>FixedSequenceName()</apiname></xref> - This returns the name of the specified fixed tone sequence. </p> </li>
</ul> <p>Upon successful configuration, the Play() can be called as
shown below. </p> <p> <codeph> Play()</codeph> - plays the tone, DTMF
or tone sequence specified by the prepare statement. For example: </p> <codeblock id="GUID-D152802E-768B-5001-B362-05F7438B5106" xml:space="preserve">virtual void Play();</codeblock> <p>Here, the tone player uses the <xref href="GUID-E9006092-2ED1-3486-985A-0A4821FF90EC.dita"><apiname>Play()</apiname></xref> from
the audio player utility to play the tone. </p> <p>This function is
asynchronous. It retrieves the details of the type of tone to play
from the previous <codeph>Prepare</codeph> statement. When the tone
has been played to completion, the observer callback function <xref href="GUID-A6D27F43-AC44-38EA-B16F-31A14390582E.dita#GUID-A6D27F43-AC44-38EA-B16F-31A14390582E/GUID-65AAF2C6-FD4F-3365-99F7-FCD15287A1B9"><apiname>MMdaAudioToneObserver::MatoPlayComplete()</apiname></xref> is called, indicating
the success or failure of the play operation. The play operation can
be cancelled by calling the <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-0E2324A3-9290-56B4-BF68-A00FEF8B26ED">CancelPlay()</xref> member function. </p> <p>Playing the tone or
DTMF string can be customised using the following member functions
as mentioned below: </p> <ul>
<li id="GUID-03F93CEA-1B61-5262-B720-2313E79662E6"><p> <codeph>SetRepeats()</codeph> - sets the number of times the tone sequence (plus an optional trailing
silent period, measured in microseconds) is repeated during the play
operation. For example: </p> <codeblock id="GUID-7B2A1D5A-BB07-5CAA-86F3-CF7C011A939A" xml:space="preserve">virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds &amp;aTrailingSilence);</codeblock> <p>You can repeat the tone sequence indefinitely by setting <codeph>aRepeatNumberOfTimes</codeph> to <codeph>KMdaRepeatForever</codeph>. </p> </li>
<li id="GUID-5E34283D-17EF-59FC-842E-AD54DF7659C4"><p> <codeph>State()</codeph> - returns the current state of the tone player (an enum): </p> <ul>
<li id="GUID-A997198F-F638-5071-9333-6835E24EB23B"><p> <codeph>EMdaAudioToneUtilityNotReady</codeph> - not prepared to play a tone </p> </li>
<li id="GUID-CAF8DAEB-E147-5F08-B86C-E3C3735690EB"><p> <codeph>EMdaAudioToneUtilityPrepared</codeph> - prepared and ready to play a tone </p> </li>
<li id="GUID-F10E01C6-F237-58E9-8213-423FEAAE3DDC"><p> <codeph>EMdaAudioToneUtilityPlaying</codeph> - currently playing a tone </p> </li>
</ul> <p>For example: </p> <codeblock id="GUID-B2BB2135-C055-5A5E-B66B-63118DD7F654" xml:space="preserve">virtual TMdaAudioToneUtilityState State();</codeblock> </li>
</ul> <p>To play another tone or sequence, either wait for <xref href="GUID-A6D27F43-AC44-38EA-B16F-31A14390582E.dita#GUID-A6D27F43-AC44-38EA-B16F-31A14390582E/GUID-65AAF2C6-FD4F-3365-99F7-FCD15287A1B9"><apiname>MMdaAudioToneObserver::MatoPlayComplete()</apiname></xref> callback to be
issued when the current tone or DTMF string completes playing, or
use <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita#GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1/GUID-0E2324A3-9290-56B4-BF68-A00FEF8B26ED">CancelPlay()</xref> and then issue the relevant prepare statement.
The <xref href="GUID-E9006092-2ED1-3486-985A-0A4821FF90EC.dita"><apiname>Play()</apiname></xref> function following the prepare statement
plays the tone or DTMF string based on the previously issued prepare
statement. </p> <p id="GUID-0E2324A3-9290-56B4-BF68-A00FEF8B26ED"><b>Cancelling a tone</b> </p> <p> <xref href="GUID-E5898C2C-12A4-3803-BB97-A9C3F3CDDDE4.dita"><apiname>CancelPlay()</apiname></xref> - cancels the tone, DTMF,
or tone sequence currently playing. For example: </p> <codeblock id="GUID-5F4A763E-BB07-5ACC-BC6C-6EA78DC85A44" xml:space="preserve">virtual void CancelPlay();</codeblock> <p>The observer callback function is <i>not</i> called on completion
of the cancel. </p> <p id="GUID-9D861D80-F6E4-577F-80AB-BD321D413764"><b>Retrieving a custom
interface</b> </p> <p>To retrieve a custom interface to the underlying
device, use the <codeph>CustomInterface()</codeph> member function.
For example: </p> <codeblock id="GUID-AC62D116-853B-5216-9E22-FB9A68A53179" xml:space="preserve">IMPORT_C TAny *CustomInterface(TUid aInterfaceId);</codeblock> <p> <codeph>aInterfaceId</codeph> is the UID of the interface function
required. </p> <p>The function returns a pointer to the interface
implementation, or NULL if the device does not implement the interface
requested. You must cast the return value to the correct type. </p> </section>
<section id="GUID-E2511DB8-AC9C-48ED-8877-37BFA7FB3647"><title>See
Also</title> <p><xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita">How to use the audio convert utility</xref>  </p> </section>
</conbody></concept>