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.

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
  })

virtual async_result<std::vector<screen_share_source>> get_screen_share_sources() = 0

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
  });

virtual async_result<std::optional<screen_share_source>> get_current_screen_share_source() = 0

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<screen_share_error> &&callback) = 0

Adds a listener for the screen_share_error events. Upon receiving this event the application should stop screen sharing to ensure remote clients get information that screen share has stopped.

Parameters:

callback – The function object that is invoked when an screen share capturinge 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.

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.

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.

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

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.

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.

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.

struct video_device_error

Emitted when an error is encountered with the video device.

Public Types

enum class error_type

Enum describing the types of video device errors.

Values:

enumerator start_camera

An error occurred when trying to start camera.

enumerator camera_failure

An unrecoverable error occurred with the camera used for capturing.

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.

struct screen_share_error

Emitted when an error is encountered with the current screen capture. Upon receiving this error applications should call the services::conference::stop_screenshare method to inform other partcipants that screen share has stopped.

Public Types

enum class error_type

Enum describing the types of screen capture errors.

Values:

enumerator continuos_temporary

10 or more continuous errors occurred each of which was considered a temporary error. Capturing will not be force stopped here, but the application should stop screen sharing.

enumerator permanent

An unrecoverable error occurred with the camera used for capturing. The screen share will already have stopped capturing frames and the application must stop the screen sharing.

Public Members

screen_share_source source

The current screen share source.

error_type type
std::string description

Type of error encountered.

bool force_stopped

Error describing the issue encountered with screen source.

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.

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.

inline const identity &get_identity() const

Get the identity of the device.

Returns:

the identity 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.

Public Functions

identity(const std::shared_ptr<pimpl> &impl)
identity(identity&&) noexcept = default
identity(const identity&) = default
identity &operator=(identity&&) noexcept = default
identity &operator=(const identity&) = default
~identity() = default
inline const std::shared_ptr<pimpl> &get_impl() const
bool operator==(const identity &other) const noexcept

Compares the identity against another.

Parameters:

other – another identity

Returns:

true if the two identities denote the same device.

bool operator<(const identity &other) const noexcept

Compares the identity against another.

Parameters:

other – another identity

Returns:

true if the identity should be considered “less than” another one, for std containers, false otherwise.

struct camera_device

The platform agnostic description of an camera device.

Public Types

using id = std::string

Public Functions

inline bool operator<(const camera_device &other) const noexcept
inline bool operator==(const camera_device &other) const noexcept

Public Members

std::string display_name

Display name of the camera device.

id unique_id

Unique identifier for the camera device.

struct screen_share_source

The platform agnostic description of source for screen sharing.

Public Types

enum class type

Possible screen share source types.

Values:

enumerator screen

Entire monitor or display screen.

enumerator window

Single applicaton window.

Public Members

std::string title

Title of the screen.

intptr_t id

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.

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.