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.

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.

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.

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.

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.

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.

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

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.

platform platform_type() const

Gets the platform type of the device.

Returns:: The platform type.

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.

bool operator==(const uid_t &uid) const

Compare operator for comparison of unique id.

Parameters:: uid – The unique id to be compared
Returns:: Boolean indicating the device has this unique id.

struct camera_device

The platform agnostic description of an camera device.

Public Members

std::string display_name

std::string unique_id