Device Management Service

Note

The Device Management Service is intended for Client Applications.

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 dolbyio::comms::services::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 intended for Client applications.

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.

// Wait device to be set
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<event_handler_id> add_event_handler(event_handler<device_added> &&callback) = 0

Adds a listener for the 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::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::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 will be 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<device_removed> &&callback) = 0

Adds a listener for the 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::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::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 will be 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<device_changed> &&callback) = 0

Adds a listener for the 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::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::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 will be invoked when a 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<device_timeout_failure> &&callback) = 0

Adds a listener for the 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::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::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 will be invoked when a 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 dolbyio::comms::device_added

Emitted when a new audio device is added to the system.

Public Members

dvc_device device

The device that was added.

struct dolbyio::comms::device_removed

Emitted when an audio device is removed from the system.

Public Members

std::string uid

Unique id belonging to the removed device.

struct dolbyio::comms::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.

Device Structs

Other structures used by the Device Management Service that are not defined in the Device Management Interface interface.

class dolbyio::comms::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 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

Public Functions

dvc_device(const std::string &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 std::string &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 std::string &uid() const

Gets the uid of the audio device.

Returns:

Unique id of the device. This is is a binary string and not a null terminated C string.

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 std::string &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.