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:
  1. Log in to the session using the session::open command.

  2. Listen to a conference and record it. For more information, see the Conference Service.

  3. 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 dolbyio::comms::services::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 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<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 will be 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 will be 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 will be 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 will be 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 will be 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 will be invoked when a conference with enabled notification_subscription_type::conference_ended subscription ends.

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.

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

std::vector<participant_info> participants

The collection of active participants.

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