12 <concept xml:lang="en" id="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1"><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>

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

    13              Tone Player Utility 

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

    14           </title> <image href="GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e307907_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,

    14 capable devices. Using this class you can play the following tones: </p>

    15 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><title>See Also</title> <p><xref href="GUID-4E1F04EB-09EA-5354-8EFF-BBC95F44C9AE.dita">How to use the audio player utility</xref>  </p> <p><xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita">How to use the audio convert utility</xref>  </p> <p><xref href="GUID-BA2EEEC3-86AC-5B1C-81E2-CC571EB5AB3E.dita">How to use audio recorder utility</xref>  </p> </section> </conbody></concept>

    15 <ul>

    16 <li id="GUID-6F7555FF-A11D-5D34-9602-75E9B9F4E70E"><p>Single tone

    17 of a specified duration and frequency </p> </li>

    18 <li id="GUID-B99BA7D8-E58F-5206-AAEE-55D47DC0629B"><p>Dual Tone Multi

    19 Frequency (DTMF) strings </p> </li>

    20 <li id="GUID-97874FB6-0884-53D7-9667-EC96604DEF30"><p>Sequences of

    21 tones held in files or descriptors </p> </li>

    22 <li id="GUID-B4704DBA-54C9-5B74-B518-2F5EBA1396C9"><p>Predefined (fixed)

    23 sequences of tones held in any mobile equipment </p> </li>

    24 </ul>

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

    26 The tone player in turn uses MMF for playing sounds and is also credited

    27 for interfacing with the audio hardware. An active scheduler is needed

    28 for all the clients applications for the use of active objects and

    29 callbacks. </p>

    30 <section id="GUID-B86646DF-E472-556C-B9AF-F82CBAEE468A"><title>Using

    31 the tone player</title> <p>The tone player provides a simple interface

    32 to generate single and multiple tones. Once the tone player object

    33 has been constructed, multiple tones and tone sequences can be played

    34 without having to create new instances of the object. </p> <p>Using

    35 the tone player typically involves the following steps: </p> <fig id="GUID-BF7D8243-53BE-5AF8-B9EF-4E7DC202AA1F">

    36 <title>              Tone Player Utility            </title>

    37 <image href="GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e314379_href.png" placement="inline"/>

    38 </fig> <ol id="GUID-11853890-B5E8-5797-918B-A1105C35F5BC">

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

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

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

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

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

    44 </ol> <p id="GUID-B5EAD538-CB1F-556C-B38D-26A4327B6454"><b>Constructing a tone

    45 player</b> </p> <p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> object

    46 can be constructed using the <codeph>NewL()</codeph> member function.

    47 There are two versions of this constructor function: </p> <ul>

    48 <li id="GUID-A395EF84-C992-57B2-9A7A-2F9EE94E4E1E"><p>create a tone

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

    50 <li id="GUID-9152BA40-7543-5915-A508-1E98EAD288FD"><p>create a tone

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

    52 TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality); </codeblock> </li>

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

    54 player</b> </p> <p>Once the tone player object is created, it has

    55 to be prepared to play a tone or a DTMF string. use one of the following

    56 prepare member functions to get it ready for playing the corresponding

    57 tone. </p> <ul>

    58 <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).

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

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

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

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

    63 example: </p> <codeblock id="GUID-52063B5D-1131-5236-A06F-BFD67A09CF71" xml:space="preserve">virtual void PrepareToPlayDesSequence(const TDesC8&amp; aSequence);</codeblock> </li>

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

    65 For example: </p> <codeblock id="GUID-839C7AFA-0D3E-5D05-BA0C-34CEF841D3F7" xml:space="preserve">virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber); </codeblock> </li>

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

    67 in Hz, and the duration of the tone, aDuration, is measured in microseconds. </p> </li>

    68 </ul> <p>All the prepare member functions are asynchronous. In response

    69 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

    70 type of tone to play. </p> <p>On completion of a prepare, the observer

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

    72 If successful you can play the tone. </p> <p>You can cancel any prepare

    73 function using <xref href="GUID-D4BCECEA-A42F-372D-85D7-66762D2F7B0D.dita"><apiname>CancelPrepare()</apiname></xref> (the observer callback

    74 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

    75 can be done before playing the tone as listed below: </p> <ul>

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

    77 volume settings and sets to a new value specified by the user respectively. </p> </li>

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

    79 balance of the audio device and sets the audio balance specified by

    80 the user respectively.. </p> </li>

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

    82 to arbitrate between multiple objects trying to access the controller

    83 at the same time. </p> </li>

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

    85 (in microseconds) smoothly from zero to the specified volume level.

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

    87 A value that is longer than the duration of the tone sequence means

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

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

    90 tones, and the pauses in microseconds. </p> </li>

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

    92 the number always being greater than zero. </p> </li>

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

    94 </ul> <p>Upon successful configuration, the Play() can be called as

    95 shown below. </p> <p> <codeph> Play()</codeph> - plays the tone, DTMF

    96 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

    97 the audio player utility to play the tone. </p> <p>This function is

    98 asynchronous. It retrieves the details of the type of tone to play

    99 from the previous <codeph>Prepare</codeph> statement. When the tone

   100 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

   101 the success or failure of the play operation. The play operation can

   102 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

   103 DTMF string can be customised using the following member functions

   104 as mentioned below: </p> <ul>

   105 <li id="GUID-03F93CEA-1B61-5262-B720-2313E79662E6"><p> <codeph>SetRepeats()</codeph> - sets the number of times the tone sequence (plus an optional trailing

   106 silent period, measured in microseconds) is repeated during the play

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

   108 <li id="GUID-5E34283D-17EF-59FC-842E-AD54DF7659C4"><p> <codeph>State()</codeph> - returns the current state of the tone player (an enum): </p> <ul>

   109 <li id="GUID-A997198F-F638-5071-9333-6835E24EB23B"><p> <codeph>EMdaAudioToneUtilityNotReady</codeph> - not prepared to play a tone </p> </li>

   110 <li id="GUID-CAF8DAEB-E147-5F08-B86C-E3C3735690EB"><p> <codeph>EMdaAudioToneUtilityPrepared</codeph> - prepared and ready to play a tone </p> </li>

   111 <li id="GUID-F10E01C6-F237-58E9-8213-423FEAAE3DDC"><p> <codeph>EMdaAudioToneUtilityPlaying</codeph> - currently playing a tone </p> </li>

   112 </ul> <p>For example: </p> <codeblock id="GUID-B2BB2135-C055-5A5E-B66B-63118DD7F654" xml:space="preserve">virtual TMdaAudioToneUtilityState State();</codeblock> </li>

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

   114 issued when the current tone or DTMF string completes playing, or

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

   116 The <xref href="GUID-E9006092-2ED1-3486-985A-0A4821FF90EC.dita"><apiname>Play()</apiname></xref> function following the prepare statement

   117 plays the tone or DTMF string based on the previously issued prepare

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

   119 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

   120 of the cancel. </p> <p id="GUID-9D861D80-F6E4-577F-80AB-BD321D413764"><b>Retrieving a custom

   121 interface</b> </p> <p>To retrieve a custom interface to the underlying

   122 device, use the <codeph>CustomInterface()</codeph> member function.

   123 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

   124 required. </p> <p>The function returns a pointer to the interface

   125 implementation, or NULL if the device does not implement the interface

   126 requested. You must cast the return value to the correct type. </p> </section>

   127 <section id="GUID-E2511DB8-AC9C-48ED-8877-37BFA7FB3647"><title>See

   128 Also</title> <p><xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita">How to use the audio convert utility</xref>  </p> </section>

   129 </conbody></concept>