Sdk Interface

#include <dolbyio/comms/sdk.h>

This interface is the starting point for the SDK. It exposes methods that allow initializing the SDK and accessing the underlying services. The basic steps to use the SDK are:

Acquire the necessary Access Token from the application server. This is a mandatory step that allows using the SDK.
Set a log level for the SDK sdk::set_log_level. For the possible log levels, see the Logging enum.
Create the SDK using sdk::create. The create call needs to pass a valid access token in order to initialize the SDK. Wait for the return of the create call.
Log in to the Dolby.io backend. For more information, see the Session Service.
Retrieve a reference to Session Interface through sdk::session.
Create and join a conference. A reference to the Conference Interface can be retrieved through the sdk::conference.
Manage Audio Devices using the Device Management Interface. A reference to this service can be retrieved through sdk::device_management.
Manage local and remote Audio streams using the Audio Service. A reference to this service can be retrieved through sdk::audio.
Manage local Video stream using the Video Service. A reference to this service can be retrieved through sdk::video.
The destructor for the SDK performs necessary cleanups when the SDK instance goes out of scope. This means that you do not need to perform any cleanup.

class sdk

The SDK interface is the entry point for the CoreSDK API.

Attention: The SDK interface contains methods that return async_result. Each function that returns async_result is asynchronous and executes operations on the SDK event loop. The caller can block the calling thread until the operation completes and can use the wait helper. The caller can also chain consecutive operations which depend on the completion of this method using async_result::then calls. When you create an async_result chain, terminate it using async_result::on_error.

Public Functions

virtual ~sdk(): The destructor that shuts down the SDK.

virtual services::media_io &media_io() = 0

The Media IO Service accessor.

auto conference_service = sdk->media_io();

Returns:: References to the servies::media_io service.

virtual services::audio &audio() = 0

The Audio Service accessor.

Returns:: Reference to the services::audio service.

virtual services::video &video() = 0

The Video Service accessor.

Returns:: Reference to the services::video service.

virtual services::session &session() = 0

The Session Service accessor.

auto session_service = sdk->session();

Returns:: Reference to the services::session service.

virtual services::conference &conference() = 0

The Conference Service accessor.

auto conference_service = sdk->conference();

Returns:: The reference to the services::conference service.

virtual services::device_management &device_management() = 0

The Device Management Service accessor.

auto device_management_service = sdk->device_management();

Returns:: The reference to the services::device_management service.

virtual services::experimental &experimental() = 0

virtual async_result<component_data> register_component_version(const std::string &name, const std::string &version) = 0

Registers the component version for internal telemetry.

The component name and version are free-form strings, which will be added to the Dolby.io telemetry reports. If a component with given name has already been registered with a different version, this method fails and returns error information asynchronously.

sdk->register_component_version("MyApp", "1.0.0")
     .then([](sdk::component_data&& data) {
       component_logger_ = std::move(data.logger);
     })
     .on_error([](auto&&){ std::cerr << "Failed to register my app to
telemetry" << std::endl; }); 

Parameters:

name – the name of the component
version – the version of the component

Returns:

The result object producing the success or failure information asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<signaling_channel_exception> &&callback) = 0

Adds a listener for the signaling_channel_exception events.

// The method invokes via wait blocks until it succeeds or fails
handlers.push_back(wait(sdk->add_event_handler(
    [](const dolbyio::comms::signalling_channel_exception& e) {
    // Process the event
})));

 // Invoking the method directly requires chaining successive operations
 // via the `then` call
sdk->add_event_handler(
  [](const dolbyio::comms::signalling_channel_exception& 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 the WebSocket responsible for signaling detects a failure.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<invalid_token_exception> &&callback) = 0

Adds a listener for the invalid_token_exception events.

// The method invokes via wait blocks until it succeeds or fails
handlers.push_back(wait(sdk->add_event_handler(
  [](const dolbyio::comms::invalid_token_exception& e) {
    // Process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->add_event_handler(
  [](const dolbyio::comms::invalid_token_exception& 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 in the case of using an invalid token.
Returns:: The result object producing the event_handler_id asynchronously.

Public Static Functions

static void set_app_allocator(const app_allocator &allocator)

Set the instance of app_allocator.

This method causes the global operators new and delete in the SDK to use the application-provided allocator. If the application wishes to override the SDK’s memory allocator, it must do so prior to calling any other SDK APIs, otherwise there is a risk of overriding memory deallocation functions and using the overriden functions to free memory that has been allocated using the default memory allocator. The SDK restores the default allocator upon application exit (not the SDK destruction) to allow freeing memory allocated in global objects using the system allocator.

Attention: This is only available on Windows.

If the allocator has already been overridden, and the new one uses different memory management functions, this method will throw. If the allocator does not contain all four memory allocation functions, this method will also throw. The application should not attempt to restore the default allocator before shutdown; the SDK does it automatically.

Parameters:: allocator – the allocator to be used in the SDK.

static void set_log_settings(const log_settings &settings)

Sets what and how to log.

dolbyio::comms::sdk::log_settings log_settings;
log_settings.sdk_log_level = dolbyio::comms::log_level::INFO;
log_settings.media_log_level = dolbyio::comms::log_level::OFF;
log_settings.log_directory = ".";
dolbyio::comms::sdk::set_log_settings(log_settings);

Parameters:

settings – Structure of type log_settings.

Throws:

dolbyio::comms::exception – Thrown when:

provided invalid log directory
attempting to set log settings more than once

Returns:

true if logging settings were set, false otherwise

static std::unique_ptr<sdk> create(const std::string &access_token, std::function<void(std::unique_ptr<refresh_token>)> &&refresh_token_callback)

Creates an instance of the SDK. This method is synchronous and is available when the SDK is created and initialized. Otherwise, SDK triggers errors and exceptions.

std::unique_ptr<sdk> sdk =
 dolbyio::comms::sdk::create(
   access_token,
   [](std::function<void(std::unique_ptr<dolbyio::comms::refresh_token>)>&&
cb) { std::shared_ptr<refresh_token> shared_cb = std::move(cb);
     users_fetch_token_method().then([cb{std::move(shared_cb)}](auto&&token)
     {
       (*cb)(std::move(token));
     });
  });

Attention: The SDK invokes refresh_token_callback on the SDKs event loop thread. Since fetching a token requires a network request, we recommend not blocking the SDK thread. You can use the async_result and solver APIs to create an asynchronous method and chain the SDK refresh_token callback invocation when the token is fetched.

Parameters:

access_token – The access token that is required to send requests to the Dolby.io backed. The token needs to be fetched externally and provided in the create call.
refresh_token_callback – The function object that is called to refresh the access token. It fetches a new and valid access token and passes the token to the SDK. To do it, the function object is passed as a pointer to the SDK’s refresh_token callable, callable, which needs to be invoked with the newly acquired access token. This callback is invoked twice before the access token expiration.

Throws:

dolbyio::comms::exception – The SDK throws the object when an error occurs.

Returns:

The unique pointer to the initialized SDK object.

static std::string get_sdk_version(): Version of the SDK.

struct component_data

Component specific data returned by the SDK when the components is registered.

Public Members

std::shared_ptr<logger_sink> logger: Shared pointer to the logger instance created for the component when it is registered with the SDK. This can be used to log using the SDK logger and thus log to the same file as the SDK.

struct log_settings

Settings describing what and how to log.

Public Members

log_level sdk_log_level = log_level::INFO : Log level for SDK logs. Default is INFO.

log_level media_log_level = log_level::OFF : Log level for Media Engine logs. It is recommended to keep the Media Engine log level at OFF, ERROR or WARNING to avoid spam and only enable more detailed logs when necessary. Default is OFF.

log_level dvc_log_level = log_level::OFF : Log level for DVC logs. It is recommended to keep the DVC log level at OFF, ERROR or WARNING to avoid spam and only enable more detailed logs when necessary. Default is OFF.

std::string log_directory = {}: Directory to which SDK logs should be saved. The application must have write access to the directory or it must be able to create such a directory. Providing a valid directory implies starting logging to a timestamped file. Providing no value or an empty string has no effect. Default is an empty string.

std::shared_ptr<logger_sink_callback> log_callback = {}: Log callback function. The callback object will not be destroyed until the application shutdown (SDK dynamic library unload). If set, the logs will be additionally passed to the callback.

bool suppress_stdout_logs = {false}: Suppress the logs to stdout. This parameter will only be taken into account if the log directory or the log callback is set. If true, logs will not be output on the stdout.

class refresh_token

The interface for the function object, which is passed by the SDK to the applications’ refresh token callback. The application needs to fetch a new token and invoke the function call operator that passes the token.

Public Functions

virtual ~refresh_token(): The destructor of the refresh token object.

virtual void operator()(std::string &&token) = 0

Overloaded function call operator which will be passed the newly acquired token.

Parameters:: token – R-value reference to the token string.