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:
  1. Acquire the necessary Access Token from the application server. This is a mandatory step that allows using the SDK.

  2. Set a log level for the SDK sdk::set_log_level. For the possible log levels, see the Logging enum.

  3. 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.

  4. Log in to the Dolby.io backend. For more information, see the Session Service.

  5. Retrieve a reference to Session Interface through sdk::session.

  6. Create and join a conference. A reference to the Conference Interface can be retrieved through the sdk::conference.

  7. Manage Audio Devices using the Device Management Interface. A reference to this service can be retrieved through sdk::device_management.

  8. Manage local and remote Audio streams using the Audio Service. A reference to this service can be retrieved through sdk::audio.

  9. Manage local Video stream using the Video Service. A reference to this service can be retrieved through sdk::video.

  10. 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 dolbyio::comms::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::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 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 will be 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 will be 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_level(log_level level)

Sets the logging level.

Deprecated:

Use set_log_settings instead.

dolbyio::comms::sdk::set_log_level(dolbyio::comms::log_level::INFO);

Parameters:

level – The log level to set.

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

Calling more than once has no effect.

Parameters:

settings – Structure of type log_settings.

Throws:

dolbyio::comms::exception – Thrown when:

  • provided invalid log directory

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.

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.

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.

Attention

SDK logs are always also output to stdout regardless of this setting.

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