CMdaAudioOutputStream Class Reference

class CMdaAudioOutputStream : public CBase

The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.

This class enables MMF clients to:

Stream raw audio data to the audio hardware from specified buffers

Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware

Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these values once streaming has started.

Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.

The API supports callbacks from the server to notify the client:

MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the audio hardware as a result of a previous call to Open().

MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the MMF as a result of a previous WriteL().

MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().

Inherits from

  • CMdaAudioOutputStream

Constructor & Destructor Documentation

CMdaAudioOutputStream()

CMdaAudioOutputStream()[private]

~CMdaAudioOutputStream()

~CMdaAudioOutputStream()

Destructor.

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

Member Functions Documentation

CancelRegisterAudioResourceNotification(TUid)

IMPORT_C TIntCancelRegisterAudioResourceNotification(TUidaNotificationEventId)

Cancels the registered notification event.

Parameters

TUid aNotificationEventIdThe Event to notify the client.

CustomInterface(TUid)

IMPORT_C TAny *CustomInterface(TUidaInterfaceId)

Retrieves a custom interface to the underlying device.

Parameters

TUid aInterfaceIdThe interface UID, defined with the custom interface.

DataType()

IMPORT_C TFourCCDataType()const

Returns the current data type.

GetBalanceL()

IMPORT_C TIntGetBalanceL()const

Returns the current balance as an integer.

GetBytes()

IMPORT_C TIntGetBytes()

Returns the current number of bytes rendered by audio hardware.

KeepOpenAtEnd()

IMPORT_C TIntKeepOpenAtEnd()

When this method is called, AudioOutputStream goes into a different mode wherein it does not call MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream. If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play immediately by discarding all the queued data.

Client should call this method on CMdaAudioOutputStream just after its construction and its effect remains through out its lifetime.

Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of the play i.e which returns ETrue from QueryIgnoresUnderflow().

CMdaAudioOutputStream::RequestStop() CMMFDevSound::QueryIgnoresUnderflow()

MaxVolume()

TInt MaxVolume()[virtual]

Returns the maximum volume level.

NewL(MMdaAudioOutputStreamCallback &, CMdaServer *)

IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &aCallBack,
CMdaServer *aServer = NULL
)[static]

Allocates and constructs an audio stream player object.

Static NewL

Parameters

MMdaAudioOutputStreamCallback & aCallBackA callback to notify the client when the sound device is open and ready to receive data, when each descriptor has been copied and when the stream is closed. The caller must create a callback class which implements this interface.
CMdaServer * aServer = NULLA pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided for backward compatibility.

NewL(MMdaAudioOutputStreamCallback &, TInt, TInt)

IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &aCallBack,
TIntaPriority,
TIntaPref = EMdaPriorityPreferenceTimeAndQuality
)[static]

Constructs and initialises a new instance of an audio streaming object.

The function leaves if the audio streaming object cannot be created.

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.

Static NewL

Parameters

MMdaAudioOutputStreamCallback & aCallBackA callback to notify the client when the sound device is open and ready to receive data, when each descriptor has been copied and when the stream is closed. The caller must create a callback class which implements this interface.
TInt aPriorityThe 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 = EMdaPriorityPreferenceTimeAndQualityThe 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.

Open(TMdaPackage *)

voidOpen(TMdaPackage *aSettings)[virtual]

Opens an output audio stream package.

The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError parameter of the callback.

Parameters

TMdaPackage * aSettingsA pointer to a TMdaPackage object.

Pause()

IMPORT_C TIntPause()

Pause data rendering by audio hardware.

Position()

const TTimeIntervalMicroSeconds &Position()[virtual]

Returns the current position within the data stream.

RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &, TUid, const TDesC8 &)

IMPORT_C TIntRegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &aCallback,
TUidaNotificationEventUid,
const TDesC8 &aNotificationRegistrationData =  KNullDesC8
)

Registers the Event for Notification when resource is avaliable. Registers the Event for Notification when resource is avaliable.

Parameters

MMMFAudioResourceNotificationCallback & aCallbackThe audio player observer interface.
TUid aNotificationEventUidThe event uid to notify the client.
const TDesC8 & aNotificationRegistrationData =  KNullDesC8 Notification registration specific data.

RequestStop()

IMPORT_C TIntRequestStop()

This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.

Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this method returns KErrNotSupported. It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.

CMdaAudioOutputStream::KeepOpenAtEnd()

Resume()

IMPORT_C TIntResume()

Resume data rendering by audio hardware.

SetAudioPropertiesL(TInt, TInt)

voidSetAudioPropertiesL(TIntaSampleRate,
TIntaChannels
)[virtual]

Sets the sample rate and number of audio channels.

Parameters

TInt aSampleRateThe new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
TInt aChannelsThe new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.

SetBalanceL(TInt)

IMPORT_C voidSetBalanceL(TIntaBalance =  KMMFBalanceCenter )

Sets the audio balance.

Parameters

TInt aBalance =  KMMFBalanceCenter A specified balance volume. Default is KMMFBalanceCenter.

SetDataTypeL(TFourCC)

IMPORT_C voidSetDataTypeL(TFourCCaAudioType)

Sets the data type. If the data type is not explicitly set it will assumed to be pcm16. If it is set then the hardware must support the data type being set otherwise the function leaves with KErrNotSupported.

leave
KErrNotSupported Leaves with this for any unsuported data type.

Parameters

TFourCC aAudioTypeThe fourCC code used to specify the data type of the streamed audio

SetPriority(TInt, TInt)

voidSetPriority(TIntaPriority,
TIntaPref
)[virtual]

Sets the audio priority values.

This function cannot be used while the stream object is open. It is intended for use before an Open() is issued, or between a previous Stop() and a new Open().

CMdaAudioOutputStream::NewL()

Parameters

TInt aPriorityThe Priority Value.
TInt aPrefThe Priority Preference.

SetVolume(const TInt)

voidSetVolume(const TIntaNewVolume)[virtual]

Sets the audio volume.

Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().

Parameters

const TInt aNewVolumeA specified audio volume.

Stop()

voidStop()[virtual]

Stops writing data to a stream.

Volume()

TInt Volume()[virtual]

Returns the current volume.

WillResumePlay()

IMPORT_C TIntWillResumePlay()

Waits for the client to resume the play even after the default timer expires.

WriteL(const TDesC8 &)

voidWriteL(const TDesC8 &aData)[virtual]

Writes (plays) streaming raw audio data.

This function is asynchronous. When aData has been received, the client is notified by a call to MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification takes place because the buffers are maintained in a client-side queue until they have been sent. An active object performs the notification, and copies the next item in the queue to the server. MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.

Parameters

const TDesC8 & aDataA reference to the stream data.

Member Data Documentation

CMMFMdaAudioOutputStream * iProperties

CMMFMdaAudioOutputStream *iProperties[private]

This member is internal and not intended for use.