Collapse all Symbian^3 Application Developer Library

CMdaAudioInputStream Class Reference

class CMdaAudioInputStream : public CBase

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

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

MaiscRecordComplete() is called after Stop() has been called. aError - KErrAbort if MaiscRecordComplete called as a result of a call to 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.

Inherits from

CMdaAudioInputStream
- CBase

Public Member Functions
	~CMdaAudioInputStream ()
IMPORT_C TInt	BitRateL ()
IMPORT_C TAny *	CustomInterface ( TUid )
IMPORT_C TFourCC	DataType ()
IMPORT_C TInt	Gain ()
IMPORT_C TInt	GetBalanceL ()
IMPORT_C TInt	GetBytes ()
IMPORT_C void	GetSupportedBitRatesL ( RArray < TInt > &)
IMPORT_C TInt	MaxGain ()
IMPORT_C CMdaAudioInputStream *	NewL ( MMdaAudioInputStreamCallback &)
IMPORT_C CMdaAudioInputStream *	NewL ( MMdaAudioInputStreamCallback &, TInt , TInt )
IMPORT_C void	Open ( TMdaPackage *)
IMPORT_C const TTimeIntervalMicroSeconds &	Position ()
IMPORT_C void	ReadL ( TDes8 &)
IMPORT_C void	RequestStop ()
IMPORT_C void	SetAudioPropertiesL ( TInt , TInt )
IMPORT_C void	SetBalanceL ( TInt )
IMPORT_C void	SetBitRateL ( TInt )
IMPORT_C void	SetDataTypeL ( TFourCC )
IMPORT_C void	SetGain ( TInt )
IMPORT_C void	SetPriority ( TInt , TInt )
IMPORT_C void	SetSingleBufferMode ( TBool )
IMPORT_C void	Stop ()

Private Member Functions
	CMdaAudioInputStream ()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
CMMFMdaAudioInputStream *	iProperties

Constructor & Destructor Documentation

CMdaAudioInputStream()

CMdaAudioInputStream

(

)

[private]

~CMdaAudioInputStream()

~CMdaAudioInputStream

(

)

Destructor.

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

Member Functions Documentation

BitRateL()

IMPORT_C TInt

BitRateL

(

)

const

Returns the current bit rate.

leave: KErrNotSupported If the sound device does not support returning the current bit rate

CustomInterface(TUid)

IMPORT_C TAny *

CustomInterface

(

TUid

aInterfaceId

)

Retrieves a custom interface to the underlying device.

Parameters

TUid aInterfaceId

The interface UID, defined with the custom interface.

DataType()

IMPORT_C TFourCC

DataType

(

)

const

Returns the current data type.

Gain()

IMPORT_C TInt

Gain

(

)

const

Returns the current gain setting.

GetBalanceL()

IMPORT_C TInt

GetBalanceL

(

)

const

Returns the current audio balance.

GetBytes()

IMPORT_C TInt

GetBytes

(

)

Returns the current number of bytes rendered by audio hardware.

GetSupportedBitRatesL(RArray< TInt > &)

IMPORT_C void

GetSupportedBitRatesL

(

RArray < TInt > &

aSupportedBitRates

)

Returns the bit rates supported by the sound device

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

Parameters

RArray < TInt > & aSupportedBitRates

MaxGain()

IMPORT_C TInt

MaxGain

(

)

const

Returns the maximum gain level.

NewL(MMdaAudioInputStreamCallback &)

IMPORT_C CMdaAudioInputStream *

NewL

(

MMdaAudioInputStreamCallback &

aCallBack

)

[static]

Instantiates a new audio input stream using default priority preferences.

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

Static NewL

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.

NewL(MMdaAudioInputStreamCallback &, TInt, TInt)

IMPORT_C CMdaAudioInputStream *	NewL	(	MMdaAudioInputStreamCallback &	aCallBack,
			TInt	aPriority,
			TInt	aPref
		)	[static]

Instantiates a new audio input stream.

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

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

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	The 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	The 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 *)

IMPORT_C void

Open

(

TMdaPackage *

aSettings

)

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.

Position()

IMPORT_C const TTimeIntervalMicroSeconds &

Position

(

)

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

ReadL(TDes8 &)

IMPORT_C void

ReadL

(

TDes8 &

aData

)

Records streaming raw audio data.

If this is the first ReadL() after a successful Open() 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 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.

RequestStop()

IMPORT_C void

RequestStop

(

)

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.

CMdaAudioInputStream::Stop()

SetAudioPropertiesL(TInt, TInt)

IMPORT_C void	SetAudioPropertiesL	(	TInt	aSampleRate,
			TInt	aChannels
		)

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.

SetBalanceL(TInt)

IMPORT_C void

SetBalanceL

(

TInt

aBalance = KMMFBalanceCenter

)

Sets the current audio balance.

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

Parameters

TInt aBalance = KMMFBalanceCenter

A specified balance value.

SetBitRateL(TInt)

IMPORT_C void

SetBitRateL

(

TInt

aBitRate

)

Sets the bit rate to a new value.

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

Parameters

TInt aBitRate

The new bit rate, in bits per second.

SetDataTypeL(TFourCC)

IMPORT_C void

SetDataTypeL

(

TFourCC

aAudioType

)

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 aAudioType

The fourCC code used to request the data type of the recorded data.

SetGain(TInt)

IMPORT_C void

SetGain

(

TInt

aNewGain

)

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 MaxGain(). A value which is less than zero is set to zero. A value which is greater than MaxGain() is set to MaxGain().

SetPriority(TInt, TInt)

IMPORT_C void	SetPriority	(	TInt	aPriority,
			TInt	aPref
		)

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

CMdaAudioInputStream::NewL()

Parameters

TInt aPriority	The Priority Value.
TInt aPref	The Priority Preference.

SetSingleBufferMode(TBool)

IMPORT_C void

SetSingleBufferMode

(

TBool

aSingleMode

)

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.

Stop()

IMPORT_C void

Stop

(

)

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.

CMdaAudioInputStream::RequestStop()

Member Data Documentation

CMMFMdaAudioInputStream * iProperties

CMMFMdaAudioInputStream *

iProperties

[private]