#include <mdaaudiotoneplayer.h>
| class CMdaAudioToneUtility : public CBase |
| Protected Attributes | |
|---|---|
| CMMFMdaAudioToneUtility * | iProperties |
Generates tones on an audio capable EPOC device.
The class offers an interface for generating tones on all audio capable EPOC devices.
To use the tone utility:
1. Create an instance by calling NewL().
2. Call the appropriate PrepareToPlay variant for the required tone type and wait for the callback indicating success.
3. Call Play and either wait for the callback to indicate completion, or call CancelPlay to end playback early.
4. Delete the instance.
It is possible to call Play before calling any PrepareToPlay variant. This will result in a default fixed sequence tone being played.
| CMMFMdaAudioToneUtility * | iProperties | [protected] |
This member is internal and not intended for use.
| ~CMdaAudioToneUtility | ( | ) |
Destructor. Frees any resources held by the tone player
| void | CancelPlay | ( | ) | [virtual] |
Cancels the tone playing operation.
The observer callback function MMdaAudioToneObserver::MatoPlayComplete() is not called.
| void | CancelPrepare | ( | ) | [virtual] |
Cancels the configuration operation.
The observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is not called.
Retrieves a custom interface to the underlying device.
| Parameter | Description |
|---|---|
| aInterfaceId | The interface UID, defined with the custom interface. |
Returns: A pointer to the interface implementation, or NULL if the device does not implement the interface requested. The return value must be cast to the correct type by the user.
| TInt | FixedSequenceCount | ( | ) | [virtual] |
Returns the number of available pre-defined tone sequences.
Returns: The number of tone sequences. This value is implementation dependent but is always greater than or equal to zero.
Returns the name assigned to a specific pre-defined tone sequence.
See also: CMMFDevSound::FixedSequenceName(TInt aSequenceNumber) FixedSequenceCount()
| Parameter | Description |
|---|---|
| aSequenceNumber | The index identifying the specific pre-defined tone sequence. Index values are relative to zero. This can be any value from zero to the value returned by a call to FixedSequenceCount() - 1. The function raises a panic if sequence number is not within this range. |
Returns: The name assigned to the tone sequence.
| IMPORT_C TInt | GetBalanceL | ( | ) |
Returns The current playback balance.This function may not return the same value as passed to SetBalanceL depending on the internal implementation in the underlying components.
Returns: The balance. Should be between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.
| TInt | MaxVolume | ( | ) | [virtual] |
Returns the maximum volume supported by the device. This is the maximum value which can be passed to CMdaAudioToneUtility::SetVolume().
Returns: The maximum volume. This value is platform dependent but is always greater than or equal to one.
| IMPORT_C CMdaAudioToneUtility * | NewL | ( | MMdaAudioToneObserver & | aObserver, |
| CMdaServer * | aServer = NULL | |||
| ) | [static] | |||
Creates a new instance of the tone player utility. The default volume is set to MaxVolume() / 2.
| Parameter | Description |
|---|---|
| aObserver | A class to receive notifications from the tone player. |
| aServer | This parameter is no longer used and should be NULL. |
Returns: A pointer to the new audio tone player utility object.
| IMPORT_C CMdaAudioToneUtility * | NewL | ( | MMdaAudioToneObserver & | aObserver, |
| CMdaServer * | aServer, | |||
| TInt | aPriority, | |||
| TInt | aPref = EMdaPriorityPreferenceTimeAndQuality | |||
| ) | [static] | |||
Creates a new instance of the tone player utility. The default volume is set to MaxVolume() / 2.
| Parameter | Description |
|---|---|
| aObserver | A class to receive notifications from the tone player |
| aServer | This parameter is no longer used and should be NULL |
| aPriority | The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request. |
| aPref | The Priority Preference - an additional audio policy parameter. The suggested default is EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional values may be supported by given phones and/or platforms, but should not be depended upon by portable code. |
Returns: A pointer to the new audio tone player utility object.
| void | Play | ( | ) | [virtual] |
Plays the tone.
The tone played depends on the current configuration.This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPlayComplete() is called, indicating the success or failure of the play operation.The play operation can be cancelled by calling CMdaAudioToneUtility::CancelPlay().
| void | PrepareToPlayDTMFString | ( | const TDesC & | aDTMF | ) | [virtual] |
Configures the audio tone utility player to play a DTMF (Dual-Tone Multi-Frequency) string.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aDTMF | A descriptor containing the DTMF string. |
| void | PrepareToPlayDesSequence | ( | const TDesC8 & | aSequence | ) | [virtual] |
Configures the audio tone player utility to play a tone sequence contained in a descriptor.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aSequence | The descriptor containing the tone sequence. The format of the data is unspecified but is expected to be platform dependent. A device might support more than one form of sequence data. |
| IMPORT_C void | PrepareToPlayDualTone | ( | TInt | aFrequencyOne, |
| TInt | aFrequencyTwo, | |||
| const TTimeIntervalMicroSeconds & | aDuration | |||
| ) | ||||
Configures the audio tone player utility to play a dual tone. The generated tone consists of two sine waves of different frequencies summed together.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aFrequencyOne | The first frequency (pitch) of the tone. |
| aFrequencyTwo | The second frequency (pitch) of the tone. |
| aDuration | The duration of the tone in microseconds. |
| void | PrepareToPlayFileSequence | ( | const TDesC & | aFileName | ) | [virtual] |
Configures the audio tone player utility to play a tone sequence contained in a file.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aFileName | The full path name of the file containing the tone sequence. The format of the data is unspecified but is expected to be platform dependent. A device might support more than one form of sequence data. |
| IMPORT_C void | PrepareToPlayFileSequence | ( | RFile & | aFile | ) |
Configures the audio tone player utility to play a tone sequence contained in a file.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aFile | A handle to an open file containing the tone sequence. The format of the data is unspecified but is expected to be platform dependent. A device might support more than one form of sequence data. |
| void | PrepareToPlayFixedSequence | ( | TInt | aSequenceNumber | ) | [virtual] |
Configures the audio tone player utility to play the specified pre-defined tone sequence.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation. The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
See also: FixedSequenceCount() CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)
| Parameter | Description |
|---|---|
| aSequenceNumber | An index into the set of pre-defined tone sequences. This can be any value from zero to the value returned by a call to FixedSequenceCount() - 1. If the sequence number is not within this range, a panic will be raised when Play() is called later. |
| void | PrepareToPlayTone | ( | TInt | aFrequency, |
| const TTimeIntervalMicroSeconds & | aDuration | |||
| ) | [virtual] | |||
Configures the audio tone player utility to play a single tone.
This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the configuration operation.The configuration operation can be cancelled by calling CMdaAudioToneUtility::CancelPrepare(). The configuration operation cannot be started if a play operation is in progress.
| Parameter | Description |
|---|---|
| aFrequency | The frequency (pitch) of the tone in Hz. |
| aDuration | The duration of the tone in microseconds. |
| IMPORT_C void | RegisterPlayStartCallback | ( | MMdaAudioTonePlayStartObserver & | aObserver | ) |
| IMPORT_C void | SetBalanceL | ( | TInt | aBalance = KMMFBalanceCenter | ) |
Sets the stereo balance for playback.
| Parameter | Description |
|---|---|
| aBalance | The balance. Should be between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. |
Returns: An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.
| void | SetDTMFLengths | ( | TTimeIntervalMicroSeconds32 | aToneLength, |
| TTimeIntervalMicroSeconds32 | aToneOffLength, | |||
| TTimeIntervalMicroSeconds32 | aPauseLength | |||
| ) | [virtual] | |||
Changes the duration of DTMF tones, the gaps between DTMF tones and the pauses.
| Parameter | Description |
|---|---|
| aToneLength | The duration of the DTMF tone in microseconds. |
| aToneOffLength | The gap between DTFM tones in microseconds. |
| aPauseLength | Pauses in microseconds |
| Parameter | Description |
|---|---|
| aPriority | The Priority Value. |
| aPref | The Priority Preference. |
| void | SetRepeats | ( | TInt | aRepeatNumberOfTimes, |
| const TTimeIntervalMicroSeconds & | aTrailingSilence | |||
| ) | [virtual] | |||
Sets the number of times the tone sequence is to be repeated during the play operation.
A period of silence can follow each playing of the tone sequence. The tone sequence can be repeated indefinitely.
| Parameter | Description |
|---|---|
| aRepeatNumberOfTimes | The number of times the tone sequence, together with the trailing silence, is to be repeated. If this is set to KMdaRepeatForever, then the tone sequence, together with the trailing silence, is repeated indefinitely. The behaviour is undefined for values other than KMdaRepeatForever, zero and positive. |
| aTrailingSilence | The time interval of the training silence. The behaviour is undefined for values other than zero and positive. |
| void | SetVolume | ( | TInt | aVolume | ) | [virtual] |
Changes the volume of the audio device.
The volume can be changed before or during play and is effective immediately.
| Parameter | Description |
|---|---|
| aVolume | The volume setting. This can be any value from zero to the value returned by a call to CMdaAudioToneUtility::MaxVolume(). Setting a zero value mutes the sound. Setting the maximum value results in the loudest possible sound. |
| void | SetVolumeRamp | ( | const TTimeIntervalMicroSeconds & | aRampDuration | ) | [virtual] |
Defines the period over which the volume level is to rise smoothly from nothing to the normal volume level.
| Parameter | Description |
|---|---|
| aRampDuration | The period over which the volume is to rise. A zero value causes the tone to be played at the normal level for the full duration of the playback. A value which is longer than the duration of the tone sequence means that the tone never reaches its normal volume level. |
| TMdaAudioToneUtilityState | State | ( | ) | [virtual] |
Returns the current state of the audio tone utility.
Returns: The state of the audio tone utility.
| TInt | Volume | ( | ) | [virtual] |
Returns an integer representing the current volume of the audio device.
Returns: The current volume.