CMdaAudioOutputStream Class Reference

#include <mdaaudiooutputstream.h>

Link against: mediaclientaudiostream.lib

class CMdaAudioOutputStream : public CBase, public MMMFClientUtility

Inherits from

Detailed Description

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

Constructor & Destructor Documentation

~CMdaAudioOutputStream ( )

~CMdaAudioOutputStream()

Destructor.

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

Member Function Documentation

CancelRegisterAudioResourceNotification ( TUid )

IMPORT_C TIntCancelRegisterAudioResourceNotification(TUidaNotificationEventId)

Cancels the registered notification event.

Parameters
aNotificationEventIdThe Event to notify the client.
Return Value
An error code indicating if the registration was successful. KErrNone on success, otherwise another of the system-wide error codes.

CustomInterface ( TUid )

IMPORT_C TAny *CustomInterface(TUidaInterfaceId)

Retrieves a custom interface to the underlying device.

Parameters
aInterfaceIdThe interface UID, defined with the custom interface.
Return Value
A pointer to the interface implementation, or NULL if the device does not implement the interface requested. The return value must be cast to the correct type by the user.

DataType ( )

IMPORT_C TFourCCDataType()const

Returns the current data type.

Return Value
The ID of the data type.

GetBalanceL ( )

IMPORT_C TIntGetBalanceL()const

Returns the current balance as an integer.

Return Value
The current balance value as integer.

GetBytes ( )

IMPORT_C TIntGetBytes()

Returns the current number of bytes rendered by audio hardware.

Return Value
The current current number of bytes rendered by audio hardware as an integer.

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

See also: CMdaAudioOutputStream::RequestStop() CMMFDevSound::QueryIgnoresUnderflow()

Return Value
KErrNone on success, KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play

MaxVolume ( )

TInt MaxVolume()[virtual]

Returns the maximum volume level.

Return Value
The maximum volume level supported by the sound device, as an integer.

NewL ( MMdaAudioOutputStreamCallback &, CMdaServer * )

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

Allocates and constructs an audio stream player object.

Static NewL

Parameters
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.
aServerA pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided for backward compatibility.
Return Value
A pointer to new audio stream player.CMdaAudioOutputStream*

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
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.
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.
aPrefThe 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.
Return Value
A pointer to CMdaAudioOutputStream.CMdaAudioOutputStream*

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
aSettingsA pointer to a TMdaPackage object.

Pause ( )

IMPORT_C TIntPause()

Pause data rendering by audio hardware.

Return Value
An error code indicating if the operation was successful. KErrNone on success, KErrNotReady if not streaming KErrNotSupported if trying to pause when resume is not supported by DevSound

Position ( )

const TTimeIntervalMicroSeconds &Position()[virtual]

Returns the current position within the data stream.

Return Value
The current position within the stream in microseconds.

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.

otherwise another of the system-wide error codes.

Parameters
aCallbackThe audio player observer interface.
aNotificationEventUidThe event uid to notify the client.
aNotificationRegistrationDataNotification registration specific data.
Return Value
An error code indicating if the registration was successful. KErrNone on success, otherwise another of the system-wide error codes.An error code indicating if the registration was successful. KErrNone on success,

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.

See also: CMdaAudioOutputStream::KeepOpenAtEnd()

Return Value
KErrNone on success KErrNotSupported when this method is called without calling KeepOpenAtEnd KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream is already in the stopped state

Resume ( )

IMPORT_C TIntResume()

Resume data rendering by audio hardware.

Return Value
An error code indicating if the operation was successful. KErrNone on success, KErrNotReady if not paused. KErrNotSupported if trying to resume when resume is not supported by DevSound

SetAudioPropertiesL ( TInt, TInt )

voidSetAudioPropertiesL(TIntaSampleRate,
TIntaChannels
)[virtual]

Sets the sample rate and number of audio channels.

Parameters
aSampleRateThe new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
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
aBalanceA 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.

Parameters
aAudioTypeThe fourCC code used to specify the data type of the streamed audio
Leave Codes
KErrNotSupportedLeaves with this for any unsuported data type.

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

See also: CMdaAudioOutputStream::NewL()

Parameters
aPriorityThe Priority Value.
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
aNewVolumeA specified audio volume.

Stop ( )

voidStop()[virtual]

Stops writing data to a stream.

Volume ( )

TInt Volume()[virtual]

Returns the current volume.

Return Value
The current volume as an integer.

WillResumePlay ( )

IMPORT_C TIntWillResumePlay()

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

Return Value
An error code indicating if the registration was successful. KErrNone on success, otherwise another of the system-wide error codes.

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
aDataA reference to the stream data.