CMdaAudioToneUtility in Multimedia Multimedia

class CMdaAudioToneUtility : public CBase, public MMMFClientUtility;

Description

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 CMdaAudioToneUtility::NewL(MMdaAudioToneObserver &,CMdaServer *).

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.

Derivation

MMMFClientUtility - No description.
CBase - Base class for all classes to be instantiated on the heap.

CMdaAudioToneUtility - Generates tones on an audio capable EPOC device.

Members

Defined in CMdaAudioToneUtility:

CancelPlay()Cancels the tone playing operation.
CancelPrepare()Cancels the configuration operation.
CustomInterface(TUid)Retrieves a custom interface to the underlying device.
FixedSequenceCount()Returns the number of available pre-defined tone sequences.
FixedSequenceName(TInt)Returns the name assigned to a specific pre-defined tone sequence.
GetBalanceL()Returns The current playback balance.This function may not return the same value...
MaxVolume()Returns the maximum volume supported by the device. This is the maximum value wh...
NewL(MMdaAudioToneObserver &,CMdaServer *)Creates a new instance of the tone player utility. The default volume is set to ...
NewL(MMdaAudioToneObserver &,CMdaServer *,TInt,TMdaPriorityPreference)Creates a new instance of the tone player utility. The default volume is set to ...
Play()Plays the tone.
PrepareToPlayDTMFString(const TDesC &)Configures the audio tone utility player to play a DTMF (Dual-Tone Multi-Frequen...
PrepareToPlayDesSequence(const TDesC8 &)Configures the audio tone player utility to play a tone sequence contained in a ...
PrepareToPlayDualTone(TInt,TInt,const TTimeIntervalMicroSeconds &)Configures the audio tone player utility to play a dual tone. The generated tone...
PrepareToPlayFileSequence(RFile &)Configures the audio tone player utility to play a tone sequence contained in a ...
PrepareToPlayFileSequence(const TDesC &)Configures the audio tone player utility to play a tone sequence contained in a ...
PrepareToPlayFixedSequence(TInt)Configures the audio tone player utility to play the specified pre-defined tone ...
PrepareToPlayTone(TInt,const TTimeIntervalMicroSeconds &)Configures the audio tone player utility to play a single tone.
SetBalanceL(TInt)Sets the stereo balance for playback.
SetDTMFLengths(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32)Changes the duration of DTMF tones, the gaps between DTMF tones and the pauses.
SetPriority(TInt,TMdaPriorityPreference)Changes the clients priority.
SetRepeats(TInt,const TTimeIntervalMicroSeconds &)Sets the number of times the tone sequence is to be repeated during the play ope...
SetVolume(TInt)Changes the volume of the audio device.
SetVolumeRamp(const TTimeIntervalMicroSeconds &)Defines the period over which the volume level is to rise smoothly from nothing ...
State()Returns the current state of the audio tone utility.
Volume()Returns an integer representing the current volume of the audio device.
iPropertiesThis member is internal and not intended for use.

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
Extension_(TUint,TAny *&,TAny *)Extension function
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

IMPORT_C static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver &aObserver, CMdaServer *aServer=0);

Description

Creates a new instance of the tone player utility. The default volume is set to CMdaAudioToneUtility::MaxVolume() / 2.

Parameters

`MMdaAudioToneObserver &aObserver`	A class to receive notifications from the tone player.
`CMdaServer *aServer`	This parameter is no longer used and should be NULL.

Return value

CMdaAudioToneUtility *

A pointer to the new audio tone player utility object.

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

IMPORT_C static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver &aObserver, CMdaServer *aServer, TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

Description

Creates a new instance of the tone player utility. The default volume is set to CMdaAudioToneUtility::MaxVolume() / 2.

Parameters

`MMdaAudioToneObserver &aObserver`	A class to receive notifications from the tone player
`CMdaServer *aServer`	This parameter is no longer used and should be NULL
`TInt aPriority`	A priority between EMdaPriorityMin and EMdaPriorityMax
`TMdaPriorityPreference aPref`	`Time` vs Quality priority preferences, enumerated in TMdaPriorityPreference

Return value

CMdaAudioToneUtility *

A pointer to the new audio tone player utility object.

virtual TMdaAudioToneUtilityState State();

Description

Returns the current state of the audio tone utility.

Return value

TMdaAudioToneUtilityState

The state of the audio tone utility.

virtual TInt MaxVolume();

Description

Returns the maximum volume supported by the device. This is the maximum value which can be passed to CMdaAudioToneUtility::SetVolume(TInt).

Return value

TInt

The maximum volume. This value is platform dependent but is always greater than or equal to one.

virtual TInt Volume();

Description

Returns an integer representing the current volume of the audio device.

Return value

TInt

The current volume.

virtual void SetVolume(TInt aVolume);

Description

Changes the volume of the audio device.

The volume can be changed before or during play and is effective immediately.

Parameters


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

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

virtual void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

Description

Changes the clients priority.

Parameters

`TInt aPriority`	This client's relative priority. This is a value between -100 and +100 and represents a relative priority. A higher value indicates a more important request. The absolute priority at which a client application runs depends on the EPOC platform.
`TMdaPriorityPreference aPref`	The required behaviour if a higher priority client takes over the sound output device.

virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32 aToneLength, TTimeIntervalMicroSeconds32 aToneOffLength, TTimeIntervalMicroSeconds32 aPauseLength);

Description

Changes the duration of DTMF tones, the gaps between DTMF tones and the pauses.

Parameters

`TTimeIntervalMicroSeconds32 aToneLength`	The duration of the DTMF tone in microseconds.
`TTimeIntervalMicroSeconds32 aToneOffLength`	The gap between DTFM tones in microseconds.
`TTimeIntervalMicroSeconds32 aPauseLength`	Pauses in microseconds

virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds &aTrailingSilence);

Description

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.

Parameters

`TInt 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.
`const TTimeIntervalMicroSeconds &aTrailingSilence`	The time interval of the training silence. The behaviour is undefined for values other than zero and positive.

virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds &aRampDuration);

Description

Defines the period over which the volume level is to rise smoothly from nothing to the normal volume level.

Parameters

const TTimeIntervalMicroSeconds &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.

virtual TInt FixedSequenceCount();

Description

Returns the number of available pre-defined tone sequences.

Return value

TInt

The number of tone sequences. This value is implementation dependent but is always greater than or equal to zero.

virtual const TDesC& FixedSequenceName(TInt aSequenceNumber);

Description

Returns the name assigned to a specific pre-defined tone sequence.

Parameters


                                 						TInt 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 CMdaAudioToneUtility::FixedSequenceCount() - 1. The function raises a panic if sequence number is not within this range.

Return value

const TDesC16 &

The name assigned to the tone sequence.

Description

Configures the audio tone player utility to play a single tone.

This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete(TInt) 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.

Parameters

`TInt aFrequency`	The frequency (pitch) of the tone in Hz.
`const TTimeIntervalMicroSeconds &aDuration`	The duration of the tone in microseconds.

virtual void PrepareToPlayDTMFString(const TDesC &aDTMF);

Description

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(TInt) 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.

Parameters

const TDesC16 &aDTMF

A descriptor containing the DTMF string.

virtual void PrepareToPlayDesSequence(const TDesC8 &aSequence);

Description

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(TInt) 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.

Parameters

const TDesC8 &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.

virtual void PrepareToPlayFileSequence(const TDesC &aFileName);

Description

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(TInt) 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.

Parameters

const TDesC16 &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.

virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber);

Description

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(TInt) 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.

Parameters


                                 						TInt 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 CMdaAudioToneUtility::FixedSequenceCount() - 1. If the sequence number is not within this range, a panic will be raised when CMdaAudioToneUtility::Play() is called later.

Description

Cancels the configuration operation.

The observer callback function MMdaAudioToneObserver::MatoPrepareComplete(TInt) is not called.

virtual void Play();

Description

Plays the tone.

The tone played depends on the current configuration.This function is asynchronous. On completion, the observer callback function MMdaAudioToneObserver::MatoPlayComplete(TInt) is called, indicating the success or failure of the play operation.The play operation can be cancelled by calling CMdaAudioToneUtility::CancelPlay().

virtual void CancelPlay();

Description

Cancels the tone playing operation.

The observer callback function MMdaAudioToneObserver::MatoPlayComplete(TInt) is not called.

IMPORT_C void SetBalanceL(TInt aBalance=KMMFBalanceCenter);

Description

Sets the stereo balance for playback.

Parameters


                                 						TInt aBalance

The balance. Should be between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

IMPORT_C TInt GetBalanceL();

Description

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.

Return value

TInt

The balance. Should be between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

IMPORT_C void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds &aDuration);

Description

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(TInt) 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.

Parameters

`TInt aFrequencyOne`	The first frequency (pitch) of the tone.
`TInt aFrequencyTwo`	The second frequency (pitch) of the tone.
`const TTimeIntervalMicroSeconds &aDuration`	The duration of the tone in microseconds.

IMPORT_C void PrepareToPlayFileSequence(RFile &aFile);

Description

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(TInt) 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.

Parameters


                                 						RFile &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.

IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

Description

Retrieves a custom interface to the underlying device.

Parameters


                                 						TUid aInterfaceId

The interface UID, defined with the custom interface.

Return value

TAny *

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.

protected: CMMFMdaAudioToneUtility * iProperties;

Description

This member is internal and not intended for use.

Class CMdaAudioToneUtility

Description

Derivation

Members

Construction and destruction

NewL(MMdaAudioToneObserver &,CMdaServer *)

Description

Parameters

Return value

NewL(MMdaAudioToneObserver &,CMdaServer *,TInt,TMdaPriorityPreference)

Description

Parameters

Return value

Member functions

State()

Description

Return value

MaxVolume()

Description

Return value

Volume()

Description

Return value

SetVolume(TInt)

Description

Parameters

SetPriority(TInt,TMdaPriorityPreference)

Description

Parameters

SetDTMFLengths(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32)

Description

Parameters

SetRepeats(TInt,const TTimeIntervalMicroSeconds &)

Description

Parameters

SetVolumeRamp(const TTimeIntervalMicroSeconds &)

Description

Parameters

FixedSequenceCount()

Description

Return value

FixedSequenceName(TInt)

Description

Parameters

Return value

See also:

PrepareToPlayTone(TInt,const TTimeIntervalMicroSeconds &)

Description

Parameters

PrepareToPlayDTMFString(const TDesC &)

Description

Parameters

PrepareToPlayDesSequence(const TDesC8 &)

Description

Parameters

PrepareToPlayFileSequence(const TDesC &)

Description

Parameters

PrepareToPlayFixedSequence(TInt)

Description

Parameters

See also:

CancelPrepare()

Description

Play()

Description

CancelPlay()

Description

SetBalanceL(TInt)

Description

Parameters

GetBalanceL()

Description

Return value

PrepareToPlayDualTone(TInt,TInt,const TTimeIntervalMicroSeconds &)

Description

Parameters

PrepareToPlayFileSequence(RFile &)

Description

Parameters

Class `CMdaAudioToneUtility`

`NewL(MMdaAudioToneObserver &,CMdaServer *)`

`NewL(MMdaAudioToneObserver &,CMdaServer *,TInt,TMdaPriorityPreference)`

`State()`

`MaxVolume()`

`Volume()`

`SetVolume(TInt)`

`SetPriority(TInt,TMdaPriorityPreference)`

`SetDTMFLengths(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32)`

`SetRepeats(TInt,const TTimeIntervalMicroSeconds &)`

`SetVolumeRamp(const TTimeIntervalMicroSeconds &)`

`FixedSequenceCount()`

`FixedSequenceName(TInt)`

`PrepareToPlayTone(TInt,const TTimeIntervalMicroSeconds &)`

`PrepareToPlayDTMFString(const TDesC &)`

`PrepareToPlayDesSequence(const TDesC8 &)`

`PrepareToPlayFileSequence(const TDesC &)`

`PrepareToPlayFixedSequence(TInt)`

`CancelPrepare()`

`Play()`

`CancelPlay()`

`SetBalanceL(TInt)`

`GetBalanceL()`

`PrepareToPlayDualTone(TInt,TInt,const TTimeIntervalMicroSeconds &)`

`PrepareToPlayFileSequence(RFile &)`

`CustomInterface(TUid)`

`iProperties`