Collapse all Symbian^3 Product Developer Library

CMdaAudioToneUtility Class Reference

class CMdaAudioToneUtility : public CBase

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.

Since: 5.0

Inherits from

CMdaAudioToneUtility
- CBase

Public Member Functions
	~CMdaAudioToneUtility()
void	CancelPlay()
void	CancelPrepare()
IMPORT_C TAny *	CustomInterface(TUid)
TInt	FixedSequenceCount()
const TDesC &	FixedSequenceName(TInt)
IMPORT_C TInt	GetBalanceL()
TInt	MaxVolume()
IMPORT_C CMdaAudioToneUtility *	NewL(MMdaAudioToneObserver &, CMdaServer *)
IMPORT_C CMdaAudioToneUtility *	NewL(MMdaAudioToneObserver &, CMdaServer *, TInt, TInt)
IMPORT_C TInt	Pause()
void	Play()
void	PrepareToPlayDTMFString(const TDesC &)
void	PrepareToPlayDesSequence(const TDesC8 &)
IMPORT_C void	PrepareToPlayDualTone(TInt, TInt, const TTimeIntervalMicroSeconds &)
void	PrepareToPlayFileSequence(const TDesC &)
IMPORT_C void	PrepareToPlayFileSequence(RFile &)
void	PrepareToPlayFixedSequence(TInt)
void	PrepareToPlayTone(TInt, const TTimeIntervalMicroSeconds &)
IMPORT_C void	RegisterPlayStartCallback(MMdaAudioTonePlayStartObserver &)
IMPORT_C TInt	Resume()
IMPORT_C void	SetBalanceL(TInt)
void	SetDTMFLengths(TTimeIntervalMicroSeconds32, TTimeIntervalMicroSeconds32, TTimeIntervalMicroSeconds32)
void	SetPriority(TInt, TInt)
void	SetRepeats(TInt, const TTimeIntervalMicroSeconds &)
void	SetVolume(TInt)
void	SetVolumeRamp(const TTimeIntervalMicroSeconds &)
TMdaAudioToneUtilityState	State()
TInt	Volume()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Protected Attributes
CMMFMdaAudioToneUtility *	iProperties

Constructor & Destructor Documentation

~CMdaAudioToneUtility()

~CMdaAudioToneUtility

(

)

Destructor. Frees any resources held by the tone player

Since: 5.0

Member Functions Documentation

CancelPlay()

void

CancelPlay

(

)

[virtual]

Cancels the tone playing operation.

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

Since: 5.0

CancelPrepare()

void

CancelPrepare

(

)

[virtual]

Cancels the configuration operation.

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

Since: 5.0

CustomInterface(TUid)

IMPORT_C TAny *

CustomInterface

(

TUid

aInterfaceId

)

Retrieves a custom interface to the underlying device.

Parameters

TUid aInterfaceId

The interface UID, defined with the custom interface.

FixedSequenceCount()

TInt

FixedSequenceCount

(

)

[virtual]

Returns the number of available pre-defined tone sequences.

Since: 5.0

FixedSequenceName(TInt)

const TDesC &

FixedSequenceName

(

TInt

aSequenceNumber

)

[virtual]

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

CMMFDevSound::FixedSequenceName(TInt aSequenceNumber) FixedSequenceCount()

Since: 5.0

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

GetBalanceL()

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.

Since: 7.0s

MaxVolume()

TInt

MaxVolume

(

)

[virtual]

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

Since: 5.0

NewL(MMdaAudioToneObserver &, CMdaServer *)

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.

Since: 5.0

Parameters

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

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

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.

Since: 5.0

Note: The Priority Value and Priority Preference are used primarily when deciding what to do when several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may vary between different phones. Portable applications are advised not to assume any specific behaviour.

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	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.
TInt aPref = EMdaPriorityPreferenceTimeAndQuality	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.

Pause()

IMPORT_C TInt

Pause

(

)

Play()

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

Since: 5.0

PrepareToPlayDTMFString(const TDesC &)

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.

Since: 5.0

Parameters

const TDesC & aDTMF

A descriptor containing the DTMF string.

PrepareToPlayDesSequence(const TDesC8 &)

void

PrepareToPlayDesSequence

(

const TDesC8 &

aSequence

)

[virtual]

Configures the audio tone player utility to play a tone sequence contained in a descriptor.

Since: 5.0

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.

PrepareToPlayDualTone(TInt, TInt, const TTimeIntervalMicroSeconds &)

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.

Since: 7.0sy

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.

PrepareToPlayFileSequence(const TDesC &)

void

PrepareToPlayFileSequence

(

const TDesC &

aFileName

)

[virtual]

Configures the audio tone player utility to play a tone sequence contained in a file.

Since: 5.0

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.

PrepareToPlayFileSequence(RFile &)

IMPORT_C void

PrepareToPlayFileSequence

(

RFile &

aFile

)

Configures the audio tone player utility to play a tone sequence contained in a file.

Since: 5.0

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.

PrepareToPlayFixedSequence(TInt)

void

PrepareToPlayFixedSequence

(

TInt

aSequenceNumber

)

[virtual]

Configures the audio tone player utility to play the specified pre-defined tone sequence.

FixedSequenceCount() CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)

Since: 5.0

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

PrepareToPlayTone(TInt, const TTimeIntervalMicroSeconds &)

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.

Since: 5.0

Parameters

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

RegisterPlayStartCallback(MMdaAudioTonePlayStartObserver &)

IMPORT_C void

RegisterPlayStartCallback

(

MMdaAudioTonePlayStartObserver &

aObserver

)

Parameters

MMdaAudioTonePlayStartObserver & aObserver

Resume()

IMPORT_C TInt

Resume

(

)

SetBalanceL(TInt)

IMPORT_C void

SetBalanceL

(

TInt

aBalance = KMMFBalanceCenter

)

Sets the stereo balance for playback.

Since: 7.0s

Parameters

TInt aBalance = KMMFBalanceCenter

The balance. Should be between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

SetDTMFLengths(TTimeIntervalMicroSeconds32, TTimeIntervalMicroSeconds32, TTimeIntervalMicroSeconds32)

void	SetDTMFLengths	(	TTimeIntervalMicroSeconds32	aToneLength,
			TTimeIntervalMicroSeconds32	aToneOffLength,
			TTimeIntervalMicroSeconds32	aPauseLength
		)	[virtual]

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

SetPriority(TInt, TInt)

void	SetPriority	(	TInt	aPriority,
			TInt	aPref
		)	[virtual]

Changes the clients priority.

CMdaAudioToneUtility::NewL()

Since: 5.0

Parameters

TInt aPriority	The Priority Value.
TInt aPref	The Priority Preference.

SetRepeats(TInt, const TTimeIntervalMicroSeconds &)

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.

Since: 5.0

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.

SetVolume(TInt)

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.

Since: 5.0

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.

SetVolumeRamp(const TTimeIntervalMicroSeconds &)

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.

Since: 5.0

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.

State()

TMdaAudioToneUtilityState

State

(

)

[virtual]

Returns the current state of the audio tone utility.

Since: 5.0

Volume()

TInt

Volume

(

)

[virtual]

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

Since: 5.0

Member Data Documentation

CMMFMdaAudioToneUtility * iProperties

CMMFMdaAudioToneUtility *

iProperties

[protected]

This member is internal and not intended for use.