Device Management Service
Once the SDK is instantiated, applications have access to the device management service. Currently, this allows managing audio input and output devices. This service provides the ability to:
Get the available audio devices
Set the preferred input and output devices
Check the currently set input and output device
Receive events about audio devices that have been added, removed, or changed as well as device failures
Device Management Interface
#include <dolbyio/comms/device_management.h>
-
class device_management
Provides methods of the Device Management Service.
- Attention
The device_management interface contains methods that return async_result. Each function that returns async_result is asynchronous and the operation is executed during the SDK event loop. The caller can block the calling thread until the operation completes using the wait helper. The caller can also chain consecutive operations, which are dependent on the completion of this method, using the async_result::then calls. Each async_result chain needs to be terminated with an async_result::on_error.
Note
The Device Management service is not intended to be used when media_io service is being used as the Media IO Service implies using external media sources..
Public Functions
-
virtual async_result<void> set_default_audio_device_policy(default_audio_device_policy policy) = 0
Sets the default audio device selection policy on Windows. Must be called before joining a conference for the policy to be used. By default the device will opened as a communications device.
- Parameters:
policy – The default audio device selection policy.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> set_preferred_input_audio_device(const audio_device &device) = 0
Sets the preferred input audio device.
- Parameters:
device – Structure containing information about the desired input device.
- Returns:
The result object producing the operation status asynchronously.
// Wait device to be set wait(sdk->device_management().set_preferred_input_audio_device(device)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().set_preferred_input_audio_device(device) .then([]() { // device is now set }) .on_error([](auto&& e) { // Handle exception });
-
virtual async_result<void> set_preferred_output_audio_device(const audio_device &device) = 0
Sets the preferred output audio device.
- Parameters:
device – Structure containing information about the desired output device.
- Returns:
The result object producing the operation status asynchronously.
// Wait device to be set wait(sdk->device_management().set_preferred_input_audio_device(device)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().set_preferred_output_audio_device(device) .then([]() { // Device is now set }) .on_error([](auto&& e) { // Handle exception });
-
virtual async_result<std::vector<audio_device>> get_audio_devices() = 0
Gets a list of the currently available audio devices in the system.
- Returns:
The result object producing a vector containing the audio devices asynchronously.
auto devices = wait(sdk->device_management().get_audio_devices()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_audio_devices() .then([](std::vector<audio_device>&& dev) { // devices are now available }) .on_error([](auto&& e) { // Handle exception });
-
virtual async_result<std::optional<audio_device>> get_current_audio_input_device() = 0
Gets the audio input device that is currently used by the system.
- Returns:
The result object producing the audio device asynchronously. async_result fails if no audio input device is set.
// Wait device to be set auto devices = wait(sdk->device_management().get_current_audio_input_device()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_current_audio_input_device() .then([](audio_device&& dev) { // Devices are now available }) .on_error([](auto&& e) { // Currently no audio input device set });
-
virtual async_result<std::optional<audio_device>> get_current_audio_output_device() = 0
Gets the audio output device currently used by the system.
- Returns:
The result object producing the audio device asynchronously. async_result fails if no audio output device is set.
// Wait device to be set auto devices = wait(sdk->device_management().get_current_audio_output_device()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_current_audio_output_device() .then([](audio_device&& dev) { // Current output device now available }) .on_error([](auto&& e) { // Currently no audio input device set });
-
virtual async_result<void> set_input_volume(linear_volume vol) = 0
Sets the system volume of the current input audio device.
Warning
This is an experimental functionality, which should not be used for general-purpose application feature development. Changing the input device’s volume may affect echo cancellation performance, will interfere with automatic gain adjustment, and will change the system volume of the input device.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> set_output_volume(linear_volume vol) = 0
Sets the system volume of the current output audio device.
Warning
This is an experimental functionality, which should not be used for general-purpose application feature development. Changing the output device’s volume may affect echo cancellation performance, will interfere with automatic gain adjustment, and will change the system volume of the output device.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<std::vector<camera_device>> get_video_devices() = 0
Gets a list of the currently available video devices in the system.
- Returns:
The result object producing a vector containing the audio devices asynchronously.
auto devices = wait(sdk->device_management().get_video_devices()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_video_devices() .then([](std::vector<camera_device>&& dev) { // Devices are now available }) .on_error([](auto&& e) { // Handle exception });
-
virtual async_result<std::optional<camera_device>> get_current_video_device() = 0
Gets the video device currently used by the system.
- Returns:
The result object producing the video device asynchronously. async_result fails if no video device is set.
// Wait device to be set auto devices = wait(sdk->device_management().get_current_video_device()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_current_video_device() .then([](camera_device&& dev) { // Current camera device now available }) .on_error([](auto&& e) { // Currently no video device set })
Get a list of all possible Screen Sharing sources. This can be both entire monitor screens or specific active application windows.
- Returns:
The result object producing the screen share source list asynchronously.
// Wait device to be set auto devices = wait(sdk->device_management().get_screen_share_sources()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_screen_share_sources() .then([](std::vector<screen_share_source>&& sources) { // Screen share source list available }) .on_error([](auto&& e) { // Error occurred getting the list });
Get the currently used source (window/screen) for Screen Sharing.
- Returns:
The result object producing the screen share source asynchronously. async_result fails if no screen share source is set.
// Wait device to be set auto devices = wait(sdk->device_management().get_current_screen_share_sources()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->device_management().get_current_screen_share_sources() .then([](screen_share_source&& dev) { // Current camera device now available }) .on_error([](auto&& e) { // Currently no video device set })
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_device_added> &&callback) = 0
Adds a listener for the audio_device_added events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::audio_device_added& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_device_added& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when an audio device is added to the system.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_device_removed> &&callback) = 0
Adds a listener for the audio_device_removed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::audio_device_removed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_device_removed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when an audio device is removed from the system.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_device_changed> &&callback) = 0
Adds a listener for the audio_device_changed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::audio_device_changed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_device_changed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a audio_device_changed event occurs.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<video_device_added> &&callback) = 0
Adds a listener for the video_device_added events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::video_device_added& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::video_device_added& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when an video device is added to the system.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<video_device_removed> &&callback) = 0
Adds a listener for the video_device_removed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::video_device_removed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::video_device_removed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when an video device is removed from the system.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<video_device_changed> &&callback) = 0
Adds a listener for the video_device_changed events.
- Parameters:
callback – The function object that is invoked when an video device is removed from the system.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<video_device_error> &&callback) = 0
Adds a listener for the video_device_error events.
- Parameters:
callback – The function object that is invoked when an video device enters error state.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_device_timeout_failure> &&callback) = 0
Adds a listener for the audio_device_timeout_failure events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->device_management().add_event_handler( [](const dolbyio::comms::audio_device_timeout_failure& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_device_timeout_failure& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a audio_device_timeout_failure event occurs.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_volume_changed> &&callback) = 0
Adds a listener for the audio_volume_changed events.
- Parameters:
callback – The function object that is invoked when a audio_volume_changed event occurs.
- Returns:
The result object producing the event_handler_id asynchronously.
Device Events
The Device Management Service events that are emitted by the SDK. They can be subscribed to using the
device_management::add_event_handler
methods.
-
struct audio_device_added
Emitted when a new audio device is added to the system.
Public Members
-
audio_device device
The device that was added.
-
audio_device device
-
struct audio_device_removed
Emitted when an audio device is removed from the system.
Public Members
-
audio_device::identity device_id
The ID of the device that was removed.
-
audio_device::identity device_id
-
struct audio_device_changed
Emitted when the current audio device has changed.
Public Members
-
std::optional<audio_device::identity> device
The new current device, or unset optional if there’s no device in given direction
-
enum audio_device::direction utilized_direction
If the new device has the capability to be both an input and output device, this field indicates the direction (input or output) for which the device is being used.
-
std::optional<audio_device::identity> device
-
struct audio_device_timeout_failure
Emitted when the audio device fails continuously for a prolonged time.
-
struct audio_volume_changed
Emitted when the volume set on the currently used audio device changes.
Public Members
-
enum audio_device::direction direction
The direction (input or output) in which the volume is changed.
-
linear_volume volume
The new volume
-
enum audio_device::direction direction
-
struct video_device_added
Emitted when a new video device is added to the system.
Public Members
-
camera_device device
The device that was added.
-
camera_device device
-
struct video_device_removed
Emitted when an video device is removed from the system.
Public Members
-
std::string uid
Unique id belonging to the removed device.
-
std::string uid
-
struct video_device_changed
Emitted a video device is in use.
Public Members
-
camera_device device = {}
The device that is in use, or default-constructed for no device.
-
camera_device device = {}
-
struct video_device_error
Emitted when an error is encountered with the video device.
Public Types
Public Members
-
std::string uid
Unique id belonging to the device.
-
std::string description
-
std::string recovery_suggestion
Error describing the issue encountered with device.
-
error_type type
Suggestion for possible remedy of the situation, may be empty. Type of video device error.
-
std::string uid
Device Structs
Other structures used by the Device Management Service that are not defined in the Device Management Interface interface.
-
class audio_device
The platform agnostic description of an audio device.
Public Types
-
enum direction
Enum describing the possible directions of audio devices.
Values:
-
enumerator none
No direction, this is default.
-
enumerator input
The device is used for input (microphone).
-
enumerator output
The device is used for output (speakers).
-
enumerator input_and_output
The device can be used for both input and output.
-
enumerator none
-
typedef void native_id_t
The audio device’s native ID.
This type is defined as a type alias, depending on the platform. It’s an integer for Linux and Macos, and a string on Windows. The native ID can be used to match the audio devices reported by the SDK against the system list of devices.
Public Functions
-
audio_device(const identity &pdata, const std::string &name, direction direction, const native_id_t &id)
Constructor.
- Parameters:
pdata – The platform data for this device, set and used by the SDK.
name – String name of the device.
direction – Direction of the device.
id – Native handle of the device.
-
audio_device(audio_device &&dev) noexcept = default
Move constructor.
- Parameters:
dev – Object moved from.
-
audio_device(const audio_device &dev) = default
Copy constructor.
- Parameters:
dev – Object being copied from.
-
audio_device &operator=(const audio_device &dev) = default
Copy assignment operator.
- Parameters:
dev – Object copied from.
- Returns:
The audio device.
-
audio_device &operator=(audio_device &&dev) = default
Move assignment operator.
- Parameters:
dev – Object moved from.
- Returns:
The audio device.
-
inline const std::string &name() const
Gets the name of the audio device.
- Returns:
String containing the name.
-
inline direction direction() const
Gets the direction of the audio device.
- Returns:
The direction of the device.
-
inline bool operator==(const audio_device &other) const
Compare operator for comparison against other audio_devices’s.
- Parameters:
other – The audio device to be compared against
- Returns:
true if the other structure denotes the same device as this, false otherwise.
-
inline bool operator==(const audio_device::identity &other) const
Compare operator for comparison against other audio_devices’ identity.
- Parameters:
other – The identity structure of the other device.
- Returns:
true if the other structure denotes the same device as this, false otherwise.
-
inline bool operator==(const std::optional<audio_device::identity> &other) const
Compare operator for comparison against other audio_devices’ identity.
- Parameters:
other – The optional holding identity structure of the other device, or empty optional.
- Returns:
true if the argument is a non-empty optional, holding the identity structure which denotes the same device as this, false otherwise.
-
inline const native_id_t &native_id() const
Get the system ID of the device.
- Returns:
the native ID of the device.
-
class identity
The identity of the audio device.
The identity class is copyable and moveable, but it’s mostly opaque. The application can not construct the identity instances, and can not get any meaningful data out of the identity objects. This class serves a purpose of identifying identical (same) devices in the platform-agnostic way, unline the system native ID.
The identity class implements the equality and less-than comparison operators, and there’s an std::hash<identity> specialisation provided, so the identity class can be used as a key in any type of the std containers.
-
enum direction
-
struct camera_device
The platform agnostic description of an camera device.
The platform agnostic description of source for screen sharing.
Public Types
Possible screen share source types.
Values:
Entire monitor or display screen.
Single applicaton window.
Public Members
Title of the screen.
Unique id of the screen in question.
-
type type
Type of the screen share source.
-
enum class dolbyio::comms::default_audio_device_policy
The default audio device selection policy.
Note
This API is Windows-only.
Values:
-
enumerator output
Use the default output device.
-
enumerator communications
Use the default communications device.
-
enumerator output
-
struct linear_volume
The linear volume.
The type-safe volume represenatation.
Public Functions
-
inline explicit constexpr linear_volume(double volume)
The constructor taking a double as a linear volume value.
The linear volume value is a floating-point number, where 0.0 is the maximum attenuation, 1.0 is the default volume (no attenuation, and no gain), and values above 1.0 are positive gain.
- Parameters:
volume – the volume in linear scale
-
inline constexpr double get_value() const
Gets the numerical value of the linear volume.
- Returns:
the volume value.
-
inline explicit constexpr linear_volume(double volume)