Suggestions

close search

Joining a Session — Windows

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

This topic includes the following sections:

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

Initializing a Session object

Before you can connect to a session, instantiate a Session object by calling the Session() constructor, passing in the appropriate Windows application context, your OpenTok API key, and an OpenTok session ID:

session = new Session(Context.Instance, API_KEY, SESSION_ID);

Note that calling the Session() constructor does not create an OpenTok session; it creates a C# Session object, which represents an existing OpenTok session. You create an OpenTok session using the OpenTok server-side libraries. See Creating an OpenTok session.

You will want to add handlers for basic session-related events:

session.Connected += Session_Connected;
session.Disconnected += Session_Disconnected;
session.Error += Session_Error;
session.ConnectionCreated += Session_ConnectionCreated;
session.StreamReceived += Session_StreamReceived;
session.StreamDropped += Session_StreamDropped;

You will want to implement each of the callback methods. For example, this method handles `ConnectionCreated` event (which occurs when the client connects to the OpenTok session):

private void Session_Connected(object sender, EventArgs e)
{
    Console.WriteLine("Session connected connection id:" + session.Connection.Id);
}

Note: The Session class implements the System.IDisposable interface. Be sure to call the Dispose() method of the Session object to release their resources when you no longer need the object (for example, when the app or window is closing).

Connecting to a session

Call the Session.connect(token) method, passing in a valid OpenTok token:

session.Connect(TOKEN);

The Session.Connected event is sent when the client connects to the OpenTok session.

session.ConnectionCreated += Session_ConnectionCreated;

private void Session_Connected(object sender, EventArgs e)
{
    Console.WriteLine("Session connected connection id:" + session.Connection.Id);
}

The Session.Error event is sent when there is an error in connecting:

session.Error += Session_Error;

private void Session_Error(object sender, Session.ErrorEventArgs e)
{
    Console.WriteLine("Session error:" + e.ErrorCode);
}

See the documentation for the OpenTok.ErrorCode enum for descriptions of values of the code property of the error object.

Disconnecting from a session

To disconnect from a session, call the Session.Disconnect() method:

session.Disconnect();

Detecting when you have disconnected

The Session.Disconnected message is sent when the client disconnects from the OpenTok session.

private void Session_Disconnected(object sender, EventArgs e)
{
    Console.WriteLine("Session disconnected");
}

If the connection to the session drops due to an error that occurs after a successful connection, the Session.Error event is sent prior to the Session.Disconnected event. The ErrorEventArgs object passed into the Session.Error event handler define the reason the connection dropped.

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 Session.ReconnectionStart event is sent. When the connection is restored, the Session.ReconnectionSuccess event is sent. If the client cannot restore the connection, the client disconnects from the OpenTok session, and the Session.Disconnected event is sent.

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

session.ReconnectionStart = Session_ReconnectionStart;
session.ReconnectionSuccess = Session_ReconnectionSuccess;
session.Disconnected = Session_Disconnected;

private void Session_ReconnectionStart(object sender, EventArgs e)
{
    // Display a user interface notification.
}

private void Session_ReconnectionSuccess(object sender, EventArgs e)
{
    // Adjust user interface.
}


private void Session_Disconnected(object sender, EventArgs e)
{
    // Adjust user interface.
}

When your client temporarily disconnects from a session, Subscriber objects in clients subscribing to the stream send Subscriber.StreamDisconnected and Subscriber.StreamDisconnected events when your published stream drops and when (and if) it 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. You can use the Session.SendSignal(type, signal, connection, retryAfterReconnect) method and set the retryAfterReconnect parameter to false to prevent signals from being queued while you are disconnected. For more information, see Preventing signals from being sent during automatic reconnection.

Detecting when other clients have connected and disconnected

When you are connected to a session, the Session.ConnectionCreated event is sent when a new client (other than your own) connects to the session. The ConnectionEventArgs object passed into the event listener defines the connection hat has left the session:

session.ConnectionCreated += Session_ConnectionCreated;

private void Session_ConnectionCreated(object sender, EventArgs e)
{
    // Another client connected to the session.
}

The Session.ConnectionDropped event is sent when a client (other than your own) leaves the session. The ConnectionEventArgs object passed into the event listener defines the connection that has left the session.

session.ConnectionCreated += Session_ConnectionDropped;

private void Session_ConnectionDropped(object sender, EventArgs e)
{
    // Another client disconnected from the session.
}