Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]

#include <MdaAudioInputStream.h>
Link against: mediaclientaudioinputstream.lib

Class CMdaAudioInputStream

class CMdaAudioInputStream : public CBase, public MMMFClientUtility;

Description

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

This class enables MMF clients to:

Stream raw audio data from the audio hardware to 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 gain and balance before or while streaming is in progress. Gain and balance settings take effect immediately.

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

MaiscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the user as a result of a previous call to CMdaAudioInputStream::Open(TMdaPackage *).

MaiscBufferCopied() will be called multiple times while the FIFO (queued via CMdaAudioInputStream::ReadL(TDes8 &)) is emptied. Note: Each buffer will be flagged with KErrAbort if received after CMdaAudioInputStream::Stop() on is called. MaiscRecordComplete is called once all remaining buffers have been read.

MaiscRecordComplete() is called after CMdaAudioInputStream::Stop() has been called. aError - KErrAbort if MaiscRecordComplete called as a result of a call to CMdaAudioInputStream::Stop().

Users of object CMdaAudioInputStream should ensure that implementation of the callback methods MaiscOpenComplete,MaiscBufferCopied and MaiscRecordComplete in class MMdaAudioInputStreamCallback do not delete the object,otherwise a Kern-Exec 3 would occur during callback.

Derivation

Members

Defined in CMdaAudioInputStream:

Inherited from CBase:


Construction and destruction


NewL(MMdaAudioInputStreamCallback &)

Capability: UserEnvironment For recording - the requesting client process must have a UserEnvironment capability.

IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback &aCallBack);

Description

Instantiates a new audio input stream using default priority preferences.

Parameters

MMdaAudioInputStreamCallback &aCallBack

A callback to notify the client when the input stream has been initialised and is ready for use, when data has been copied to a specified descriptor and when input streaming is stopped. The caller must create a callback class that implements this interface.

Return value

CMdaAudioInputStream *

A pointer to the audio input stream object.


NewL(MMdaAudioInputStreamCallback &,TInt,TMdaPriorityPreference)

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.
Capability: UserEnvironment For recording - the requesting client process must have a UserEnvironment capability.

IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback &aCallBack, TInt aPriority, TMdaPriorityPreference aPref);

Description

Instantiates a new audio input stream.

Parameters

MMdaAudioInputStreamCallback &aCallBack

A callback to notify the client when the input stream has been initialised and is ready for use. 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

CMdaAudioInputStream *

A pointer to the audio input stream object.

[Top]


Member functions


SetAudioPropertiesL(TInt,TInt)

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


Open(TMdaPackage *)

IMPORT_C void Open(TMdaPackage *aSettings);

Description

Opens an input audio stream package.

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

Parameters

TMdaPackage *aSettings

A pointer to an TMdaPackage object.


SetGain(TInt)

IMPORT_C void SetGain(TInt aNewGain);

Description

Sets the gain for the audio device to a specified value.

Parameters

TInt aNewGain

The gain setting. This can be any value from zero to the value returned by a call to CMdaAudioInputStream::MaxGain()const. A value which is less than zero is set to zero. A value which is greater than CMdaAudioInputStream::MaxGain()const is set to CMdaAudioInputStream::MaxGain()const.


Gain()const

IMPORT_C TInt Gain() const;

Description

Returns the current gain setting.

Return value

TInt

The current gain setting.


MaxGain()const

IMPORT_C TInt MaxGain() const;

Description

Returns the maximum gain level.

Return value

TInt

The maximum gain value that is supported by the sound device.


SetBalanceL(TInt)

IMPORT_C void SetBalanceL(TInt aBalance=KMMFBalanceCenter);

Description

Sets the current audio balance.

The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value being KMMFBalanceCenter.

Parameters

TInt aBalance

A specified balance value.


GetBalanceL()const

IMPORT_C TInt GetBalanceL() const;

Description

Returns the current audio balance.

Return value

TInt

The current balance value.


SetPriority(TInt,TMdaPriorityPreference)

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 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 CMdaAudioInputStream::Open(TMdaPackage *) is issued, or between a previous CMdaAudioInputStream::Stop() and a new CMdaAudioInputStream::Open(TMdaPackage *).

Parameters

TInt aPriority

The priority level to apply, EMdaPriorityMin means the client can be interrupted by any other client, EMdaPriorityNormal means the client is only interrupted by clients with a higher priority and EMdaPriorityMax means 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.


ReadL(TDes8 &)

IMPORT_C void ReadL(TDes8 &aData);

Description

Records streaming raw audio data.

If this is the first CMdaAudioInputStream::ReadL(TDes8 &) after a successful CMdaAudioInputStream::Open(TMdaPackage *) this function starts the audio recording process.

The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is called when the buffer has been successfully filled. A pointer to the newly filled buffer is returned in the callback.

Note: The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is also called when a CMdaAudioInputStream::Stop() is issued, with a pointer to the remaining recorded audio data and the aError parameter of the callback set to indicate recording has finished.

Parameters

TDes8 &aData

A reference to a buffer to be written into.


Stop()

IMPORT_C void Stop();

Description

Stops the recording process.

The MMdaAudioInputStreamCallback::MaisRecordComplete() callback function is called when recording has been halted. Just prior to issuing this callback, the FIFO buffers are read and the remaining audio data passed back by a final MMdaAudioInputStreamCallback::MaisBufferCopied() callback with its aError parameter set to KErrAbort.

Any remaining FIFO buffers are also passed back, with their aError parameter set to KErrAbort.

Stop is immediate and best used for premature stops, for example within destructors. If it is critical to receive all data buffers upto the point that Recording has Stopped, we recommend using RequestStop instead. Otherwise some trailing buffers may be lost from the recording process.

If a Stop is issued after a RequestStop, Stop will take precedent.

See also:


Position()

IMPORT_C const TTimeIntervalMicroSeconds& Position();

Description

Returns the current position within the data stream in microseconds since the start of streaming.

Return value

const TTimeIntervalMicroSeconds &

The current position.


GetBytes()

IMPORT_C TInt GetBytes();

Description

Returns the current number of bytes rendered by audio hardware.

Return value

TInt

The number of bytes.


SetDataTypeL(TFourCC)

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 request the data type of the recorded data.

Leave codes

KErrNotSupported

Leaves with this for any unsuported data type.


DataType()const

IMPORT_C TFourCC DataType() const;

Description

Returns the current data type.

Return value

TFourCC

The ID of the data type.


GetSupportedBitRatesL(RArray< TInt > &)

IMPORT_C void GetSupportedBitRatesL(RArray< TInt > &aSupportedBitRates);

Description

Returns the bit rates supported by the sound device

Parameters

RArray< TInt > &aSupportedBitRates

Leave codes

KErrNotSupported

If the sound device does not support setting the bit rate The supported bit rates, in bits per second, shall be appended to this array. Note that the array shall be reset by this method.


BitRateL()const

IMPORT_C TInt BitRateL() const;

Description

Returns the current bit rate.

Return value

TInt

The current bit rate, in bits per second.

Leave codes

KErrNotSupported

If the sound device does not support returning the current bit rate


SetBitRateL(TInt)

IMPORT_C void SetBitRateL(TInt aBitRate);

Description

Sets the bit rate to a new value.

Parameters

TInt aBitRate

The new bit rate, in bits per second.

Leave codes

KErrNotSupported

If the sound device does not support returning the current bit rate or the bit rate set is not supported


CustomInterface(TUid)

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.


SetSingleBufferMode(TBool)

IMPORT_C void SetSingleBufferMode(TBool aSingleMode);

Description

Indicates that the client wishes to use a single buffer to collect the data. This buffer is passed via the ReadL api.

Parameters

TBool aSingleMode

ETrue to indicate setting of single buffer mode and the use of a single buffer, EFalse to indicate use of multiple buffers.


RequestStop()

IMPORT_C void RequestStop();

Description

Requests a Stop of the recording process.

The device is requested to Stop and does so after all unprocessed buffers are processed and passed back to the input stream. The device is actually Stopped when the final empty buffer indicating buffer process completion is received.

See also: