carb::audio::IAudioDevice¶

struct carb::audio::IAudioDevice¶

An interface to provide simple audio device enumeration functionality, as well as device change notifications.

This is able to enumerate all audio devices attached to the system at any given point and collect the information for each device. This is able to collect information and provide notifications for both playback and capture devices.

Public Members

size_t (*getDeviceCount)(DeviceType dir)¶

retrieves the total number of devices attached to the system of a requested type.

Parameters: dir – [in] the audio direction to get the device count for.
Returns: the total number of connected audio devices of the requested type.
Returns: 0 if no audio devices are connected to the system.

AudioResult (*getDeviceCaps)(DeviceType dir, size_t index, carb::audio::DeviceCaps *caps)¶

Retrieve the capabilities of a device.

Parameters

dir – [in] The audio direction of the device.
index – [in] The index of the device to retrieve the description for. This should be between 0 and one less than the most recent return value of getDeviceCount().
caps – [inout] The capabilities of this device. caps->thisSize must be set to sizeof(*caps) before passing it.

Returns

AudioResult::eOk if the device info was successfully retrieved.

Returns

AudioResult::eInvalidParameter if the thisSize value is not properly initialized in caps or caps is nullptr.

Returns

AudioResult::eOutOfRange if the requested device index is out of range of the system’s current device count.

Returns

AudioResult::eNotSupported if a device is found but it requires an unsupported sample format.

Returns

an AudioResult::* error code if another failure occurred.

DeviceChangeNotifier *(*createNotifier)(DeviceType type, DeviceNotifyCallback callback, void *context)¶

Create a device notification object.

Parameters

type – [in] The device type to fire the callback for.
callback – [in] The callback that will be fired when a device change occurs. This must not be nullptr.
context – [in] The object passed to the parameter of callback.

Returns

A valid device notifier object if successful. This must be destroyed with destroyNotifier() when device notifications are no longer needed.

Returns

nullptr if an error occurred.

void (*destroyNotifier)(DeviceChangeNotifier *notifier)¶

Destroy a device notification object.

Parameters: notifier – [in] The notification object to free. Device notification callbacks for this object will no longer occur.

DeviceBackend (*getBackend)()¶

Query the device backend that’s currently in use.

Note

This returned value is cached internally, so these calls are inexpensive.

Note

The value this returns will not change until carb.audio reloads.

Returns: The device backend in use.

AudioResult (*getDeviceName)(DeviceType type, size_t index, DeviceCaps *caps)¶

Retrieve a minimal set of device properties.

Parameters

dir – [in] The audio direction of the device.
index – [in] The index of the device to retrieve the description for. This should be between 0 and one less than the most recent return value of getDeviceCount().
caps – [inout] The basic properties of this device. DeviceCaps::name and DeviceCaps::guid will be written to this. DeviceCaps::flags will have fDeviceFlagDefault set if this is the default device, but no other flags will be set. All other members of this struct will be set to default values. caps->thisSize must be set to sizeof(*caps) before passing it.

Returns

AudioResult::eOk on success.

Returns

AudioResult::eInvalidParameter if caps had an invalid thisSize member or was nullptr.

Returns

AudioResult::eOutOfRange if index was past the end of the device list.

AudioResult (*getDeviceCapsByGuid)(DeviceType dir, const carb::extras::Guid *guid, carb::audio::DeviceCaps *caps)¶

Retrieve the capabilities of a device.

Parameters

dir – [in] The audio direction of the device.
guid – [in] The guid of the device to retrieve the description for.
caps – [inout] The capabilities of this device. caps->thisSize must be set to sizeof(*caps) before passing it.

Returns

AudioResult::eOk if the device info was successfully retrieved.

Returns

AudioResult::eInvalidParameter if the thisSize value is not properly initialized in caps, caps is nullptr or guid is nullptr.

Returns

AudioResult::eOutOfRange if guid did not correspond to a device.

Returns

AudioResult::eNotSupported if a device is found but it requires an unsupported sample format.

Returns

an AudioResult::* error code if another failure occurred.

AudioResult (*getDeviceNameByGuid)(DeviceType dir, const carb::extras::Guid *guid, carb::audio::DeviceCaps *caps)¶

Retrieve a minimal set of device properties.

Parameters

dir – [in] The audio direction of the device.
guid – [in] The guid of the device to retrieve the description for.
caps – [inout] The basic properties of this device. DeviceCaps::name and DeviceCaps::guid will be written to this. DeviceCaps::flags will have fDeviceFlagDefault set if this is the default device, but no other flags will be set. All other members of this struct will be set to default values. caps->thisSize must be set to sizeof(*caps) before passing it.

Returns

AudioResult::eOk on success.

Returns

AudioResult::eInvalidParameter if the thisSize value is not properly initialized in caps, caps is nullptr or guid is nullptr.

Returns

AudioResult::eOutOfRange if guid did not correspond to a device.