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.