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