Class CMMFDevSound

class CMMFDevSound : public CBase;

Description

This is the interface from Symbian OS to the raw audio functions on the device hardware.

DevSound is currently loaded as a DLL, and implements the VCR-type functions to be expected for such an interface.

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

Members

Defined in CMMFDevSound:

• CancelRegisterAsClient(TUid)Cancels the Registered Notification.
• Capabilities()Returns the supported Audio settings ie. encoding, sample rates, mono/stereo ope...
• Config()constReturns the current device configuration.
• CustomInterface(TUid)Retrieves a custom interface to the device.
• FixedSequenceCount()Returns the number of available pre-defined tone sequences.
• FixedSequenceName(TInt)Returns the name assigned to a specific pre-defined tone sequence.
• Gain()Returns an integer representing the current gain.
• GetPlayBalanceL(TInt &,TInt &)Returns the speaker balance set for playing.
• GetRecordBalanceL(TInt &,TInt &)Returns the microphone gain balance set for recording.
• GetResourceNotificationData(TUid,TDes8 &)Returns the Notification data which the client needs to resume playing.
• GetSupportedInputDataTypesL(RArray< TFourCC > &,const TMMFPrioritySettings &)constReturns a list of the supported input datatypes that can be sent to DevSound for...
• GetSupportedOutputDataTypesL(RArray< TFourCC > &,const TMMFPrioritySettings &)constReturns a list of the supported output dataypes that can be received from DevSou...
• InitializeL(MDevSoundObserver &,TFourCC,TMMFState)Initializes DevSound object for the mode aMode for processing audio data with ha...
• InitializeL(MDevSoundObserver &,TMMFState)Initializes CMMFDevSound object to play and record PCM16 raw audio data with sam...
• InitializeL(MDevSoundObserver &,TUid,TMMFState)Initializes DevSound object for the mode aMode for processing audio data with ha...
• MaxGain()Returns an integer representing the maximum gain the device supports.
• MaxVolume()Returns an integer representing the maximum volume device supports.
• NewL()Constructs, and returns a pointer to, a new CMMFDevSound object.
• Pause()Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert).
• PlayDTMFStringL(const TDesC &)Initializes the audio device and starts playing the DTMF string aDTMFString.
• PlayData()Plays data in the buffer at the current volume.
• PlayDualToneL(TInt,TInt,const TTimeIntervalMicroSeconds &)Initializes audio device and starts playing a dual tone.
• PlayFixedSequenceL(TInt)Initializes the audio device and starts playing the specified pre-defined tone s...
• PlayInitL()Initializes the audio device and starts the play process.
• PlayToneL(TInt,const TTimeIntervalMicroSeconds &)Initializes the audio device and starts playing a tone. The tone is played with ...
• PlayToneSequenceL(const TDesC8 &)Initializes the audio device and starts playing a tone sequence.
• RecordData()Contine the process of recording.
• RecordInitL()Initializes audio device and starts the recording process.
• RegisterAsClient(TUid,const TDesC8 &)Registers the client for notification of resource avalibility.
• SamplesPlayed()Returns the number of samples played so far.
• SamplesRecorded()Returns the number samples recorded so far.
• SetConfigL(const TMMFCapabilities &)Configure CMMFDevSound object with the settings in aConfig.
• SetDTMFLengths(TTimeIntervalMicroSeconds32 &,TTimeIntervalMicroSeconds32 &,TTimeIntervalMicroSeconds32 &)Defines the duration of tone on, tone off and tone pause to be used during the D...
• SetGain(TInt)Changes the current recording gain to a specified value.
• SetPlayBalanceL(TInt,TInt)Sets the speaker balance for playing.
• SetPrioritySettings(const TMMFPrioritySettings &)Defines the priority settings that should be used for this instance.
• SetRecordBalanceL(TInt,TInt)Sets the microphone gain balance for recording.
• SetToneRepeats(TInt,const TTimeIntervalMicroSeconds &)Defines the number of times the audio is to be repeated during the tone playback...
• SetVolume(TInt)Changes the current playback volume to a specified value.
• SetVolumeRamp(const TTimeIntervalMicroSeconds &)Defines the period over which the volume level is to rise smoothly from nothing ...
• Stop()Stops the ongoing operation (Play, Record, TonePlay, Convert).
• Volume()Returns an integer representing the current volume.
• WillResumePlay()Wait for the clients to resume play back even after the default timeout expires....
• iBodyDevSound body
• ~CMMFDevSound()Destructor.

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

IMPORT_C static CMMFDevSound* NewL();

Description

Constructs, and returns a pointer to, a new CMMFDevSound object.

Leaves on failure.

Return value

IMPORT_C ~CMMFDevSound();

Description

Destructor.

Deletes all objects and releases all resource owned by this instance.

IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TMMFState aMode);

Description

Initializes CMMFDevSound object to play and record PCM16 raw audio data with sampling rate of 8 KHz.

On completion of Initialization, calls InitializeComplete() on aDevSoundObserver.

Leaves on failure.

Parameters

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

Description

Initializes DevSound object for the mode aMode for processing audio data with hardware device aHWDev.

On completion of Initialization, the observer will be notified via call back InitializeComplete().

Leaves on failure.

Parameters

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

Description

Initializes DevSound object for the mode aMode for processing audio data with hardware device supporting FourCC aDesiredFourCC.

On completion of Initialization, the observer will be notified via call back InitializeComplete().

Leaves on failure.

Parameters

IMPORT_C TMMFCapabilities Capabilities();

Description

Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer size etc.

Return value

IMPORT_C TMMFCapabilities Config() const;

Description

Returns the current device configuration.

Return value

IMPORT_C void SetConfigL(const TMMFCapabilities &aCaps);

Description

Configure CMMFDevSound object with the settings in aConfig.

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

Parameters

IMPORT_C TInt MaxVolume();

Description

Returns an integer representing the maximum volume device supports.

This is the maximum value which can be passed to CMMFDevSound::SetVolume(TInt).

Return value

IMPORT_C TInt Volume();

Description

Returns an integer representing the current volume.

Return value

IMPORT_C void SetVolume(TInt aVolume);

Description

Changes the current playback volume to a specified value.

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

Parameters

IMPORT_C TInt MaxGain();

Description

Returns an integer representing the maximum gain the device supports.

This is the maximum value which can be passed to CMMFDevSound::SetGain(TInt).

Return value

IMPORT_C TInt Gain();

Description

Returns an integer representing the current gain.

Return value

IMPORT_C void SetGain(TInt aGain);

Description

Changes the current recording gain to a specified value.

The gain can be changed before or during recording and is effective immediately.

Parameters

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

Description

Returns the speaker balance set for playing.

Leaves on failure.

Parameters

IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage);

Description

Sets the speaker balance for playing.

The speaker balance can be changed before or during playback and is effective immediately.

Parameters

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

Description

Returns the microphone gain balance set for recording.

Leaves on failure.

Parameters

IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage);

Description

Sets the microphone gain balance for recording.

The microphone gain balance can be changed before or during recording and is effective immediately.

Parameters

IMPORT_C void PlayInitL();

Description

Initializes the audio device and starts the play process.

This function queries and acquires the audio policy before initializing audio device. If there was an error during policy initialization, PlayError() function will be called on the observer with error code KErrAccessDenied, otherwise BufferToBeFilled() function will be called with a buffer reference. After reading data into the buffer reference passed, the client should call CMMFDevSound::PlayData() to play data.

The amount of data that can be played is specified in CMMFBuffer::RequestSize(). Any data that is read into buffer beyond this size will be ignored.

Leaves on failure.

See also:

• MDevSoundObserver::PlayError(TInt)Handles play completion or cancel event.
• MDevSoundObserver::BufferToBeFilled(CMMFBuffer *)Handles CMMFDevSound object's data request event.

IMPORT_C void RecordInitL();

Description

Initializes audio device and starts the recording process.

This function queries and acquires the audio policy before initializing audio device. If there was an error during policy initialization, RecordError() function will be called on the observer with error code KErrAccessDenied, otherwise BufferToBeEmptied() function will be called with a buffer reference. This buffer contains recorded or encoded data. After processing data in the buffer reference passed, the client should call CMMFDevSound::RecordData() to continue recording process.

The amount of data that is available is specified in CMMFBuffer::RequestSize().

Leaves on failure.

See also:

• MDevSoundObserver::RecordError(TInt)Handles record completion or cancel event.
• MDevSoundObserver::BufferToBeEmptied(CMMFBuffer *)Handles CMMFDevSound object's data request event.

IMPORT_C void PlayData();

Description

Plays data in the buffer at the current volume.

The client should fill the buffer with audio data before calling this function. The observer gets a reference to the buffer along with the callback function BufferToBeFilled(). When playing of the audio sample is complete, successfully or otherwise, the function PlayError() on the observer is called.

The last buffer of the audio stream being played should have the last buffer flag set using CMMFBuffer::SetLastBuffer(TBool). If a subsequent attempt to play the clip is made, this flag will need resetting by the client.

See also:

• MDevSoundObserver::PlayError(TInt)Handles play completion or cancel event.

IMPORT_C void RecordData();

Description

Contine the process of recording.

Once the buffer is filled with recorded data, the Observer gets a reference to the buffer along with the callback function BufferToBeEmptied(). After processing the buffer (copying over to a different buffer or writing to file) the client should call this function to continue the recording process.

IMPORT_C void Stop();

Description

Stops the ongoing operation (Play, Record, TonePlay, Convert).

This function should be synchronous and invoke no callbacks through MDevSoundObserver.

IMPORT_C void Pause();

Description

Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert).

The behaviour of CMMFDevSound::Pause() is currently undefined when the initialisation mode is not EMMFStateRecording, consequently different DevSound implementations exhibit different behaviour for pause during play. For this reason, it is recommended that when pausing of audio during playing is required, CMMFDevSound::Stop() is used instead of the call to CMMFDevSound::Pause(). To resume audio playing after CMMFDevSound::Stop(), call CMMFDevSound::PlayInitL(). Among other things, this will internally reset the CMMFDevSound::SamplesPlayed() result and the calling code may need to remember the previous result to give the correct "samples played from start" value.

In the case of record, Pause is taken to mean halt any further recording but continue to call the MDevSoundObserver::BufferToBeEmptied(CMMFBuffer *) passing already recorded buffers. The last buffer flag should be set when all recorded buffers have been flushed.

See also:

• CMMFDevSound::Stop()Stops the ongoing operation (Play, Record, TonePlay, Convert).
• CMMFDevSound::PlayInitL()Initializes the audio device and starts the play process.
• CMMFDevSound::SamplesPlayed()Returns the number of samples played so far.

IMPORT_C TInt SamplesRecorded();

Description

Returns the number samples recorded so far.

Return value

IMPORT_C TInt SamplesPlayed();

Description

Returns the number of samples played so far.

Return value

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

Description

Initializes the audio device and starts playing a tone. The tone is played with the frequency and duration specified.

Leaves on failure.

Parameters

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

Description

Initializes audio device and starts playing a dual tone.

The generated tone consists of two sine waves of different frequencies summed together.

Dual Tone is played with the specified frequencies and for the specified duration.

Parameters

IMPORT_C void PlayDTMFStringL(const TDesC &aDTMFString);

Description

Initializes the audio device and starts playing the DTMF string aDTMFString.

Leaves on failure.

Parameters

IMPORT_C void PlayToneSequenceL(const TDesC8 &aData);

Description

Initializes the audio device and starts playing a tone sequence.

Leaves on failure.

Parameters

IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber);

Description

Initializes the audio device and starts playing the specified pre-defined tone sequence.

Leaves on failure.

Parameters

See also:

• CMMFDevSound::FixedSequenceCount()Returns the number of available pre-defined tone sequences.

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

Description

Defines the number of times the audio is to be repeated during the tone playback operation.

A period of silence can follow each playing of a tone. The tone playing can be repeated indefinitely.

Parameters

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

Supported only during tone playing.

Parameters

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

The function is only available while the tone is playing.

Parameters

IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings &aPrioritySettings);

Description

Defines the priority settings that should be used for this instance.

Parameters

IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

Description

Retrieves a custom interface to the device.

Parameters

Return value

IMPORT_C TInt FixedSequenceCount();

Description

Returns the number of available pre-defined tone sequences.

This is the number of fixed sequence supported by DevSound by default.

Return value

IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber);

Description

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

This is the number of the fixed sequence supported by DevSound by default.

The function raises a panic if sequence number specified is invalid.

Parameters

Return value

See also:

• CMMFDevSound::FixedSequenceCount()Returns the number of available pre-defined tone sequences.

IMPORT_C void GetSupportedInputDataTypesL(RArray< TFourCC > &aSupportedDataTypes, const TMMFPrioritySettings &aPrioritySettings) const;

Description

Returns a list of the supported input datatypes that can be sent to DevSound for playing audio. The datatypes returned are those that the DevSound supports given the priority settings passed in aPrioritySettings.

Note that if no supported data types are found this does not constitute failure, the function will return normally with no entries in aSupportedDataTypes.

Parameters

IMPORT_C void GetSupportedOutputDataTypesL(RArray< TFourCC > &aSupportedDataTypes, const TMMFPrioritySettings &aPrioritySettings) const;

Description

Returns a list of the supported output dataypes that can be received from DevSound for recording audio. The datatypes returned are those that the DevSound supports given the priority settings passed in aPrioritySettings.

Note that if no supported data types are found this does not constitute failure, the function will return normally with no entries in aSupportedDataTypes.

Parameters

inline TInt RegisterAsClient(TUid aEventType, const TDesC8 &aNotificationRegistrationData=KNullDesC8);

Description

Registers the client for notification of resource avalibility.

Parameters

Return value

inline TInt CancelRegisterAsClient(TUid aEventType);

Description

Cancels the Registered Notification.

Parameters

Return value

inline TInt GetResourceNotificationData(TUid aEventType, TDes8 &aNotificationData);

Description

Returns the Notification data which the client needs to resume playing.

Parameters

Return value

inline TInt WillResumePlay();

Description

Wait for the clients to resume play back even after the default timeout expires. Unless the client cancels the notification request or completes no other client gets notification.

Return value

protected: CBody * iBody;

Description

DevSound body