
DEVELOPER LIBRARY

» Developer Library » API Reference » C++ API reference » Sound Device » CMMFDevSound

Location: SoundDevice.h
Link against: MMFDevSound.lib

Class `CMMFDevSound`

class CMMFDevSound : public CBase, public MMMFHwDeviceObserver;

Support

Supported from 7.0s

Description

An interface to the raw audio functions of Symbian OS device hardware.

The audio functions include the following functionality:

Initialisation and configuration of hardware devices, for example, setting microphone gain, setting setero balance and so on.
The playing and recording of raw audio data.
The playing and dynamic control of tones with user specified frequencies.
The playing of DTMF strings.

Derivation

`CBase`	Base class for all classes to be instantiated on the heap
`CMMFDevSound`	An interface to the raw audio functions of Symbian OS device hardware
`MMMFHwDeviceObserver`

Defined in CMMFDevSound:
CMMFDevSound(), Capabilities(), Complete(), Config(), ConstructL(), ConvertData(), ConvertInitL(), CustomCommand(), DevSoundInfo(), Device(), DoPlayL(), EmptyThisHwBuffer(), FillFreeToneBuffer(), FillThisHwBuffer(), Gain(), GetPlayBalanceL(), GetRecordBalanceL(), InitAudioDeviceNode(), InitializeFormat(), InitializeL(), InitializeL(), InitializeL(), InitializeL(), LoadL(), MaxGain(), MaxVolume(), MoreData(), MoreRecordData(), MsgFromHwDevice(), NewL(), NumberOfChannels(), Pause(), PlayDTMFStringL(), PlayData(), PlayFixedSequenceL(), PlayInitL(), PlayToneL(), PlayToneSequenceL(), PlayingStopped(), RecordComplete(), RecordData(), RecordInitL(), RecordingStopped(), RequestPolicy(), ResumePlayDTMFStringL(), ResumePlayDataL(), ResumePlayToneL(), ResumePlayToneSequenceL(), ResumeRecordDataL(), SamplesPlayed(), SamplesRecorded(), SamplingFrequency(), SendEventToClient(), SetActiveToneBuffer(), SetConfigL(), SetDTMFLengths(), SetDevSoundId(), SetGain(), SetPlayBalanceL(), SetPrioritySettings(), SetRecordBalanceL(), SetToneRepeats(), SetVolume(), SetVolumeRamp(), Stop(), Stopped(), Unload(), UpdateBytesPlayed(), UpdatePolicyState(), Volume(), iActiveToneBuffer, iAudioPlayer, iAudioPolicyPrioritySettings, iAudioPolicyProxy, iAudioPolicyRequest, iAudioRecorder, iBuffer, iCMMFHwDevice, iClientSessionId, iCurrentGenerator, iDTMFGen, iDevInfo, iDevSoundEventHandler, iDevSoundInfo, iDevSoundObserver, iDevice, iDeviceCapabilities, iDeviceConfig, iDeviceIsOpen, iGain, iHwDeviceBuffer, iMode, iPlayFormat, iPlayFormatsSupported, iPlayedBytesCount, iPlayerErrors, iPrioritySettings, iRampDuration, iReceivingEvents, iRecordFormat, iRecordFormatsSupported, iRecordedBytesCount, iRecorderErrors, iRepeatCount, iRepeatTrailingSilence, iState, iToneBuffer1, iToneBuffer2, iToneGen, iVolume, ~CMMFDevSound()

Inherited from CBase:
operator new()

Construction and destruction

`NewL()`

static CMMFDevSound* NewL();

Description

Constructs and initialises a new instance of DevSound.

The function leaves if the DevSound object cannot be created.

Return value


CMMFDevSound
*

Pointer to the new DevSound object.

`~CMMFDevSound()`

~CMMFDevSound();

Description

Default destructor.

Frees all resources owned by the object prior to its destruction.

Member functions

`InitializeL()`

void InitializeL(MDevSoundObserver& aDevSoundObserver);

Description

Initialises the CMMFDevSound object and sets raw audio encoding to PCM16 and sampling to 8 KHz.

On completion of initialisation, the observer is notified via the call back MDevSoundObserver::InitializeComplete().

Parameters

MDevSoundObserver& aDevSoundObserver

An observer class used to notify the client of various events. It also provides a mechanism for the client to pass and receive data to and from DevSound. The caller must create an observer class that implements this interface.

`InitializeL()`

void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode);

Description

Initialises the CMMFDevSound object specifying the hardware device and its mode, for example play, record or convert.

On completion of initialisation, the observer is notified via the call back MDevSoundObserver::InitializeComplete().

Parameters

`MDevSoundObserver& aDevSoundObserver`	An observer class used to notify the client of various events. It also provides a mechanism for the client to pass and receive data to and from DevSound. The caller must create an observer class that implements this interface.
`TUid aHWDev`	Hardware device ID.
`TMMFState aMode`	Audio mode, for example, idle, tone playing and so on.

`InitializeL()`

void InitializeL(MDevSoundObserver& aDevSoundObserver, CArrayPtr<TUid> aHWDevArray, TMMFState aMode);

Description

Initialises the CMMFDevSound object specifying a chain of hardware devices and a single mode to set them to.

The hardware devices are chained together with data flow starting with first array element.

On completion of initialisation, the observer is notified via the call back MDevSoundObserver::InitializeComplete().

Parameters

`MDevSoundObserver& aDevSoundObserver`	An observer class used to notify the client of various events. It also provides a mechanism for the client to pass and receive data to and from DevSound. The caller must create an observer class that implements this interface.
`CArrayPtr<TUid> aHWDevArray`	An array of hardware device IDs.
`TMMFState aMode`	Audio mode, for example, idle, tone playing and so on.

`InitializeL()`

void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode);

Description

Initialises the CMMFDevSound object specifying a hardware device (referenced by its associated TFourCC code) and its mode, for example play, record or convert.

On completion of initialisation, the observer is notified via the call back MDevSoundObserver::InitializeComplete().

Parameters

`MDevSoundObserver& aDevSoundObserver`	An observer class used to notify the client of various events. It also provides a mechanism for the client to pass and receive data to and from DevSound. The caller must create an observer class that implements this interface.
`TFourCC aDesiredFourCC`	The `TFourCC` code for the desired hardware.
`TMMFState aMode`	Audio mode, for example, idle, tone playing and so on.

`Capabilities()`

TMMFCapabilities Capabilities();

Description

Returns all possible values that the device configuration can be set to.

Return value


TMMFCapabilities

Device's capability attributes, specifically, encoding, sample rates, mono/stereo indication and buffer size.

`Config()`

TMMFCapabilities Config() const;

Description

Returns the current settings used by the device.

Return value


TMMFCapabilities

Device's configuration attributes, specifically, encoding, sample rates, mono/stereo indication and buffer size.

`SetConfigL()`

void SetConfigL(const TMMFCapabilities& aCaps);

Description

Sets new device attribute values.

Use this to set sampling rate, encoding and the mono/stereo indicator.

Parameters

const TMMFCapabilities& aCaps

New device attribute values.

`MaxVolume()`

TInt MaxVolume();

Description

Returns the maximum volume setting supported by the current device.

Return value


TInt

Maximum volume setting.

`Volume()`

TInt Volume();

Description

Returns the volume setting of the current device.

Return value


TInt

Current volume setting.

`SetVolume()`

void SetVolume(TInt aVolume);

Description

Sets the volume of the current device.

Valid volume settings are in the range of 0 to MaxVolume().

Parameters

TInt aVolume

Volume setting.

`MaxGain()`

TInt MaxGain();

Description

Maximum microphone gain supported by the current device.

Return value


TInt

Maximum microphone gain.

`Gain()`

TInt Gain();

Description

Returns the microphone gain of the current device.

Return value


TInt

Current microphone gain.

`SetGain()`

void SetGain(TInt aGain);

Description

Sets the microphone gain of the current device.

Valid gain settings are in the range of 0 to MaxGain().

Parameters

TInt aGain

Microphone gain.

`GetPlayBalanceL()`

void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);

Description

Gets the balance settings for the current playing device.

Parameters

`TInt& aLeftPercentage`	On return, contains the left channel's volume balance setting for playing audio.
`TInt& aRightPercentage`	On return, contains the right channel's volume balance setting for playing audio.

`SetPlayBalanceL()`

void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage);

Description

Modifies the balance settings for the current playing device.

Both channels require percentage values, therefore, valid range is between 0 and 100 only.

Parameters

`TInt aLeftPercentage`	The left channel's volume balance setting for playing audio.
`TInt aRightPercentage`	The right channel's volume balance setting for playing audio.

`GetRecordBalanceL()`

void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);

Description

Gets the balance settings for the current recording device.

Parameters

`TInt& aLeftPercentage`	On return, contains the left channel's balance setting for recording audio.
`TInt& aRightPercentage`	On return, contains the right channel's balance setting for recording audio.

`SetRecordBalanceL()`

void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage);

Description

Modifies the balance settings for the current recording device.

Both channels require percentage values, therefore, valid range is between 0 and 100 only.

Parameters

`TInt aLeftPercentage`	The left channel balance setting for recording audio.
`TInt aRightPercentage`	The right channel balance setting for recording audio.

`PlayInitL()`

void PlayInitL();

Description

Initialises the audio device and starts the play process.

This method queries the audio policy server before initialising the audio device. If there is an error during policy initialisation, MDevSoundObserver::PlayError() is called with an error code of KErrAccessDenied. If no initialisation error occurs, MDevSoundObserver::BufferToBeFilled() is called with a buffer reference. The client then needs to fill the buffer with the data to play and then call PlayData().

Note: The amount of data that can be played is specified in CMMFBuffer::RequestSize(). Any additional data placed in the buffer is ignored.

`RecordInitL()`

void RecordInitL();

Description

Initialises the audio device and starts the record process.

This method queries the audio policy server before initialising the audio device. If there is an error during policy initialisation, MDevSoundObserver::RecordError() is called with an error code of KErrAccessDenied. If no initialisation error occurs, MDevSoundObserver::BufferToBeEmptied() is called with a buffer reference. This buffer contains recorded or encoded data. After processing the recorded or encoded data the client should call RecordData() to continue the recording process.

`PlayData()`

void PlayData();

Description

Plays the audio data provided by the client when processing the BufferToBeFilled() callback.

When playing of the audio sample is complete, successfully or otherwise MDevSoundObserver::PlayError() is called with the appropriate system wide error code.

`RecordData()`

void RecordData();

Description

Continues the recording process.

Once the recording buffer is filled with audio data, MDevSoundObserver::BufferToBeEmptied() is called so that the client has the opportunity to process the recorded data (usually copying the data to another buffer or writing it to a file.)

`Stop()`

void Stop();

Description

Stops an ongoing operation, for example, play, record, tone play, convert and so on.

`Pause()`

void Pause();

Description

Temporarily stops an ongoing operation, for example, play, record, tone play, convert and so on.

`SamplesRecorded()`

TInt SamplesRecorded();

Description

Returns the number of bytes recorded so far.

Return value


TInt

Recorded bytes.

`SamplesPlayed()`

TInt SamplesPlayed();

Description

Returns the number of bytes played so far.

Return value


TInt

Played bytes.

`PlayToneL()`

void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);

Description

Initialises the audio device and starts the play tone process.

The tone is played at a specified frequency for a specified amount of time.

Parameters

`TInt aFrequency`	The frequency of the tone to play.
`const TTimeIntervalMicroSeconds& aDuration`	The duration of the tone.

`PlayDTMFStringL()`

void PlayDTMFStringL(const TDesC& aDTMFString);

Description

Initialises the audio device and starts playing a DTMF string.

Parameters

const TDesC& aDTMFString

DTMF sequence to play.

`PlayToneSequenceL()`

void PlayToneSequenceL(const TDesC8& aData);

Description

Initialises the audio device and starts playing a sequence of tones.

Note: This function is not currently supported.

Parameters

const TDesC8& aData

Tone sequence to play.

`PlayFixedSequenceL()`

void PlayFixedSequenceL(TInt aSequenceNumber);

Description

Initialises the audio device and starts playing a fixed sequence of tones.

Note: This function is not currently supported.

Parameters

TInt aSequenceNumber

Tone sequence number pointing to an index in a fixed sequence table.

`SetToneRepeats()`

void SetToneRepeats(TInt aRepeatCount, const TTimeIntervalMicroSeconds& aRepeatTrailingSilence);

Description

Defines the number of times the tone should be repeated during playback.

A period of silence can follow each playing of tone.

This function is only available while a tone is playing.

Parameters

`TInt aRepeatCount`	The number of times to repeat the tone. Use 0 for no repeat, or `KMdaRepeatForever` to repeat until `Stop()` is called.
`const TTimeIntervalMicroSeconds& aRepeatTrailingSilence`	Duration of a trailing silence after a tone has been played.

`SetDTMFLengths()`

void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength, TTimeIntervalMicroSeconds32& aToneOffLength, TTimeIntervalMicroSeconds32& aPauseLength);

Description

Defines the duration of tone on, tone off and tone pause to be used during the DTMF tone playback operation.

Parameters

`TTimeIntervalMicroSeconds32& aToneOnLength`	The period over which the tone will be played. If this is set to zero, then the tone is not played.
`TTimeIntervalMicroSeconds32& aToneOffLength`	The period over which the no tone will be played.
`TTimeIntervalMicroSeconds32& aPauseLength`	The period over which the tone playing will be paused.

`SetVolumeRamp()`

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.

This function is only available while a tone is playing.

Parameters

const TTimeIntervalMicroSeconds& aRampDuration

The period over which the volume is to rise. Zero causes the tone sample to be played at the normal level for the duration of the playback.

`SetPrioritySettings()`

void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);

Description

Defines the priority settings to use for this instance.

Parameters

const TMMFPrioritySettings& aPrioritySettings

Priority settings.

`ConvertInitL()`

void ConvertInitL();

Description

Initialises the audio device and starts the convert process.

This method queries the audio policy server before initialising audio device. If there is an error during policy initialisation, MDevSoundObserver::PlayError() is called with an error code of KErrAccessDenied. If no initialisation error occurs, MDevSoundObserver::BufferToBeFilled() is called with a buffer reference used to store the source audio data. The client then needs to fill the buffer with the data to convert and then call ConvertData().

Note: The amount of data that can be converted is specified in CMMFBuffer::RequestSize(). Any additional data placed in the buffer is ignored.

Note: This function is not currently supported.

`ConvertData()`

void ConvertData();

Description

Completes the conversion process.

Once the conversion buffer is filled with converted audio data MDevSoundObserver::BufferToBeEmptied() is called so that the client has the opportunity to process the converted data (usually copying the data to another buffer or writing it to a file.)

Note: This function is not currently supported.

`CustomCommand()`

TInt CustomCommand(TDesC8& aCommand);

Description

Used to issue device specific commands that cannot be executed through the DevSound API.

The command is packed in the form of a descriptor. After executing the custom command, the device may or may not send a command execution message to the observer via MDevSoundObserver::DeviceMessage().

Note: This function is not currently supported.

Parameters

TDesC8& aCommand

Device specific command.

Return value


TInt

Returns KErrNotSupported.