Suggestions

close search

Searching ...

Using a session ID and token, you can connect to the OpenTok session using the OpenTok Linux SDK.

This topic includes the following sections:

• Instantiating an otc_session instance and session-related callbacks
• Connecting to a session
• Disconnecting from a session
• Detecting when you have disconnected from a session
• Automatic reconnection
• Detecting when other clients have connected and disconnected

For information on creating a session ID and an authentication token, see Session Creation and Token Creation.

Instantiating an otc_session instance and session-related callbacks

Create a structure of type otc_session_callbacks, and function pointers to it callback function members. For example:

char *session_user_data = strdup("Session user data");

static void on_session_connected(otc_session *session, void *user_data) {
  // You could publish a stream once you connect to the session.
}

static void on_session_stream_received(otc_session *session,
                                       void *user_data,
                                       const otc_stream *stream) {
  // You could call otc_subscriber_new() to subscribe to this stream
    // in response to this event.
}

static void on_session_stream_dropped(otc_session *session,
                                      void *user_data,
                                      const otc_stream *stream) {
  // If you have subscribed to this stream, you should
  // call otc_subscriber_delete() to delete the subscriber in response to this event.
}

static void on_disconnected(otc_session *session, void *user_data) {
  // Handle the on_disconnected event.
}

static void on_session_error(otc_session *session,
                             void *user_data,
                             const char *error_string,
                             enum otc_session_error_code error) {
  // Handle the error.
}

struct otc_session_callbacks session_callbacks = {0};
session_callbacks.user_data = session_user_data;
session_callbacks.on_connected = on_session_connected;
session_callbacks.on_stream_received = on_session_stream_received;
session_callbacks.on_stream_dropped = on_session_stream_dropped;
session_callbacks.on_disconnected = on_session_disconnected;
session_callbacks.on_error = on_session_error;

Use the user_data member of the otc_session_callbacks structure to set data you may want to reference in the callback functions. In this example, we set it to a pointer to a string object. But it could be a pointer to an instance of some other type that contains meaningful information.

The other members of the otc_session_callbacks structure are callback functions that are called when events related to the OpenTok session occur. The previous example includes callbacks for the following:

• on_connected -- Called when the otc_session_connect() function (see below) successfully connects the instance to an OpenTok session.

• on_stream_received -- Called when there is a new stream in the OpenTok session (when another client publishes a stream to the session).

• on_stream_dropped -- Called when another client's stream is dropped from the OpenTok session. This can happen when the client stops publishing the stream or if the client's network connection drops.

• on_disconnected -- Called when a the application disconnects from the OpenTok session (see below).

• on_error -- Called when an error occurs in connecting to the session. This function includes parameters for an error string and an error code that is defined by the otc_session_error_code enum.

All callbacks will not be made on the application or main thread but on an internal thread. The application should return the callback as quickly as possible to avoid blocking the internal thread.

See otc_session_callbacks in the OpenTok Linux SDK reference for details on each of the callback functions.

After initializing the the otc_session_callbacks structure, call the otc_session_new() function, passing in your OpenTok API key string, the OpenTok session ID string, and a pointer to the otc_session_callbacks structure:

otc_session *session = NULL;
session = otc_session_new(API_KEY, SESSION_ID, &session_callbacks);

The otc_session_new() function returns an otc_session structure, which represents an OpenTok session.

To use advanced session settings, call the otc_session_new_with_settings(), instead of the otc_session_new() function. This function takes an settings parameter that is a pointer to an otc_session_settings struct that defines the advanced settings. For example, the following code uses the otc_session_settings_new () function to instantiate an otc_session_settings struct and calls otc_session_settings_set_connection_events_suppressed(OTC_TRUE) to have the SDK suppress connection events, to support large interactive video sessions. It then passes the otc_session_settings struct into the otc_session_new_with_settings() function:

// Populate the session_callbacks struct, as in the previous example. Then...

otc_session_settings *session_settings = otc_session_settings_new();
otc_session_settings_set_connection_events_suppressed(session_settings, OTC_TRUE);
otc_session *session = otc_session_new_with_settings(API_KEY,
                                                     SESSION_ID,
                                                     &session_callbacks,
                                                     session_settings);

In addition to otc_session_settings_set_connection_events_suppressed(), the following functions let you set advanced settings for a session:

• otc_session_settings_set_custom_ice_config() — Enables custom ICE sever configuration. This is part of the configurable TURN feature.

• otc_session_settings_set_ip_whitelist() — This supports the allowed IP address feature available as an add-on feature.

• otc_session_settings_set_proxy_url() — Sets an IP proxy URL. See the IP Proxy developer guide.

Connecting to a session

After creating the session and publisher instances, call the otc_session_connect() function:

  otc_session_connect(session, TOKEN);

This function connects the client to the OpenTok session. It takes two arguments:

• The otc_session structure instance.

• The OpenTok token string.

Upon successfully connecting, the on_connected callback function of the otc_session_callbacks struct is called. Upon error, the on_error callback function of the otc_session_callbacks struct is called.

Disconnecting from a session

To disconnect from a session, call the otc_session_disconnect() function:

otc_session_disconnect(session);

If you will not be reconnecting to the session, you should call the otc_session_delete() and otc_destroy() functions:

otc_session_delete(session);
session = NULL;

otc_destroy();

Detecting when you have disconnected

When the client disconnects from the OpenTok session, the on_disconnected callback function of the otc_session_callbacks struct is called.

Automatic reconnection

Clients will attempt to automatically reconnect to a session they disconnect unexpectedly (for example, due to a drop in network connectivity). You do not need to add any code to have the clients reconnect automatically, unless you want to respond to events that occur when your client disconnects and reconnects.

When the connection is dropped and the client tries to reconnect, the on_reconnection_started callback function of the otc_session_callbacks struct is called. When the connection is restored, the on_reconnected callback function of the otc_session_callbacks struct is called. If the client cannot restore the connection, the client disconnects from the OpenTok session, and the on_disconnected callback function of the otc_session_callbacks struct is called.

In response to these events, your application can (optionally) display user interface notifications indicating the temporary disconnection, reconnection, and disconnection states.

When another client temporarily disconnects from a session, the on_disconnected callback function of the otc_subscriber_callbacks struct for a subscriber to a stream published by that client is called. The on_reconnected callback function of the otc_subscriber_callbacks struct for the subscriber is invoked when (and if) the client reconnects and the stream resumes automatically. For more information, see the Automatic reconnection section in the "Subscribing to streams" developer's guide.

By default, any signals you send while your client is temporarily disconnected from a session are queued and sent when (and if) you successfully reconnect. To prevent signals from being queued while you are disconnected. you can use the otc_session_send_signal_with_options() function or the otc_session_send_signal_to_connection_with_options () function and set the retryAfterReconnect member to false in the otc_signal_options you pass into the function. For more information, see Preventing signals from being sent during automatic reconnection.

Detecting when other clients have connected and disconnected

Once you have connected to a session, the on_connection_created callback function of the otc_session_callbacks struct is called when a new client (other than your own) connects to the session. The connection parameter of that function is a pointer to an instance of an otc_connection struct corresponding to the client connecting to the session.

The on_connection_dropped callback function of the otc_session_callbacks struct is called when a client (other than your own) disconnects from the session. The connection parameter of that function is a pointer to the otc_connection struct corresponding to the client disconnecting from the session.