snd_pcm_plugin_drain()

Block until buffered data is fully consumed and then stop the stream (playback) or stop the stream immediately but preserve the buffered data (capture) (plugin-aware)

Synopsis:

#include <sys/asoundlib.h>

int snd_pcm_plugin_drain( snd_pcm_t *pcm,
                          int channel );

Arguments:

pcm
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().
channel
The channel; SND_PCM_CHANNEL_CAPTURE or SND_PCM_CHANNEL_PLAYBACK.

Library:

libasound.so

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

Description:

For playback, the snd_pcm_plugin_drain() function blocks until buffered data is fully consumed by the hardware and the stream is stopped. For capture, it stops the stream immediately but preserves the buffered data so that clients can continue to read it until it is fully consumed.

If you use this call to process playback data, there are two considerations:
  • Since this call is a blocking call, if the channel is in the SND_PCM_STATUS_SUSPENDED state, an error occurs if you call this function.
  • If this function is called while in the SND_PCM_STATUS_PAUSED state and during playback data processing, playback is resumed, the channel goes into the SND_PCM_STATUS_RUNNING state immediately, and then ends in the SND_PCM_STATUS_READY state.

    If the channel doesn't start playing (not enough data has been written to start playback), then this call silences the remainder of the buffer to satisfy the playback start requirements. Once the playback requirements are satisfied, playback starts and allows the data to be played out. Once the buffer empties, this call returns successfully.

If the operation is successful (zero is returned), the channel's state is changed to SND_PCM_STATUS_READY, and the channel is stopped.

Returns:

EOK on success, a negative errno upon failure. The errno values are available in the errno.h file.

Errors:

-EAGAIN
The state was SND_PCM_STATUS_SUSPENDED while trying to call this function. This error is also returned if the state was SND_PCM_STATUS_PAUSED, but resuming the playback failed.
-EBADFD
The PCM device state isn't Ready.
-EINTR
The operation was interrupted because of a system signal (such as a timer) or an error was returned asynchronously.
-EINVAL
The state of pcm is invalid, an invalid channel was provided as input, or an invalid state change occurred. You can call snd_pcm_channel_status() to check if the state change was invalid.
-EIO
An invalid channel was specified, or the data wasn't all drained.

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 pcm (snd_pcm_t) is used across multiple threads.

This function is the plugin-aware version of snd_pcm_channel_drain(). It functions exactly the same way. 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.

Page updated: