snd_pcm_plugin

Transfer PCM data from the capture channel (plugin-aware)

Synopsis:

#include <sys/asoundlib.h>

ssize_t snd_pcm_plugin_read( snd_pcm_t *handle, 
                             void      *buffer, 
                             size_t     size );

Arguments:

handle: The handle for the PCM device, which you must have opened by calling snd_pcm_open_name(), snd_pcm_open(), or snd_pcm_open_preferred().
buffer: A pointer to a buffer in which snd_pcm_plugin_read() can store the data that it reads.
size: The size of the buffer, in bytes.

Library:

libasound.so

Use the -l asound option with qcc to link against this library.

Description:

The snd_pcm_plugin_read() function reads samples from the device which must be in the proper format specified by snd_pcm_plugin_params().

Note: The handle and the buffer must be valid.

This function may suspend the client application if block behavior is active (see snd_pcm_nonblock_mode()) and no data is available for reading.

Returns:

A positive value that represents the number of bytes that were successfully read from the device if the capture was successful, or a negative errno if an error occurred. The errno values are available in the errno.h file.

Errors:

-EFAULT: Failed to copy data.
-EINVAL: Partial block buffering is disabled, but the size isn't the full block size.
-EIO: The channel isn't in the prepared or running state.
-ENOMEM: Unable to allocate memory for plugin buffers.

Note: If you're reading less than a fragment-sized block, you won't get an -EFAULT or -EIO error until enough read operations have been completed to read the fragment size. The sub-buffering plugin buffers all operations until there is a fragment's worth of data, at which point the message to io-audio occurs (you can't get an error until the request goes to io-audio).

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Read the Caveats

Caveats:

This function is not thread safe if handle (snd_pcm_t) is used across multiple threads.

This function is the plugin-aware version of snd_pcm_read() . It functions exactly the same way, with only one caveat (see below). However, make sure that you don't mix and match plugin- and nonplugin-aware functions in your application, or you may get undefined behavior and misleading results.

The plugin-aware versions of the PCM read and write calls don't require that you work with multiples of fragment-size blocks (the nonplugin-aware versions do). This is because one of the plugins in the lib sub-buffers the data for you. You can disable this plugin by setting the PLUGIN_BUFFER_PARTIAL_BLOCKS bit with snd_pcm_plugin_set_disable() , in which case, the plugin-aware versions also fail on reads and writes that aren't multiples of the fragment size.

Either way, interleaved stereo data has to be aligned by the sample size times the number of channels (i.e. each write must have the same number of samples for the left and right channels).