Session Service

The Session Service allows logging in and out of the Dolby.io backend. Logging into the backend is essential for the SDK to receive backend notifications in and out of a conference; the Session Service provides APIs for the application to manage subscriptions to various types of the backend notifications.

The basic usage of the session service is:

Log in to the session using the session::open command.
Listen to a conference and record it. For more information, see the Conference Service.
Log out of the session using the session::close method.

Session Interface

#include <dolbyio/comms/session.h>

The methods of the Session Interface provide the ability to connect to the Dolby.io backend. The session service methods are all asynchronous in nature. For more information, refer to Asynchronous Operations. The structures defined in the interface are used by and returned by methods of the interface.

class session

The session class.

Attention: The session_service 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 Types

enum class state

The current state of a session.

Values:

enumerator disconnected: The session is disconnected, this is the initial state.

enumerator connecting: The session is connecting.

enumerator connected: The session is connected.

enumerator reconnecting: The session is reconnecting.

Public Functions

virtual async_result<user_info> open(user_info &&identification) = 0

Opens a new session for the specified participant.

// Wait for a new session to open
auto info = wait(sdk->session().open(identification));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->session().open(identification)
  .then([](auto&&) {
    // session is now opened and info available
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Parameters:: identification – Information about the participant who tries to open a session.
Returns:: The result object producing the user_info about opened session asynchronously.

virtual async_result<user_info> update(user_info &&identification) = 0

Updates the metadata of a logged in user.

// Synchronous approach:
auto info = wait(sdk->session().update(identification));

// Asynchronous approach:
sdk->session().update(identification)
  .then([](auto&&) {
    // The user has been updated.
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Parameters:: identification – Information about the participant who tries to open a session. Only the name and avatarUrl are updated, other fields of the user identification are ignored.
Returns:: The result object producing the new user_info asynchronously.

virtual async_result<void> close() = 0

Closes the current session.

// Wait for the session to close
wait(sdk->session().close());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->session().close()
  .then([]() {
    // session is now closed
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Returns:: The result object producing the operation status asynchronously.

virtual async_result<user_info> session_info() const = 0

Gets the information about the current session.

// Wait for the session to close
auto info = wait(sdk->session().session_info());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->session_info().
  .then([](auto&&) {
    // session info now available
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Returns:: The result object producing the user_info asynchronously.

virtual async_result<void> subscribe(const std::vector<notification_subscription> &subscriptions) = 0

Subscribes to all status updates for a specified conference, such as added/removed participants and conference ended, within a notification and without joinning the conference.

Parameters:: subscriptions – Turns on the subscription for the specified notifications.
Returns:: The result object producing the operation status asynchronously.

virtual async_result<void> unsubscribe(const std::vector<notification_subscription> &subscriptions) = 0

Unsubscribes from status updates notifications for the specified conference.

Parameters:: subscriptions – Turns off the subscription for the specified notifications.
Returns:: The result object producing the operation status asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::participant_joined> &&callback) = 0

Adds a listener for subscription_events::participant_joined events.

Parameters:: callback – The function object that is invoked when a participant joins the conference with enabled notification_subscription_type::participant_joined subscription.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::participant_left> &&callback) = 0

Adds a listener for subscription_events::participant_left events.

Parameters:: callback – The function object that is invoked when a participant leaves the conference with enabled notification_subscription_type::participant_left subscription.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::active_participants> &&callback) = 0

Adds a listener for subscription_events::active_participants events.

Parameters:: callback – The function object that is invoked periodically passing the list of active participants for the conference with enabled notification_subscription_type::active_participants subscription.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::conference_status> &&callback) = 0

Adds a listener for subscription_events::conference_status events.

Parameters:: callback – The function object that is invoked passing the status of the conference with the enabled notification_subscription_type::conference_created subscription.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::conference_created> &&callback) = 0

Adds a listener for subscription_events::conference_created events.

Parameters:: callback – The function object that is invoked when a conference with enabled notification_subscription_type::conference_created subscription is created.
Returns:: The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<subscription_events::conference_ended> &&callback) = 0

Adds a listener for subscription_events::conference_ended events.

Parameters:: callback – The function object that is invoked when a conference with enabled notification_subscription_type::conference_ended subscription ends.
Returns:: The result object producing the event_handler_id asynchronously.

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

Adds a listener for the token_expired_event.

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.

class state_exception : public dolbyio::comms::session_exception 

The class that defines exceptions for invalid session states.

Public Functions

state_exception(state current, state required)

The constructor that takes the current and the required state of a session.

Parameters:

current – The current state of the session.
required – The required state of the session.

inline state current_state() const noexcept

Returns the current state of a session that is stored in the exception.

Returns:: The current state of the session.

inline state required_state() const noexcept

Returns the required state of a session that is stored in the exception.

Returns:: A string that contains the required state of a session.

struct user_info

The class that represents the participant who tries to open a session.

Public Members

std::string name: The name of the participant.

std::string externalId: The external unique identifier that the customer’s application can add to the participant while opening a session. If a participant uses the same external ID in conferences, the participant’s ID also remains the same across all sessions.

std::string avatarUrl: The URL of the participant’s avatar.

std::optional<std::string> participant_id = {}: The unique ID for the participant opening the session, this field is provided by the backend when session is opened

Other Structures

Other structures used by the Session Service, which are not defined in the Session Interface interface.

struct token_expired_event

The event notifying about the access token expiration.

Upon the reception of this event, the application will know that the access token used by the SDK has expired. Note that the application will receive two token refresh requests before that. If the application does not deliver new, valid token, and the old one expires, the application can expect the conference to be closed, and most API calls will just return the errors.

enum class dolbyio::comms::notification_subscription_type

The subscription type.

Values:

enumerator conference_created: Subscribe to conference created events.

enumerator conference_ended: Subscribe to conference ended events.

enumerator participant_joined: Subscribe to participant joining the conference.

enumerator participant_left: Subscribe to participant leaving the conference.

enumerator active_participants: Subscribe to periodic notifications about the active participants in the conference.

struct notification_subscription

Subscription information.

Applications wishing to receive events about the conferences which are not joined should use this structure in the services::session::subscribe() and the services::session::unsubscribe() APIs to select the types of events and the conference aliases of interest.

Public Functions

inline notification_subscription(const std::string &conference_alias, notification_subscription_type type)

The constructor.

Parameters:

conference_alias – The alias of the conference.
type – Type of subscription event.

Public Members

std::string conference_alias: The alias of the conference.

notification_subscription_type type: The event type.

struct conference

The conference struct used in all subscription events.

Public Members

std::optional<std::string> conference_id: The conference ID. May have no value if the conference with given alias has not been created.

std::string conference_alias: The conference alias.

struct participant_joined

Event notifying about participant joined to the conference.

The application must use the services::session::subscribe() method to subscribe on the notification_subscription_type::participant_joined event for given conference in order to receive these events.

Public Members

subscription_events::conference conference: The conference into which the participant joined.

participant_info participant: The joined participant info.

struct participant_left

Event notifying about participant left the conference.

The application must use the services::session::subscribe() method to subscribe on the notification_subscription_type::participant_left event for given conference in order to receive these events.

Public Members

subscription_events::conference conference: The conference from which the participant left.

participant_info participant: The left participant info.

struct active_participants

Event notifying about list of active conference participants.

The application must use the services::session::subscribe() method to subscribe on the notification_subscription_type::active_participants event for given conference in order to receive these events.

Public Members

subscription_events::conference conference: The conference from which the participant left.

int participants_count: The number of all participants, active and listeners.

int viewer_count: The number of real time streaming viewers.

std::vector<participant_info> participants: The collection of active participants.

struct conference_status

Event notifying about the conference status.

This event is sent once when the application subscribes to the notification_subscription_type::conference_created event and notifies about the current status of the conference (which may or may not be created at this point).

Public Members

subscription_events::conference conference: The conference for which the status is reported.

bool live: True if the conference is live.

int start_timestamp: Timestamp of the conference start; this field is valid only if the conference is live.

std::vector<participant_info> participants: The list of conference participants. Empty if the conference is not live.

struct conference_created

Event notifying about the conference being created.

The application must use the services::session::subscribe() method to subscribe on the notification_subscription_type::conference_created event for given conference in order to receive these events.

Public Members

subscription_events::conference conference: The conference being created.

struct conference_ended

Event notifying about the conference ended.

The application must use the services::session::subscribe() method to subscribe on the notification_subscription_type::conference_ended event for given conference in order to receive these events.

Public Members

subscription_events::conference conference: The conference that ended.