SoundIo Class Reference
[Audio I/O and Signal Processing]

Audio Source/Sink Interface. More...

#include <soundio.h>

Inheritance diagram for SoundIo:

[legend]

List of all members.

Public Member Functions
virtual bool	SndOpen (bool sink, bool source, ErrorInfo *error=0)=0
	Request that the underlying device be opened.
virtual void	SndClose (void)=0
	Request that an opened underlying device be closed.
virtual void	SndGetProps (SoundIoProps &props) const =0
	Get Basic Capabilities.
virtual void	SndGetFormat (SoundIoFormat &format) const =0
	Get Current PCM Data Stream Format.
virtual bool	SndSetFormat (SoundIoFormat &format, ErrorInfo *error=0)=0
	Set Current PCM Data Stream Format.
virtual void	SndGetIBuf (SoundIoBuffer &fillme)=0
	Request Input Buffer Access.
virtual void	SndDequeueIBuf (sio_sampnum_t nsamples)=0
	Request Dequeueing of Input Samples.
virtual void	SndGetOBuf (SoundIoBuffer &fillme)=0
	Request Output Buffer Access.
virtual void	SndQueueOBuf (sio_sampnum_t nsamples)=0
	Request Queueing of Output Samples.
virtual void	SndGetQueueState (SoundIoQueueState &qs)=0
	Query the queue state of the device.
virtual bool	SndAsyncStart (bool sink, bool source, ErrorInfo *error=0)=0
	Request start of asynchronous audio handling.
virtual void	SndAsyncStop (void)=0
	Request halting of asynchronous audio handling.
virtual bool	SndIsAsyncStarted (void) const =0
	Query whether asynchronous audio handling has been started.
Public Attributes
Callback< void, SoundIo *, SoundIoQueueState & >	cb_NotifyPacket
	Notification of Audio Packet Data Availability.
Callback< void, SoundIo *, ErrorInfo & >	cb_NotifyAsyncStop
	Notification of Asynchronous Audio Processing Termination.

---

Detailed Description

Audio Source/Sink Interface.

SoundIo abstracts a full-duplex PCM audio hardware device, including input and output queues, and asynchronous notification.

There are SoundIo derived classes for handling ALSA and OSS type sound card interfaces on Linux. See SoundIoCreateOss() and SoundIoCreateAlsa(). SoundIo is implemented by HfpSession for streaming voice audio over Bluetooth.

---

Member Function Documentation

virtual bool SndOpen	(	bool	sink,
		bool	source,
		ErrorInfo *	error = 0
	)			[pure virtual]

Request that the underlying device be opened.

Attempts to open the underlying resource, if applicable. For sound card driver frontends, such as the ALSA and OSS modules, this method causes the sound card device to be opened and claimed.

The details of the device to be opened are assumed to have been set when the SoundIo derived object was constructed. These details might include the name and basic configuration of the device, e.g. SoundIoCreateAlsa(). Such details are not provided to this method.

Parameters:

[in]	sink	Set to true to open the output side of the device
[in]	source	Set to true to open the input side of the device
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Open Succeeded, SoundIo is now usable
	false	Open Failed. If the error parameter is not 0, it will be filled out with specific information about the failure. Typical reasons for failure include: Creation or opening of a necessary file (if applicable) failed. The underlying hardware device (if applicable) is in use. The underlying hardware device (if applicable) does not support the last PCM data stream format configured via SndSetFormat(). Both the play and capture parameters were set to false. The device is not ready, e.g. HfpSession::SndOpen() will return false until its socket-level connection is complete.

See also:

SndClose()

virtual void SndClose

(

void

)

[pure virtual]

Request that an opened underlying device be closed.

Closes an underlying device that was previously opened with SndOpen(). Resources should be released. For sound card driver frontends, such as the ALSA and OSS modules, this method causes the underlying devices to be closed and released.

See also:

SndOpen()

virtual void SndGetProps

(

SoundIoProps &

props

)

const [pure virtual]

Get Basic Capabilities.

This method fills in a structure describing the basic capabilities of the interface. Some modules, such as the ALSA and OSS frontends, support full-duplex, asynchronous operation. Others, such as the file module, support only input-only or output-only synchronous operation.

Parameters:

[out]

props

Properties structure to be filled out

Postcondition:

props.has_clock will be set to true if the object supports asynchronous notification through SoundIo::cb_NotifyPacket, false otherwise.

props.does_source will be set to true if the object supports input, false otherwise.

props.does_sink will be set to true if the object supports output, false otherwise.

props.does_loop will be set to true if the object's input buffer grows immediately as data is submitted to its output buffer, false otherwise.

The result of this method may differ depending on:

• Whether the device (if applicable) is open. Some objects will not return meaningful results unless they are open. See SndOpen().
• The active configuration of the object. See SndSetFormat().
• Parameters supplied when the object was constructed. For example, providing a NULL output device specifier to the ALSA frontend will cause it to set SoundIoProps::does_sink = false.

virtual void SndGetFormat

(

SoundIoFormat &

format

)

const [pure virtual]

Get Current PCM Data Stream Format.

This method fills out a SoundIoFormat structure based on the object's currently configured PCM data stream format. This method may be invoked on objects in the open or closed states, but in general, the result should only be considered meaningful for objects in the open state.

Parameters:

[out]

format

Structure to be filled with the object's currently configured data stream format.

The result of this method may be affected by:

• Whether the device (if applicable) is open. Some objects will not return meaningful results unless they are open. An object will always return the most specific results when it is open. See SndOpen().
• Parameters supplied when the object was constructed.

virtual bool SndSetFormat	(	SoundIoFormat &	format,
		ErrorInfo *	error = 0
	)			[pure virtual]

Set Current PCM Data Stream Format.

This method attempts to reconfigure the PCM data stream format of the object. This method may be invoked on objects in the open or closed states.

Parameters:

[in,out]	format	Structure containing the new format parameters to be applied to the object, which is filled with the resulting effective parameters on return.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Parameters accepted and applied. Note that in some cases, for objects in the closed state, this is a tentative approval of the stream format.
	false	One or more mandatory parameter values are not supported by the object.

The Mandatory Parameters include:

• SoundIoFormat::sampletype, which must be exactly supported.
• SoundIoFormat::samplerate, which must be exactly supported.
• SoundIoFormat::nchannels, which must be exactly supported.

The other fields of the SoundIoFormat object, including SoundIoFormat::packet_samps, are guidelines. The object may use any convenient value for these fields. On success, the contents of the format parameter will be updated to reflect the effective values.

virtual void SndGetIBuf

(

SoundIoBuffer &

fillme

)

[pure virtual]

Request Input Buffer Access.

Clients of SoundIo objects access their input and output sample buffers directly. This method requests access to the object's input (capture) buffer.

Parameters:

[in,out]

fillme

The buffer descriptor containing the requested size, to be filled with the memory location and actual size.

Precondition:

The requested size of the buffer, in sample records, is passed in through the fillme.m_size field. If this value is zero, the largest possible buffer will be requested.

Postcondition:

The resulting buffer is returned through the fillme.m_data field. The valid size of the buffer, in sample records, is returned through the fillme.m_size field. If fillme.m_size is set to zero on return, no input samples are available, and fillme.m_data should be considered invalid. If a specific buffer size was requested, the resulting buffer size should never be larger, but may be smaller.

The returned buffer always contains the least recent input samples. After a client has finished examining the input buffer, it should dequeue some number of input samples with SndDequeueIBuf(). After samples are dequeued, SndGetIBuf() will make more recent input samples available.

Buffers returned through this method will remain valid until:

• All input samples returned through this method are dequeued via SndDequeueIBuf().
• Asynchronous handling is halted via SndAsyncStop(), or a SoundIo::cb_NotifyAsyncStop callback is received.
• The object is closed via SndClose().

This method will only return useful results when invoked on objects in the open state.

See also:

SndDequeueIBuf(), SndGetQueueState()

Implemented in SoundIoBufferBaseSync.

virtual void SndDequeueIBuf

(

sio_sampnum_t

nsamples

)

[pure virtual]

Request Dequeueing of Input Samples.

When a SoundIo client has finished processing input samples accessed through SndGetIBuf(), or merely wishes to discard them, it may do so using this method. Input samples need not have been accessed using SndGetIBuf() in order to be dequeued through this method.

Parameters:

nsamples

Number of sample records to remove from the start of the input queue

Note:

If the entire range of an input buffer previously acquired by SndGetIBuf() is fully dequeued, the input buffer will become invalid, and attempts to access it may cause SIGSEGV. Clients must take care to avoid reusing input buffers in this way.

Warning:

Attempting to dequeue more input samples than are available is not permitted and should cause an assertion failure.

Implemented in SoundIoBufferBaseSync.

virtual void SndGetOBuf

(

SoundIoBuffer &

fillme

)

[pure virtual]

Request Output Buffer Access.

Clients of SoundIo objects access their input and output sample buffers directly. This method requests access to the object's input (capture) buffer.

Parameters:

[in,out]

fillme

The buffer descriptor containing the requested size, to be filled with the memory location and actual size.

Precondition:

The requested size of the buffer, in sample records, is passed in through the fillme.m_size field. If this value is zero, the largest possible buffer will be requested.

Postcondition:

The resulting buffer is returned through the fillme.m_data field. The valid size of the buffer, in sample records, is returned through the fillme.m_size field. If fillme.m_size is set to zero on return, no input samples are available, and fillme.m_data should be considered invalid. If a specific buffer size was requested, the resulting buffer size should never be larger, but may be smaller.

To output audio data, a client would fill the returned buffer with its next batch of outbound sample records. After part or all of the buffer has been filled, the client should call the SndQueueOBuf() method to propagate the sample records.

Buffers returned through this method will remain valid until:

• Any number of output samples are queued via SndQueueOBuf().
• Asynchronous handling is halted via SndAsyncStop(), or a SoundIo::cb_NotifyAsyncStop callback is received.
• The object is closed via SndClose().

This method will only return useful results when invoked on objects in the open state.

See also:

SndQueueOBuf(), SndGetQueueState()

Implemented in SoundIoBufferBaseSync.

virtual void SndQueueOBuf

(

sio_sampnum_t

nsamples

)

[pure virtual]

Request Queueing of Output Samples.

When a SoundIo client has finished filling part or all of an output buffer accessed via SndGetOBuf(), it may request the sample records be propagated to their destination with this method.

Parameters:

nsamples

Number of sample records copied into the output buffer to be propagated

Warning:

Each call to SndQueueOBuf() must have been preceded by a call to SndGetOBuf().

Attempting to queue more samples than were previously returned by SndGetOBuf() is not permitted and should cause an assertion failure.

Implemented in SoundIoBufferBaseSync.

virtual void SndGetQueueState

(

SoundIoQueueState &

qs

)

[pure virtual]

Query the queue state of the device.

This method fills out a SoundIoQueueState structure with the fill levels of the sample buffers of the SoundIo object. This information is required by the SoundIoPump class, which uses it to make transfer size decisions.

For sound cards and other clocked sources, this information is assumed to represent the state of the local device buffers, which must fill and drain as the device processes samples.

For unclocked sinks, this information is assumed to represent a minimum number of samples available. SoundIoPump will not transfer more than qs.out_queued samples.

Parameters:

[out]

qs

Queue state structure to be filled in

Note:

This method may only be expected to return useful results when the device is opened.

Warning:

Bugs in this method can cause SoundIoPump problems that are difficult to trace back to this method.

Implemented in SoundIoBufferBaseSync.

virtual bool SndAsyncStart	(	bool	sink,
		bool	source,
		ErrorInfo *	error = 0
	)			[pure virtual]

Request start of asynchronous audio handling.

For SoundIo objects that support asynchronous operation, this method can be used to initiate it.

Parameters:

[in]	sink	Set to true to start asynchronous output
[in]	source	Set to true to start asynchronous input
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Asynchronous audio handling mode has been started
	false	Error enabling asynchronous data mode

When asynchronous audio handling mode is operating, periodic calls will be made to the SoundIo::cb_NotifyPacket callback.

Once asynchronous audio handling is successfully started, it may be spontaneously aborted due to an unexpected condition, such as a sound card catching on fire. In this case, the SoundIo object will automatically halt asynchronous audio handling, and will inform its client of this by making a call to SoundIo::cb_NotifyAsyncStop with the second parameter set to describe the reason for stopping.

See also:

SoundIo::cb_NotifyPacket, SoundIo::cb_NotifyAsyncStop, SndAsyncStop()

virtual void SndAsyncStop

(

void

)

[pure virtual]

Request halting of asynchronous audio handling.

For SoundIo objects that are currently operating in asynchronous mode, this method can be used to halt processing and cease future calls to SoundIo::cb_NotifyPacket.

See also:

SoundIo::cb_NotifyPacket, SndAsyncStart()

virtual bool SndIsAsyncStarted

(

void

)

const [pure virtual]

Query whether asynchronous audio handling has been started.

Return values:

	true	Asynchronous audio handling is started
	false	Asynchronous audio handling is not started

---

Member Data Documentation

Callback<void, SoundIo*, SoundIoQueueState&> cb_NotifyPacket

Notification of Audio Packet Data Availability.

The cb_NotifyPacket callback is invoked slightly after each packet period boundary, as measured from the hardware clock of the audio device.

Parameters:

	SoundIo*	Pointer to the SoundIo-derived object that initiated the call. This object may have new input sample records, or may have completed handling of part or all of its output queue.
	SoundIoQueueState&	A SoundIoQueueState structure describing the state of the sample buffers of the device: in_queued is the number of available, unprocessed input samples, or 0 if input is disabled. out_queued is the number of unplayed output samples sitting in the hardware buffer, or -1 if output is disabled. in_overflow is true if the input queue overflowed since the last SndDequeueIBuf() operation, false otherwise. out_underflow is true if the output queue underflowed since the last SndQueueOBuf() operation, false otherwise

A registered target method can be used to maintain the buffers for data in both directions.

Callback<void, SoundIo*, ErrorInfo&> cb_NotifyAsyncStop

Notification of Asynchronous Audio Processing Termination.

The cb_NotifyAsyncStop callback is invoked when a condition internal to the SoundIo object occurs that forces asynchronous audio processing to be halted. This may include the unplugging of a USB sound card, or the remote disconnection of a Bluetooth SCO socket.

This method will only be invoked when asynchronous audio handling has been started with SndAsyncStart(), and has been halted for a reason other than SndAsyncStop() or SndClose() being invoked. Once this callback has been invoked, no further calls to SoundIo::cb_NotifyPacket should be expected until asynchronous processing is resumed with SndAsyncStart().

Parameters:

	SoundIo*	Pointer to the SoundIo-derived object that initiated the call.
	ErrorInfo&	Error code describing why processing has been halted.

---

The documentation for this class was generated from the following file:

• include/libhfp/soundio.h

---