Class CMdaAudioToneUtility

CMdaAudioToneUtility

Support

Supported from 5.0

Description

Generates tones on an audio capable EPOC device.

The class offers an interface for generating tones on all audio capable EPOC devices.

While this class is abstract, the static function constructs, initialises and returns a pointer to an instance of a concrete class derived from this abstract class. This concrete class is part of the Media Server implementation and is private.

Derivation

CBase Base class for all classes to be instantiated on the heap CMdaAudioToneUtility Generates tones on an audio capable EPOC device

Defined in CMdaAudioToneUtility:
CancelPlay(), CancelPrepare(), FixedSequenceCount(), FixedSequenceName(), MaxVolume(), NewL(), Play(), PrepareToPlayDTMFString(), PrepareToPlayDesSequence(), PrepareToPlayFileSequence(), PrepareToPlayFixedSequence(), PrepareToPlayTone(), SetDTMFLengths(), SetPriority(), SetRepeats(), SetVolume(), SetVolumeRamp(), State(), Volume()

Inherited from CBase:
operator new()

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

Description

Constructs and initialises a new instance of the audio tone utility.

The function leaves if the audio tone utility object cannot be created.

Parameters

MMdaAudioToneObserver& aObserver The audio tone player observer interface. CMdaServer* aServer=NULL A pointer to a server object. The default is NULL which means that one is automatically constructed and owned by this conversion utility object. If not NULL, the client must construct, and be responsible for, the server object. This option may be more efficient if a number of conversion utility objects are to be created.

Return value

CMdaAudioToneUtility* Pointer to the new audio tone player utility object.

virtual void PrepareToPlayTone(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration) = 0;

Description

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.

Parameters

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

virtual void PrepareToPlayDTMFString(const TDesC& aDTMF) = 0;

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() 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 TDesC& aDTMF A descriptor containing the DTMF string

virtual void PrepareToPlayFileSequence(const TDesC& aFilename) = 0;

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() 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 TDesC& 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 PrepareToPlayDesSequence(const TDesC8& aSequence) = 0;

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() 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 PrepareToPlayFixedSequence(TInt aSequenceNumber) = 0;

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() 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. Index values are relative to zero.

virtual void CancelPrepare() = 0;

Description

Cancels the configuration operation.

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

virtual void Play() = 0;

Description

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 callingCMdaAudioToneUtility::CancelPlay().

virtual void CancelPlay() = 0;

Description

Cancels the tone playing operation.

The observer callback functionMMdaAudioToneObserver::MatoPlayComplete() is not called.

virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32 iToneOnLength,TTimeIntervalMicroSeconds32 iToneOffLength,TTimeIntervalMicroSeconds32 iPauseLength) = 0;

Description

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

Parameters

TTimeIntervalMicroSeconds32 iToneOnLength The duration of the DTMF tone in microseconds. TTimeIntervalMicroSeconds32 iToneOffLength The gap between DTFM tones in microseconds. TTimeIntervalMicroSeconds32 iPauseLength Pauses in microseconds

virtual void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

Description

Changes the client’s 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 SetVolume(TInt aVolume) = 0;

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.

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

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. If this is set to zero, then the tone sequence is not repeated. If this is set to a negative value other than KMdaRepeatForeverthen the function raises a CMdaAudioToneUtility 6 panic. const TTimeIntervalMicroSeconds& aTrailingSilence The time interval of the training silence. The value must be zero or positive, otherwise the function raises a CMdaAudioToneUtility 5 panic.

virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration) = 0;

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() = 0;

Description

Returns the number of available pre-defined tone sequences.

Return value

TInt The number of tone sequences

virtual const TDesC& FixedSequenceName(TInt aSequenceNumber) = 0;

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.

Return value

TDesC& The name assigned to the tone sequence.

virtual TMdaAudioToneUtilityState State() = 0;

Description

Returns the current state of the audio tone utility.

Return value

TMdaAudioToneUtilityState The state of the audio tone utility.

virtual TInt Volume() = 0;

Description

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

Return value

TInt The volume of the audio device.

virtual TInt MaxVolume() = 0;

Description

Returns an integer representing the maximum volume. This is the maximum value which can be passed toCMdaAudioToneUtility::SetVolume().

Return value

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