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_preferred_input_audio_device(const dvc_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 dvc_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<dvc_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<dvc_device>&& dev) { // devices are now available }) .on_error([](auto&& e) { // Handle exception });
-
virtual async_result<std::optional<dvc_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([](dvc_device&& dev) { // Devices are now available }) .on_error([](auto&& e) { // Currently no audio input device set });
-
virtual async_result<std::optional<dvc_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([](dvc_device&& dev) { // Current output device now available }) .on_error([](auto&& e) { // Currently no audio input device set });
-
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 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_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 output device now available }) .on_error([](auto&& e) { // Currently no audio input 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.
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
-
dvc_device device
The device that was added.
-
dvc_device device
-
struct audio_device_removed
Emitted when an audio device is removed from the system.
Public Members
-
dvc_device::uid_t uid
Unique id belonging to the removed device.
-
dvc_device::uid_t uid
-
struct audio_device_changed
Emitted when the current audio device has changed.
Public Members
-
dvc_device device
The new current device if no device is false.
-
bool no_device
Flag indicating whether there is a device in use for the current direction. True means no device currently in use, false means device available.
-
enum dvc_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.
-
dvc_device device
-
struct audio_device_timeout_failure
Emitted when the audio device fails continuously for a prolonged time.
-
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 dvc_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
-
enum class platform
Enum describing the current platform. This is necessary because devices have different native handle formats for different platforms.
Values:
-
enumerator macos
-
enumerator linux
-
enumerator windows
-
enumerator macos
-
using uid_t = std::vector<unsigned char>
Public Functions
-
dvc_device(const uid_t &uid, const std::string &name, direction direction, platform platform, unsigned int id)
Constructor for Unix based platforms.
- Parameters:
uid – Unique id of the device. This is is a binary string and not a null terminated C string.
name – String name of the device.
direction – Direction of the device.
platform – The current platform.
id – Native handle of the device.
-
dvc_device(const uid_t &uid, const std::string &name, direction direction, platform platform, const std::string &id)
Constructor for Windows based platforms.
- Parameters:
uid – Unique id of the device. This is is a binary string and not a null terminated C string.
name – String name of the device.
direction – Direction of the device.
platform – The current platform.
id – Native handle of the device.
-
dvc_device(dvc_device &&dev)
Move constructor.
- Parameters:
dev – Object moved from.
-
dvc_device(const dvc_device &dev)
Copy constructor.
- Parameters:
dev – Object being copied from.
-
~dvc_device()
Destructor.
-
const dvc_device &operator=(const dvc_device &dev)
Copy assignment operator.
- Parameters:
dev – Object copied from.
- Returns:
New object that was copied.
-
const std::string &name() const
Gets the name of the audio device.
- Returns:
String containing the name.
-
const uid_t &uid() const
Gets the uid of the audio device.
- Returns:
Unique id of the device encoded as binary data.
-
direction direction() const
Gets the direction of the audio device.
- Returns:
The direction of the device.
-
unsigned int macos_native_id() const
Gets native id for MacOS platforms. This will throw if called on non-MacOS platform.
- Returns:
Unsigned integer representing the native device id.
-
unsigned int linux_native_id() const
Gets native id for Linux platforms. This will throw if called on non-Linux platform.
- Returns:
Unsigned integer representing the native device id.
-
const std::string &windows_native_id() const
Gets native id for Windows platforms. This will throw if called on non-Windows platform.
- Returns:
String representing the native device id.
-
bool operator==(const dvc_device &other) const
Compare operator for comparison against other dvc_devices’s.
- Parameters:
other – The DVC device to be compared against
- Returns:
Boolean indicating the two are the same.
-
enum direction
-
struct camera_device
The platform agnostic description of an camera device.