Struct soundio::Context

pub struct Context<'a> { /* fields omitted */ }

Context represents the libsoundio library context.

It must be created using Context::new() before most operations can be done and you generally will only have one context object per app.

The underlying C struct is destroyed (and the backend is disconnected) when this object is dropped, which means that it must outlive all the Devices it creates. This is enforced via the lifetime system.

Examples

let mut ctx = soundio::Context::new();

Methods

impl<'a> Context<'a>

pub fn new() -> Context<'a>

Create a new libsoundio context.

This panics if libsoundio fails to create the context object. This only happens due to out-of-memory conditions and Rust also panics (aborts actually) under those conditions in the standard library so this behaviour seemed acceptable.

You can create multiple Context instances to connect to multiple backends.

Examples

let mut ctx = soundio::Context::new();

pub fn new_with_callbacks<BackendDisconnectCB, DevicesChangeCB, EventsSignalCB>(
    backend_disconnect_callback: Option<BackendDisconnectCB>,
    devices_change_callback: Option<DevicesChangeCB>,
    events_signal_callback: Option<EventsSignalCB>
) -> Context<'a> where
    BackendDisconnectCB: 'a + FnMut(Error),
    DevicesChangeCB: 'a + FnMut(),
    EventsSignalCB: 'a + FnMut(), 

Create a new libsoundio context with some callbacks specified.

This is the same as Context::new() but allows you to specify the following optional callbacks.

backend_disconnect_callback

This is called when the backend disconnects. For example, when the JACK server shuts down. When this happens, listing devices and opening streams will always fail with Error::BackendDisconnected. This callback is only called during a call to Context::flush_events() or Context::wait_events(). If you do not supply a callback, the default will panic with an error message. This callback is also called when the thread that retrieves device information runs into an unrecoverable condition such as running out of memory.

The possible errors passed to the callback are:

• Error::BackendDisconnected
• Error::NoMem
• Error::SystemResources
• `Error::ErrorOpeningDevice - unexpected problem accessing device information

devices_change_callback

This is called when the list of devices change. It is only called during a call to Context::flush_events() or Context::wait_events()`. The default behaviour is to print "Devices changed" to the console, which you can disable by using an empty callback.

events_signal_callback

This is called from an unknown thread that you should not use to call any soundio functions. You may use this to signal a condition variable to wake up. It is called when Context::wait_events() would be woken up.

Examples

let backend_disconnect_callback = |err| { println!("Backend disconnected: {}", err); };

let mut ctx = soundio::Context::new_with_callbacks(
    Some(backend_disconnect_callback),
    None::<fn()>,
    None::<fn()>,
);

pub fn set_app_name(&mut self, name: &str)

Set the app name. This is shown in JACK and PulseAudio. Any colons are removed. The default is "SoundIo".

This must be called before you connect to a backend.

let mut ctx = soundio::Context::new();
ctx.set_app_name("My App");

pub fn app_name(&self) -> String

Get the app name previously set by set_app_name(). The default is "SoundIo".

let mut ctx = soundio::Context::new();
assert_eq!(ctx.app_name(), "SoundIo");
ctx.set_app_name(":::My App:::");
assert_eq!(ctx.app_name(), "My App");

pub fn connect(&mut self) -> Result<()>

Connect to the default backend, trying them in the order returned by available_backends(). It will fail with Error::Invalid if this instance is already connected to a backend.

Return Values

• soundio::Error::Invalid if you are already connected.
• soundio::Error::NoMem
• soundio::Error::SystemResources
• soundio::Error::NoSuchClient when JACK returns JackNoSuchClient.

Examples

let mut ctx = soundio::Context::new();
match ctx.connect() {
	Ok(()) => println!("Connected to {}", ctx.current_backend()),
	Err(e) => println!("Couldn't connect: {}", e),
}

pub fn connect_backend(&mut self, backend: Backend) -> Result<()>

Connect to the specified backend. It will fail with Error::Invalid if this instance is already connected to a backend.

Return Values

• soundio::Error::Invalid if you are already connected or the backend was invalid.
• soundio::Error::NoMem
• soundio::Error::BackendUnavailable if the backend was not compiled in.
• soundio::Error::SystemResources
• soundio::Error::NoSuchClient when JACK returns JackNoSuchClient.
• soundio::Error::InitAudioBackend if the requested backend is not active.
• soundio::Error::BackendDisconnected if the backend disconnected while connecting. See also bug 103

Examples

let mut ctx = soundio::Context::new();
match ctx.connect_backend(soundio::Backend::Dummy) {
	Ok(()) => println!("Connected to dummy backend"),
	Err(e) => println!("Couldn't connect: {}", e),
}

pub fn disconnect(&mut self)

Disconnect from the current backend. Does nothing if no backend is connected. It is usually not necessary to call this manually; the backend will disconnect automatically when Context is dropped.

Examples

let mut ctx = soundio::Context::new();
match ctx.connect() {
	Ok(()) => println!("Connected to {}", ctx.current_backend()),
	Err(e) => { println!("Couldn't connect: {}", e); return; },
}
ctx.disconnect();

pub fn current_backend(&self) -> Backend

Return the current Backend.

If this Context isn't connected to any backend it returns Backend::None.

Examples

let mut ctx = soundio::Context::new();
match ctx.connect() {
	Ok(()) => println!("Connected to {}", ctx.current_backend()),
	Err(e) => println!("Couldn't connect: {}", e),
}

pub fn available_backends(&self) -> Vec<Backend>

Return a list of available backends on this system.

Examples

let mut ctx = soundio::Context::new();
println!("Available backends: {:?}", ctx.available_backends());

pub fn flush_events(&self)

Atomically update information for all connected devices. Note that calling this function merely flips a pointer; the actual work of collecting device information is done elsewhere. It is performant to call this function many times per second.

When you call this, the following callbacks might be called:

• on_devices_change
• on_backend_disconnect

The callbacks are specified in Context::new_with_callbacks(). This is the only time those callbacks can be called.

This must be called from the same thread as the thread in which you call any function that gets an input or output device, count or index (e.g. Context::default_input_device_index()).

Note that if you do not care about learning about updated devices, you can call this function only once ever and never call Context::wait_events().

pub fn wait_events(&self)

This function calls Context::flush_events() then blocks until another event is ready or you call wakeup. Be ready for spurious wakeups.

pub fn wakeup(&self)

Wake up any other threads currently blocking in Context::wait_events().

In order to enable this functionality, Context implements the Send and Sync traits despite the fact that not all functions can be called from all threads. Be careful.

pub fn force_device_scan(&self)

If necessary you can manually trigger a device rescan. Normally you will not ever have to call this function, as libsoundio listens to system events for device changes and responds to them by rescanning devices and preparing the new device information for you to be atomically replaced when you call Context::flush_events(). However you might run into cases where you want to force trigger a device rescan, for example if an ALSA device has a probe error.

After you call this you still have to use Context::flush_events() or Context::wait_events() and then wait for the devices_change_callback to be called.

This can be called from any thread context except for the read or write callbacks.

pub fn input_device(&self, index: usize) -> Result<Device>

Use this function to retrieve an input device given its index. Before getting devices you must call Context::flush_events() at least once, otherwise this will return an error. It will also return an error if there is a probe error while opening the device or the index is out of bounds (use Context::input_device_count() to learn) how many input devices there are.

It is probably more convenient to use the Context::input_devices() function instead of this one unless you have some very specific requirements.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
for i in 0..ctx.input_device_count() {
    let dev = ctx.input_device(i).expect("Error opening device");
    println!("Device {} is called {}", i, dev.name());
}

pub fn output_device(&self, index: usize) -> Result<Device>

Use this function to retrieve an output device given its index. Before getting devices you must call Context::flush_events() at least once, otherwise this will return an error. It will also return an error if there is a probe error while opening the device or the index is out of bounds (use Context::output_device_count() to learn) how many output devices there are.

It is probably more convenient to use the Context::output_devices() function instead of this one unless you have some very specific requirements.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
for i in 0..ctx.output_device_count() {
    let dev = ctx.output_device(i).expect("Error opening device");
    println!("Device {} is called {}", i, dev.name());
}

pub fn input_device_count(&self) -> usize

Get the number of input devices in this machine. You must call Context::flush_events() at least once before calling this function otherwise it will panic!

pub fn output_device_count(&self) -> usize

Get the number of output devices in this machine. You must call Context::flush_events() at least once before calling this function otherwise it will panic!

pub fn default_input_device_index(&self) -> Option<usize>

Returns the index of the default input device. You must call Context::flush_events() at least once before calling this function. If there are no input devices, or you never called flush_events() it returns None

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let default_input = ctx.default_input_device_index();
for i in 0..ctx.input_device_count() {
    let dev = ctx.input_device(i).expect("Error opening device");
    println!("Device {} is called {}", i, dev.name());
    if Some(i) == default_input {
        println!("And it's the default!");
    }
}

pub fn default_output_device_index(&self) -> Option<usize>

Returns the index of the default output device. You must call Context::flush_events() at least once before calling this function. If there are no output devices, or you never called flush_events() it returns None

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let default_output = ctx.default_output_device_index();
for i in 0..ctx.output_device_count() {
    let dev = ctx.output_device(i).expect("Error opening device");
    println!("Device {} is called {}", i, dev.name());
    if Some(i) == default_output {
        println!("And it's the default!");
    }
}

pub fn input_devices(&self) -> Result<Vec<Device>>

Get all the input devices as a vector. You must call Context::flush_events() at least once before calling this function. If you don't it will panic.

It returns an error if there is an error opening any of the devices.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let devs = ctx.input_devices().expect("Error getting devices");
for dev in devs {
    println!("Device {} ", dev.name());
}

pub fn output_devices(&self) -> Result<Vec<Device>>

Get all the output devices as a vector. You must call Context::flush_events() at least once before calling this function. If you don't it will panic.

It returns an error if there is an error opening any of the devices.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let devs = ctx.output_devices().expect("Error getting devices");
for dev in devs {
    println!("Device {} ", dev.name());
}

pub fn default_input_device(&self) -> Result<Device>

Get the default input device. You must call Context::flush_events() at least once before calling this function. If you don't it will panic.

If there are no devices it returns Error::NoSuchDevice. If there was an error opening the device it returns that error.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let dev = ctx.default_input_device().expect("No default device");
println!("The default input device is {}", dev.name());

pub fn default_output_device(&self) -> Result<Device>

Get the default output device. You must call Context::flush_events() at least once before calling this function. If you don't it will panic.

If there are no devices it returns Error::NoSuchDevice. If there was an error opening the device it returns that error.

Examples

let mut ctx = soundio::Context::new();
ctx.connect_backend(soundio::Backend::Dummy).expect("Couldn't connect to backend");
ctx.flush_events();
let dev = ctx.default_output_device().expect("No default device");
println!("The default output device is {}", dev.name());

Trait Implementations

impl<'a> Drop for Context<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Send for Context<'a>

impl<'a> Sync for Context<'a>