carb::audio::IAudioDevice

struct 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.

Param dir: [in] the audio direction to get the device count for.
Return: the total number of connected audio devices of the requested type.
Return: 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.

Param dir: [in] The audio direction of the device.
Param 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().
Param caps: [inout] The capabilities of this device. caps->thisSize must be set to sizeof(*caps) before passing it.
Return: AudioResult::eOk if the device info was successfully retrieved.
Return: AudioResult::eInvalidParameter if the thisSize value is not properly initialized in caps or caps is nullptr.
Return: AudioResult::eOutOfRange if the requested device index is out of range of the system’s current device count.
Return: AudioResult::eNotSupported if a device is found but it requires an unsupported sample format.
Return: an AudioResult::* error code if another failure occurred.

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

Create a device notification object.

Param type: [in] The device type to fire the callback for.
Param callback: [in] The callback that will be fired when a device change occurs. This must not be nullptr.
Param context: [in] The object passed to the parameter of callback.
Return: A valid device notifier object if successful. This must be destroyed with destroyNotifier() when device notifications are no longer needed.
Return: nullptr if an error occurred.

void (*destroyNotifier)(DeviceChangeNotifier *notifier)

Destroy a device notification object.

Param 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.

Return: The device backend in use.

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

Retrieve a minimal set of device properties.

Param dir: [in] The audio direction of the device.
Param 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().
Param 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.
Retval AudioResult::eOk: on success.
Retval AudioResult::eInvalidParameter: if caps had an invalid thisSize member or was nullptr.
Retval 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.

Param dir: [in] The audio direction of the device.
Param guid: [in] The guid of the device to retrieve the description for.
Param caps: [inout] The capabilities of this device. caps->thisSize must be set to sizeof(*caps) before passing it.
Return: AudioResult::eOk if the device info was successfully retrieved.
Return: AudioResult::eInvalidParameter if the thisSize value is not properly initialized in caps, caps is nullptr or guid is nullptr.
Return: AudioResult::eOutOfRange if guid did not correspond to a device.
Return: AudioResult::eNotSupported if a device is found but it requires an unsupported sample format.
Return: 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.

Param dir: [in] The audio direction of the device.
Param guid: [in] The guid of the device to retrieve the description for.
Param 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.
Retval AudioResult::eOk: on success.
Retval AudioResult::eInvalidParameter: if the thisSize value is not properly initialized in caps, caps is nullptr or guid is nullptr.
Retval AudioResult::eOutOfRange: if guid did not correspond to a device.