Class CMdaAudioOutputStream

class CMdaAudioOutputStream : public CBase, public MMMFClientUtility;

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 CMdaAudioOutputStream::Open(TMdaPackage *).

MaoscBufferCopied() Each time audio data has been successfully copied to the lower layers of the MMF as a result of a previous ReadL().

MaoscRecordComplete: When the audio data stream has been closed as a result of a previous CMdaAudioOutputStream::Stop().

Derivation

• MMMFClientUtility - No description.
• CBase - Base class for all classes to be instantiated on the heap.

• CMdaAudioOutputStream - ...

Members

Defined in CMdaAudioOutputStream:

• CancelRegisterAudioResourceNotification(TUid)Cancels the registered notification event.
• CustomInterface(TUid)Retrieves a custom interface to the underlying device.
• DataType()constReturns the current data type.
• GetBalanceL()constReturns the current balance as an integer.
• GetBytes()Returns the current number of bytes rendered by audio hardware.
• MaxVolume()Returns the maximum volume level.
• NewL(MMdaAudioOutputStreamCallback &,CMdaServer *)Allocates and constructs an audio stream player object.
• NewL(MMdaAudioOutputStreamCallback &,TInt,TMdaPriorityPreference)Constructs and initialises a new instance of an audio streaming object.
• Open(TMdaPackage *)Opens an output audio stream package.
• Position()Returns the current position within the data stream.
• RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &,TUid,const TDesC8 &)Registers the Event for Notification when resource is avaliable.
• SetAudioPropertiesL(TInt,TInt)Sets the sample rate and number of audio channels.
• SetBalanceL(TInt)Sets the audio balance.
• SetDataTypeL(TFourCC)Sets the data type. If the data type is not explicitly set it will assumed to be...
• SetPriority(TInt,TMdaPriorityPreference)Sets the audio priority values.
• SetVolume(const TInt)Sets the audio volume.
• Stop()Stops writing data to a stream.
• Volume()Returns the current volume.
• WillResumePlay()Waits for the client to resume the play even after the default timer expires.
• WriteL(const TDesC8 &)Writes (plays) streaming raw audio data.

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 CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback &aCallBack, CMdaServer *aServer=0);

Description

Allocates and constructs an audio stream player object.

Parameters

MMdaAudioOutputStreamCallback &aCallBack A 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 A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided for backward compatibility.

Return value

CMdaAudioOutputStream * A pointer to new audio stream player.

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback &aCallBack, TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

Description

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

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

Parameters

MMdaAudioOutputStreamCallback &aCallBack A 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 aPriority 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. TMdaPriorityPreference aPref The required behaviour if a higher priority client takes over the sound output device.

Return value

CMdaAudioOutputStream * A pointer to CMdaAudioOutputStream.

virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

Description

Sets the sample rate and number of audio channels.

Parameters

TInt aSampleRate The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings. TInt aChannels The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.

virtual void Open(TMdaPackage *aSettings);

Description

Opens an output audio stream package.

The MMdaAudioOutputStreamCallback::MaosOpenComplete() 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 *aSettings A pointer to a TMdaPackage object.

virtual TInt MaxVolume();

Description

Returns the maximum volume level.

Return value

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

virtual TInt Volume();

Description

Returns the current volume.

Return value

TInt The current volume as an integer.

virtual void SetVolume(const TInt aNewVolume);

Description

Sets the audio volume.

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

Parameters

const TInt aNewVolume A specified audio volume.

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

virtual void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

Description

Sets the audio priority values.

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

Parameters

TInt aPriority The priority level to apply, EMdaPriorityMin allows the client can be interrupted by any other client, EMdaPriorityNormal allows the client is only interrupted by clients with a higher priority or EMdaPriorityMax allows the client cannot be interrupted by other clients. TMdaPriorityPreference aPref A set of priority values that define the behaviour to be adopted by a client using a sound device if a higher priority client takes over that device.

virtual void WriteL(const TDesC8 &aData);

Description

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(TInt,const TDesC8 &). The client can call CMdaAudioOutputStream::WriteL(const TDesC8 &) 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(TInt) is called when all descriptors have been sent.

Parameters

const TDesC8 &aData A reference to the stream data.

virtual void Stop();

Description

Stops writing data to a stream.

virtual const TTimeIntervalMicroSeconds& Position();

Description

Returns the current position within the data stream.

Return value

const TTimeIntervalMicroSeconds & The current position within the stream in microseconds.

IMPORT_C void SetBalanceL(TInt aBalance=KMMFBalanceCenter);

Description

Sets the audio balance.

Parameters

TInt aBalance A specified balance volume. Default is KMMFBalanceCenter.

IMPORT_C TInt GetBalanceL() const;

Description

Returns the current balance as an integer.

Return value

TInt The current balance value as integer.

IMPORT_C TInt GetBytes();

Description

Returns the current number of bytes rendered by audio hardware.

Return value

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

IMPORT_C void SetDataTypeL(TFourCC aAudioType);

Description

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

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

Leave codes

KErrNotSupported Leaves with this for any unsuported data type.

IMPORT_C TFourCC DataType() const;

Description

Returns the current data type.

Return value

TFourCC The ID of the data type.

IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &aCallback, TUid aNotificationEventUid, const TDesC8 &aNotificationRegistrationData=KNullDesC8);

Description

Registers the Event for Notification when resource is avaliable.

Parameters

MMMFAudioResourceNotificationCallback &aCallback The audio outputstream observer interface.. TUid aNotificationEventUid The Event for which the client is registered. const TDesC8 &aNotificationRegistrationData Notification registration specific data.

Return value

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

IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);

Description

Cancels the registered notification event.

Parameters

TUid aNotificationEventId The Event to notify the client.

Return value

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

IMPORT_C TInt WillResumePlay();

Description

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

Return value

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

IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

Description

Retrieves a custom interface to the underlying device.

Parameters

TUid aInterfaceId The interface UID, defined with the custom interface.

Return value

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