document possible errors

This commit is contained in:
Andrew Kelley 2015-08-26 15:17:51 -07:00
parent c96405a091
commit a0562af122
6 changed files with 155 additions and 35 deletions

View file

@ -8,8 +8,6 @@ This library is an abstraction; however in the delicate balance between
performance and power, and API convenience, the scale is tipped closer to performance and power, and API convenience, the scale is tipped closer to
the former. Features that only exist in some sound backends are exposed. the former. Features that only exist in some sound backends are exposed.
[API Documentation](http://libsound.io/doc)
**This project is a work-in-progress.** **This project is a work-in-progress.**
## Features and Limitations ## Features and Limitations
@ -295,22 +293,13 @@ Then look at `html/index.html` in a browser.
0. Create a test for input stream overflow handling. 0. Create a test for input stream overflow handling.
0. Allow calling functions from outside the callbacks as long as they first 0. Allow calling functions from outside the callbacks as long as they first
call lock and then unlock when done. call lock and then unlock when done.
0. add len arguments to APIs that have char *
- replace strdup with `soundio_str_dupe`
0. write detailed docs on buffer underflows explaining when they occur, what state 0. write detailed docs on buffer underflows explaining when they occur, what state
changes are related to them, and how to recover from them. changes are related to them, and how to recover from them.
0. Consider testing on FreeBSD
0. In ALSA do we need to wake up the poll when destroying the in or out stream?
0. Detect PulseAudio server going offline and emit `on_backend_disconnect`. 0. Detect PulseAudio server going offline and emit `on_backend_disconnect`.
0. Custom allocator support
- default allocator mlock memory
0. Support for stream icon. 0. Support for stream icon.
- PulseAudio: XDG icon name - PulseAudio: XDG icon name
- WASAPI: path to .exe, .dll, or .ico - WASAPI: path to .exe, .dll, or .ico
- CoreAudio: CFURLRef image file - CoreAudio: CFURLRef image file
0. clean up API and improve documentation
- make sure every function which can return an error documents which errors
it can return
## Planned Uses for libsoundio ## Planned Uses for libsoundio

View file

@ -1665,7 +1665,8 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator. # recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED = PREDEFINED = SOUNDIO_EXTERN_C= \
SOUNDIO_EXPORT= \
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The # tag can be used to specify a list of macro names that should be expanded. The

View file

@ -11,6 +11,7 @@
#include "config.h" #include "config.h"
#include <stdbool.h> #include <stdbool.h>
/// \cond
#ifdef __cplusplus #ifdef __cplusplus
#define SOUNDIO_EXTERN_C extern "C" #define SOUNDIO_EXTERN_C extern "C"
#else #else
@ -26,6 +27,7 @@
#else #else
#define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default"))) #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default")))
#endif #endif
/// \endcond
/** \mainpage /** \mainpage
* *
@ -56,20 +58,34 @@
/// See also ::soundio_strerror /// See also ::soundio_strerror
enum SoundIoError { enum SoundIoError {
SoundIoErrorNone, SoundIoErrorNone,
/// Out of memory.
SoundIoErrorNoMem, SoundIoErrorNoMem,
/// The backend does not appear to be active or running.
SoundIoErrorInitAudioBackend, SoundIoErrorInitAudioBackend,
/// A system resource other than memory was not available.
SoundIoErrorSystemResources, SoundIoErrorSystemResources,
/// Attempted to open a device and failed.
SoundIoErrorOpeningDevice, SoundIoErrorOpeningDevice,
SoundIoErrorNoSuchDevice, SoundIoErrorNoSuchDevice,
/// The programmer did not comply with the API.
SoundIoErrorInvalid, SoundIoErrorInvalid,
/// libsoundio was compiled without support for that backend.
SoundIoErrorBackendUnavailable, SoundIoErrorBackendUnavailable,
/// An open stream had an error that can only be recovered from by
/// destroying the stream and creating it again.
SoundIoErrorStreaming, SoundIoErrorStreaming,
/// Attempted to use a device with parameters it cannot support.
SoundIoErrorIncompatibleDevice, SoundIoErrorIncompatibleDevice,
/// When JACK returns `JackNoSuchClient`
SoundIoErrorNoSuchClient, SoundIoErrorNoSuchClient,
/// Attempted to use parameters that the backend cannot support.
SoundIoErrorIncompatibleBackend, SoundIoErrorIncompatibleBackend,
/// Backend server shutdown or became inactive.
SoundIoErrorBackendDisconnected, SoundIoErrorBackendDisconnected,
SoundIoErrorInterrupted, SoundIoErrorInterrupted,
/// Buffer underrun occurred.
SoundIoErrorUnderflow, SoundIoErrorUnderflow,
/// Unable to convert to or from UTF-8 to the native string format.
SoundIoErrorEncodingString, SoundIoErrorEncodingString,
}; };
@ -203,6 +219,8 @@ enum SoundIoDeviceAim {
SoundIoDeviceAimOutput, ///< playback SoundIoDeviceAimOutput, ///< playback
}; };
/// For your convenience, Native Endian and Foreign Endian constants are defined
/// which point to the respective SoundIoFormat values.
enum SoundIoFormat { enum SoundIoFormat {
SoundIoFormatInvalid, SoundIoFormatInvalid,
SoundIoFormatS8, ///< Signed 8 bit SoundIoFormatS8, ///< Signed 8 bit
@ -225,9 +243,6 @@ enum SoundIoFormat {
SoundIoFormatFloat64BE, ///< Float 64 bit Big Endian, Range -1.0 to 1.0 SoundIoFormatFloat64BE, ///< Float 64 bit Big Endian, Range -1.0 to 1.0
}; };
// For your convenience, Native Endian and Foreign Endian constants are defined
// which point to the respective SoundIoFormat values.
#if defined(SOUNDIO_OS_BIG_ENDIAN) #if defined(SOUNDIO_OS_BIG_ENDIAN)
#define SoundIoFormatS16NE SoundIoFormatS16BE #define SoundIoFormatS16NE SoundIoFormatS16BE
#define SoundIoFormatU16NE SoundIoFormatU16BE #define SoundIoFormatU16NE SoundIoFormatU16BE
@ -446,6 +461,10 @@ struct SoundIoDevice {
/// fields of the device will be populated. If there is an error code here /// fields of the device will be populated. If there is an error code here
/// then information about formats, sample rates, and channel layouts might /// then information about formats, sample rates, and channel layouts might
/// be missing. /// be missing.
///
/// Possible errors:
/// * #SoundIoErrorOpeningDevice
/// * #SoundIoErrorNoMem
int probe_error; int probe_error;
}; };
@ -454,7 +473,7 @@ struct SoundIoOutStream {
/// Populated automatically when you call ::soundio_outstream_create. /// Populated automatically when you call ::soundio_outstream_create.
struct SoundIoDevice *device; struct SoundIoDevice *device;
/// Defaults to SoundIoFormatFloat32NE, followed by the first one supported. /// Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.
enum SoundIoFormat format; enum SoundIoFormat format;
/// Sample rate is the number of frames per second. /// Sample rate is the number of frames per second.
@ -605,18 +624,31 @@ struct SoundIoInStream {
// Main Context // Main Context
/// Create a SoundIo context. You may create multiple instances of this to /// Create a SoundIo context. You may create multiple instances of this to
/// connect to multiple backends. /// connect to multiple backends. Sets all fields to defaults.
/// Returns `NULL` if and only if memory could not be allocated.
/// See also ::soundio_destroy /// See also ::soundio_destroy
SOUNDIO_EXPORT struct SoundIo *soundio_create(void); SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio); SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
/// This is a convenience function you could implement yourself if you wanted /// Tries ::soundio_connect_backend on all available backends in order.
/// to. It tries ::soundio_connect_backend on all available backends in order. /// Possible errors:
/// * #SoundIoErrorInvalid - already connected
/// * #SoundIoErrorNoMem
/// * #SoundIoErrorSystemResources
/// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient`
/// See also ::soundio_disconnect /// See also ::soundio_disconnect
SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio); SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
/// Instead of calling ::soundio_connect you may call this function to try a /// Instead of calling ::soundio_connect you may call this function to try a
/// specific backend. /// specific backend.
/// Possible errors:
/// * #SoundIoErrorInvalid - already connected or invalid backend parameter
/// * #SoundIoErrorNoMem
/// * #SoundIoErrorBackendUnavailable - backend was not compiled in
/// * #SoundIoErrorSystemResources
/// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient`
/// * #SoundIoErrorInitAudioBackend - requested `backend` is not active
/// * #SoundIoErrorBackendDisconnected - backend disconnected while connecting
/// See also ::soundio_disconnect /// See also ::soundio_disconnect
SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend); SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio); SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
@ -797,7 +829,9 @@ SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *devi
// Output Streams // Output Streams
/// Allocates memory and sets defaults. Next you should fill out the struct fields /// Allocates memory and sets defaults. Next you should fill out the struct fields
/// and then call ::soundio_outstream_open. /// and then call ::soundio_outstream_open. Sets all fields to defaults.
/// Returns `NULL` if and only if memory could not be allocated.
/// See also ::soundio_outstream_destroy
SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device); SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
/// You may not call this function from the SoundIoOutStream::write_callback thread context. /// You may not call this function from the SoundIoOutStream::write_callback thread context.
SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream); SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
@ -807,15 +841,37 @@ SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream
/// The next thing to do is call ::soundio_instream_start. /// The next thing to do is call ::soundio_instream_start.
/// If this function returns an error, the outstream is in an invalid state and /// If this function returns an error, the outstream is in an invalid state and
/// you must call ::soundio_outstream_destroy on it. /// you must call ::soundio_outstream_destroy on it.
///
/// Possible errors:
/// * #SoundIoErrorInvalid
/// * SoundIoDevice::aim is not #SoundIoDeviceAimOutput
/// * SoundIoOutStream::format is not valid
/// * SoundIoOutStream::channel_count is greater than #SOUNDIO_MAX_CHANNELS
/// * #SoundIoErrorNoMem
/// * #SoundIoErrorOpeningDevice
/// * #SoundIoErrorBackendDisconnected
/// * #SoundIoErrorSystemResources
/// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient`
/// * #SoundIoErrorOpeningDevice
/// * #SoundIoErrorIncompatibleBackend - SoundIoOutStream::channel_count is
/// greater than the number of channels the backend can handle.
/// * #SoundIoErrorIncompatibleDevice - stream parameters requested are not
/// compatible with the chosen device.
SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream); SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
/// After you call this function, SoundIoOutStream::write_callback will be called. /// After you call this function, SoundIoOutStream::write_callback will be called.
///
/// Possible errors:
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorNoMem
/// * #SoundIoErrorSystemResources
/// * #SoundIoErrorBackendDisconnected
SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream); SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
/// Call this function when you are ready to begin writing to the device buffer. /// Call this function when you are ready to begin writing to the device buffer.
/// * `outstream` - (in) The output stream you want to write to. /// * `outstream` - (in) The output stream you want to write to.
/// * `areas` - (out) The memory addresses you can write data to. It is OK to /// * `areas` - (out) The memory addresses you can write data to, one per
/// modify the pointers if that helps you iterate. /// channel. It is OK to modify the pointers if that helps you iterate.
/// * `frame_count` - (in/out) Provide the number of frames you want to write. /// * `frame_count` - (in/out) Provide the number of frames you want to write.
/// Returned will be the number of frames you can actually write, which is /// Returned will be the number of frames you can actually write, which is
/// also the number of frames that will be written when you call /// also the number of frames that will be written when you call
@ -827,19 +883,40 @@ SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
/// You must call this function only from the SoundIoOutStream::write_callback thread context. /// You must call this function only from the SoundIoOutStream::write_callback thread context.
/// After calling this function, write data to `areas` and then call /// After calling this function, write data to `areas` and then call
/// ::soundio_outstream_end_write. /// ::soundio_outstream_end_write.
/// If you call this function with `frame_count` less than the `frame_count_min`
/// parameter from SoundIoOutStream::write_callback it returns SoundIoErrorInvalid.
/// If this function returns an error, do not call ::soundio_outstream_end_write. /// If this function returns an error, do not call ::soundio_outstream_end_write.
///
/// Possible errors:
/// * #SoundIoErrorInvalid
/// * `*frame_count` <= 0
/// * `*frame_count` < `frame_count_min` or `*frame_count` > `frame_count_max`
/// * function called too many times without respecting `frame_count_max`
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorUnderflow - an underflow caused this call to fail. You might
/// also get a SoundIoOutStream::underflow_callback, and you might not get
/// this error code when an underflow occurs. Unlike #SoundIoErrorStreaming,
/// the outstream is still in a valid state and streaming can continue.
/// * #SoundIoErrorIncompatibleDevice - in rare cases it might just now
/// be discovered that the device uses non-byte-aligned access, in which
/// case this error code is returned.
SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream, SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
struct SoundIoChannelArea **areas, int *frame_count); struct SoundIoChannelArea **areas, int *frame_count);
/// Commits the write that you began with ::soundio_outstream_begin_write. /// Commits the write that you began with ::soundio_outstream_begin_write.
/// You must call this function only from the SoundIoOutStream::write_callback thread context. /// You must call this function only from the SoundIoOutStream::write_callback thread context.
/// This function might return #SoundIoErrorUnderflow but don't count on it. ///
/// Possible errors:
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorUnderflow - an underflow caused this call to fail. You might
/// also get a SoundIoOutStream::underflow_callback, and you might not get
/// this error code when an underflow occurs. Unlike #SoundIoErrorStreaming,
/// the outstream is still in a valid state and streaming can continue.
SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream); SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
/// Clears the output stream buffer. /// Clears the output stream buffer.
/// You must call this function only from the SoundIoOutStream::write_callback thread context. /// You must call this function only from the SoundIoOutStream::write_callback thread context.
/// Possible errors:
///
/// * #SoundIoErrorStreaming
SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream); SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
/// If the underyling device supports pausing, this pauses the stream and /// If the underyling device supports pausing, this pauses the stream and
@ -848,6 +925,11 @@ SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outst
/// You must call this function only from the SoundIoOutStream::write_callback thread context. /// You must call this function only from the SoundIoOutStream::write_callback thread context.
/// Pausing when already paused or unpausing when already unpaused has no /// Pausing when already paused or unpausing when already unpaused has no
/// effect and always returns SoundIoErrorNone. /// effect and always returns SoundIoErrorNone.
///
/// Possible errors:
/// * #SoundIoErrorBackendDisconnected
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorIncompatibleDevice - device does not support pausing/unpausing
SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause); SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
@ -855,7 +937,9 @@ SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, b
// Input Streams // Input Streams
/// Allocates memory and sets defaults. Next you should fill out the struct fields /// Allocates memory and sets defaults. Next you should fill out the struct fields
/// and then call ::soundio_instream_open. /// and then call ::soundio_instream_open. Sets all fields to defaults.
/// Returns `NULL` if and only if memory could not be allocated.
/// See also ::soundio_instream_destroy
SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device); SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
/// You may not call this function from SoundIoInStream::read_callback. /// You may not call this function from SoundIoInStream::read_callback.
SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream); SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
@ -865,9 +949,28 @@ SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
/// The next thing to do is call ::soundio_instream_start. /// The next thing to do is call ::soundio_instream_start.
/// If this function returns an error, the instream is in an invalid state and /// If this function returns an error, the instream is in an invalid state and
/// you must call ::soundio_instream_destroy on it. /// you must call ::soundio_instream_destroy on it.
///
/// Possible errors:
/// * #SoundIoErrorInvalid
/// * device aim is not #SoundIoDeviceAimInput
/// * format is not valid
/// * requested layout channel count > #SOUNDIO_MAX_CHANNELS
/// * #SoundIoErrorOpeningDevice
/// * #SoundIoErrorNoMem
/// * #SoundIoErrorBackendDisconnected
/// * #SoundIoErrorSystemResources
/// * #SoundIoErrorNoSuchClient
/// * #SoundIoErrorIncompatibleBackend
/// * #SoundIoErrorIncompatibleDevice
SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream); SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
/// After you call this function, SoundIoInStream::read_callback will be called. /// After you call this function, SoundIoInStream::read_callback will be called.
///
/// Possible errors:
/// * #SoundIoErrorBackendDisconnected
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorOpeningDevice
/// * #SoundIoErrorSystemResources
SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream); SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
/// Call this function when you are ready to begin reading from the device /// Call this function when you are ready to begin reading from the device
@ -881,7 +984,7 @@ SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
/// returns the number of frames you can actually read. The returned value /// returns the number of frames you can actually read. The returned value
/// will always be less than or equal to the provided value. If the provided /// will always be less than or equal to the provided value. If the provided
/// value is less than `frame_count_min` from SoundIoInStream::read_callback this function /// value is less than `frame_count_min` from SoundIoInStream::read_callback this function
/// returns with SoundIoErrorInvalid. /// returns with #SoundIoErrorInvalid.
/// It is your responsibility to call this function no more and no fewer than the /// It is your responsibility to call this function no more and no fewer than the
/// correct number of times according to the `frame_count_min` and /// correct number of times according to the `frame_count_min` and
/// `frame_count_max` criteria from SoundIoInStream::read_callback. /// `frame_count_max` criteria from SoundIoInStream::read_callback.
@ -891,6 +994,14 @@ SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
/// and move the read index forward. ::soundio_instream_end_read should not be /// and move the read index forward. ::soundio_instream_end_read should not be
/// called if the buffer is empty (`frame_count` == 0), but it should be called /// called if the buffer is empty (`frame_count` == 0), but it should be called
/// if there is a hole. /// if there is a hole.
///
/// Possible errors:
/// * #SoundIoErrorInvalid
/// * `*frame_count` < `frame_count_min` or `*frame_count` > `frame_count_max`
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorIncompatibleDevice - in rare cases it might just now
/// be discovered that the device uses non-byte-aligned access, in which
/// case this error code is returned.
SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream, SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
struct SoundIoChannelArea **areas, int *frame_count); struct SoundIoChannelArea **areas, int *frame_count);
/// This will drop all of the frames from when you called /// This will drop all of the frames from when you called
@ -898,6 +1009,9 @@ SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
/// You must call this function only from the SoundIoInStream::read_callback thread context. /// You must call this function only from the SoundIoInStream::read_callback thread context.
/// You must call this function only after a successful call to /// You must call this function only after a successful call to
/// ::soundio_instream_begin_read. /// ::soundio_instream_begin_read.
///
/// Possible errors:
/// * #SoundIoErrorStreaming
SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream); SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
/// If the underyling device supports pausing, this pauses the stream and /// If the underyling device supports pausing, this pauses the stream and
@ -906,6 +1020,11 @@ SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
/// You must call this function only from the SoundIoInStream::read_callback thread context. /// You must call this function only from the SoundIoInStream::read_callback thread context.
/// Pausing when already paused or unpausing when already unpaused has no /// Pausing when already paused or unpausing when already unpaused has no
/// effect and always returns SoundIoErrorNone. /// effect and always returns SoundIoErrorNone.
///
/// Possible errors:
/// * #SoundIoErrorBackendDisconnected
/// * #SoundIoErrorStreaming
/// * #SoundIoErrorIncompatibleDevice - device does not support pausing/unpausing
SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause); SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
@ -913,6 +1032,7 @@ SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool
struct SoundIoRingBuffer; struct SoundIoRingBuffer;
/// `requested_capacity` in bytes. /// `requested_capacity` in bytes.
/// See also ::soundio_ring_buffer_destroy /// See also ::soundio_ring_buffer_destroy
/// Returns `NULL` if and only if memory could not be allocated.
SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity); SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer); SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);

View file

@ -207,7 +207,8 @@ static int outstream_begin_write_dummy(SoundIoPrivate *si,
SoundIoOutStream *outstream = &os->pub; SoundIoOutStream *outstream = &os->pub;
SoundIoOutStreamDummy *osd = &os->backend_data.dummy; SoundIoOutStreamDummy *osd = &os->backend_data.dummy;
assert(*frame_count <= osd->frames_left); if (*frame_count > osd->frames_left)
return SoundIoErrorInvalid;
char *write_ptr = soundio_ring_buffer_write_ptr(&osd->ring_buffer); char *write_ptr = soundio_ring_buffer_write_ptr(&osd->ring_buffer);
for (int ch = 0; ch < outstream->layout.channel_count; ch += 1) { for (int ch = 0; ch < outstream->layout.channel_count; ch += 1) {

View file

@ -667,8 +667,6 @@ static int outstream_open_pa(SoundIoPrivate *si, SoundIoOutStreamPrivate *os) {
SoundIoOutStreamPulseAudio *ospa = &os->backend_data.pulseaudio; SoundIoOutStreamPulseAudio *ospa = &os->backend_data.pulseaudio;
SoundIoOutStream *outstream = &os->pub; SoundIoOutStream *outstream = &os->pub;
if (outstream->layout.channel_count > SOUNDIO_MAX_CHANNELS)
return SoundIoErrorInvalid;
if ((unsigned)outstream->layout.channel_count > PA_CHANNELS_MAX) if ((unsigned)outstream->layout.channel_count > PA_CHANNELS_MAX)
return SoundIoErrorIncompatibleBackend; return SoundIoErrorIncompatibleBackend;
@ -882,8 +880,6 @@ static int instream_open_pa(SoundIoPrivate *si, SoundIoInStreamPrivate *is) {
SoundIoInStreamPulseAudio *ispa = &is->backend_data.pulseaudio; SoundIoInStreamPulseAudio *ispa = &is->backend_data.pulseaudio;
SoundIoInStream *instream = &is->pub; SoundIoInStream *instream = &is->pub;
if (instream->layout.channel_count > SOUNDIO_MAX_CHANNELS)
return SoundIoErrorInvalid;
if ((unsigned)instream->layout.channel_count > PA_CHANNELS_MAX) if ((unsigned)instream->layout.channel_count > PA_CHANNELS_MAX)
return SoundIoErrorIncompatibleBackend; return SoundIoErrorIncompatibleBackend;
if (!instream->name) if (!instream->name)

View file

@ -245,7 +245,6 @@ void soundio_disconnect(struct SoundIo *soundio) {
soundio->current_backend = SoundIoBackendNone; soundio->current_backend = SoundIoBackendNone;
soundio_destroy_devices_info(si->safe_devices_info); soundio_destroy_devices_info(si->safe_devices_info);
si->safe_devices_info = nullptr; si->safe_devices_info = nullptr;
si->destroy = nullptr; si->destroy = nullptr;
@ -424,7 +423,8 @@ int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
SoundIo *soundio = outstream->device->soundio; SoundIo *soundio = outstream->device->soundio;
SoundIoPrivate *si = (SoundIoPrivate *)soundio; SoundIoPrivate *si = (SoundIoPrivate *)soundio;
SoundIoOutStreamPrivate *os = (SoundIoOutStreamPrivate *)outstream; SoundIoOutStreamPrivate *os = (SoundIoOutStreamPrivate *)outstream;
assert(*frame_count > 0); if (*frame_count <= 0)
return SoundIoErrorInvalid;
return si->outstream_begin_write(si, os, areas, frame_count); return si->outstream_begin_write(si, os, areas, frame_count);
} }
@ -468,6 +468,9 @@ int soundio_outstream_open(struct SoundIoOutStream *outstream) {
if (device->probe_error) if (device->probe_error)
return device->probe_error; return device->probe_error;
if (outstream->layout.channel_count > SOUNDIO_MAX_CHANNELS)
return SoundIoErrorInvalid;
if (outstream->format == SoundIoFormatInvalid) { if (outstream->format == SoundIoFormatInvalid) {
outstream->format = soundio_device_supports_format(device, SoundIoFormatFloat32NE) ? outstream->format = soundio_device_supports_format(device, SoundIoFormatFloat32NE) ?
SoundIoFormatFloat32NE : device->formats[0]; SoundIoFormatFloat32NE : device->formats[0];
@ -522,6 +525,13 @@ int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause) {
return si->outstream_pause(si, os, pause); return si->outstream_pause(si, os, pause);
} }
int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream) {
SoundIo *soundio = outstream->device->soundio;
SoundIoPrivate *si = (SoundIoPrivate *)soundio;
SoundIoOutStreamPrivate *os = (SoundIoOutStreamPrivate *)outstream;
return si->outstream_clear_buffer(si, os);
}
static void default_instream_error_callback(struct SoundIoInStream *is, int err) { static void default_instream_error_callback(struct SoundIoInStream *is, int err) {
soundio_panic("libsoundio: %s", soundio_strerror(err)); soundio_panic("libsoundio: %s", soundio_strerror(err));
} }
@ -551,6 +561,9 @@ int soundio_instream_open(struct SoundIoInStream *instream) {
if (instream->format <= SoundIoFormatInvalid) if (instream->format <= SoundIoFormatInvalid)
return SoundIoErrorInvalid; return SoundIoErrorInvalid;
if (instream->layout.channel_count > SOUNDIO_MAX_CHANNELS)
return SoundIoErrorInvalid;
if (device->probe_error) if (device->probe_error)
return device->probe_error; return device->probe_error;