OpenTok.Session
public class Session : IDisposable
The first step in using the OpenTok Windows SDK is to instantiate a Session object using the Session.Builder class.
The Session class implements the System.IDisposable interface. Be sure to call the Dispose() method of the Session object to release its resources when you no longer need the object (for example, when the app or window is closing).
See also Session Creation and Token Creation.
Nested types: OpenTok.Session.ConnectionEventArgs, OpenTok.Session.ErrorEventArgs, OpenTok.Session.SignalEventArgs, OpenTok.Session.StreamEventArgs, OpenTok.Session.ArchiveStartedEventArgs, OpenTok.Session.ArchiveStoppedEventArgs, OpenTok.Session.MuteForcedEventArgs, OpenTok.Session.Builder
Properties
| Name | Type | Description |
|---|---|---|
Connection |
Connection | { get; } Returns the Connection corresponding to this client's connection to this Session. |
Capabilities |
Capabilities | { get; } Whether the client can only subscribe to streams, or both publish and subscribe to streams, based on the role assigned to the token used to connect to the session. |
Methods
| Name | Description |
|---|---|
Session(builder) |
|
Connect(token) |
When the session connects, the Session object sends the Connected event. |
DisableForceMute() |
After you call the ForceMuteAll method (or a moderator in another client makes a call to mute all streams), any streams published after the moderation call are published with audio muted. |
Disconnect() |
As a best practice, before calling this method, call the Unpublish(Publisher) method for all publishers and wait for the Publisher.StreamDestroyed event. |
Dispose(disposing) |
|
Dispose() |
Disposes of the Session object's resources. |
ForceDisconnect(connection) |
While you can use the ForceDisconnect method to terminate your own connection, calling the Disconnect method is simpler. |
ForceMuteAll(excludedStreams) |
Also, any streams that are published after the call to the ForceMuteAll() method are published with audio muted. |
ForceMuteStream(stream) |
Check the CanForceMute property of the Session.Capabilities object to see if you can call this function successfully. |
Publish(publisher) |
|
SendSignal(type, data, connection, retryAfterReconnect) |
|
SetEncryptionSecret(secret) |
See the End-to-end encryption developer guide. |
Subscribe(subscriber) |
|
Unpublish(publisher) |
|
Unsubscribe(subscriber) |
Session(builder)
Parameters:
| Name | Type | Description |
|---|---|---|
builder |
Builder |
Connect(token)
When the session connects, the Session object sends the Connected event.
If the session fails to connect, the Session object sends the Error event.
Parameters:
| Name | Type | Description |
|---|---|---|
token |
string | The token for the user. See Token Creation Overview. |
DisableForceMute()
After you call the ForceMuteAll method (or a moderator in another client makes a call to mute all streams), any streams published after the moderation call are published with audio muted. Call the DisableForceMute() method to remove the mute state of a session (so that new published streams are not automatically muted).
Calling this method causes the Session object in each client connected to the session to send the MuteForced event, with the IsActive property of the MuteForcedEventArgs object to be set to false.
Check the CanForceMute property of the Session.Capabilities object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token creation overview).
See Muting the audio of streams in a session.
See: : - Capabilities, ForceMuteAll, MuteForced
Disconnect()
As a best practice, before calling this method, call the Unpublish(Publisher) method for all publishers and wait for the Publisher.StreamDestroyed event. This ensures the complete removal of publishers, especially if network connectivity issues prevent removal due to the reconnection feature, which may keep publisher streams alive for potential reconnection.
When the session disconnects, the Session sends the Disconnected event.
Dispose(disposing)
Parameters:
| Name | Type | Description |
|---|---|---|
disposing |
bool |
Dispose()
Disposes of the Session object's resources.
ForceDisconnect(connection)
While you can use the ForceDisconnect method to terminate your own connection, calling the Disconnect method is simpler. An error will be returned if the user's role does not include permissions required to force other users to disconnect. You define a user's role when you create the user token.
When a connection is terminated using this method, the Disconnected, ConnectionDropped and Publisher.StramDestroyed events are dispatched in the same way as they would be if the connection had terminated itself using Disconnect.
Parameters:
| Name | Type | Description |
|---|---|---|
connection |
Connection | The connection to disconnect. |
ForceMuteAll(excludedStreams)
Also, any streams that are published after the call to the ForceMuteAll() method are published with audio muted. You can remove the mute state of a session by calling the DisableForceMute() method. After you call the DisableForceMute() method, new streams published to the session will no longer have audio muted.
Calling this method causes the Session object in each client connected to the session to send the MuteForced event, with the IsActive property of the MuteForcedEventArgs object to be set to true.
Check the CanForceMute property of the Session.Capabilities object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token creation overview).
See Muting the audio of streams in a session.
Parameters:
| Name | Type | Description |
|---|---|---|
excludedStreams |
IEnumerable<Stream> | Streams to be excluded from the mute request. Set this to null (or do not set this parameter) to mute all streams in the session (including those published by the local client). |
See: : - Capabilities, ForceMuteStream, DisableForceMute(), Session.MuteForced, Publisher.MuteForced
ForceMuteStream(stream)
Check the CanForceMute property of the Session.Capabilities object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token creation overview).
See Muting the audio of streams in a session.
Parameters:
| Name | Type | Description |
|---|---|---|
stream |
Stream | The stream to be muted. |
See: : - Capabilities, ForceMuteAll, Publisher.MuteForced
Publish(publisher)
Parameters:
SendSignal(type, data, connection, retryAfterReconnect)
Parameters:
| Name | Type | Description |
|---|---|---|
type |
string | The type of the signal. The type is set in the SignalEventArgs.Type argument of the Signal event listener. |
data |
string | The data to send. The limit to the size of data is 8kB. The type is set in the SignalEventArgs.Data argument of the Signal event listener. |
connection |
Connection | |
retryAfterReconnect |
bool |
SetEncryptionSecret(secret)
See the End-to-end encryption developer guide.
The session must have been configured as end-to-end encrypted using the server SDK. If the session is already known not to be end-to-end encrypted, this method throws an OpenTokException with ErrorCode.EncryptionNotEnabled and any existing publishers and subscribers receive the same error and are dropped. If that is not known yet (for example, when the secret is set before the session connects), this method succeeds and the error is reported later, when publishing or subscribing.
Passing null or an empty string resets (clears) the previously set encryption secret. Resetting the secret is always allowed, even on a session that is known not to be end-to-end encrypted.
Any other secret must be between 8 and 256 bytes long when UTF-8 encoded; otherwise an OpenTokException with ErrorCode.InvalidEncryptionSecret is thrown.
A new secret takes effect for the publishers and subscribers that are already running, as well as for those created afterwards. Resetting the secret, however, only takes effect for publishers and subscribers created afterwards: those that are already running keep encrypting and decrypting with the previous secret until they are recreated.
Parameters:
| Name | Type | Description |
|---|---|---|
secret |
string | Value of the encryption secret, or null or an empty string to reset the previously set encryption secret. |
Subscribe(subscriber)
Parameters:
| Name | Type | Description |
|---|---|---|
subscriber |
Subscriber | The subscriber bound to the stream to be received. |
Unpublish(publisher)
Parameters:
Unsubscribe(subscriber)
Parameters:
| Name | Type | Description |
|---|---|---|
subscriber |
Subscriber | The Subcriber you want to stop subscribing to. |
Events
Connected
event EventHandler Connected
Sent when the client connects to the OpenTok session.
Disconnected
event EventHandler Disconnected
Sent when the client disconnects from the OpenTok session.
ConnectionCreated
event EventHandler<ConnectionEventArgs> ConnectionCreated
The ConnectionEventArgs.Connection object represents the client's connection to the session. Note that this method is invoked when other clients connect to the session. When your own client client connects, the Session sends the Connected event.
ConnectionDropped
event EventHandler<ConnectionEventArgs> ConnectionDropped
The ConnectionEventArgs.Connection object represents the client's previous connection to the session. Note that this method is called when other clients leave the session. When your own client client disconnects, the Session object sends the Connected event.
StreamReceived
event EventHandler<StreamEventArgs> StreamReceived
The StreamEventArgs.Stream object represents a snapshot of stream at the time of the callback. Create a Subscriber and call the Subscribe(Subscriber) method to subscribe to the stream.
StreamDropped
event EventHandler<StreamEventArgs> StreamDropped
The StreamEventArgs.Stream object represents a snapshot of stream at the time of the callback. It can be used to identify a corresponding Subscriber (if there is one).
Error
event EventHandler<ErrorEventArgs> Error
This event is sent if the attempt to connect to the session fails. It is also sent if the connection to the session drops due to an error after a successful connection, and in this case the event is sent just before the Disconnected event is sent.
Signal
event EventHandler<SignalEventArgs> Signal
Called when a signal is received in the session.
StreamHasCaptionsChanged
event EventHandler<StreamEventArgs> StreamHasCaptionsChanged
Called when a stream in the session changes between having captions and not having captions.
StreamHasAudioChanged
event EventHandler<StreamEventArgs> StreamHasAudioChanged
Called when a stream in the session changes between having audio and not having audio. The StreamEventArgs.Stream object represents a snapshot of stream at the time of the callback.
StreamHasVideoChanged
event EventHandler<StreamEventArgs> StreamHasVideoChanged
Called when a stream in the session changes between having video and not having video. The StreamEventArgs.Stream object represents a snapshot of stream at the time of the callback.
StreamDimensionsChanged
event EventHandler<StreamEventArgs> StreamDimensionsChanged
Called when the video dimensions of a stream in the session change. The StreamEventArgs.Stream object represents a snapshot of stream at the time of the callback.
ReconnectionStart
event EventHandler ReconnectionStart
If the client can reconnect to the session, the Session object sends the ReconnectionSuccess event. Otherwise, if the client cannot reconnect, the Session object sends the Disconnected event.
In response to this method being called, you may want to provide a user interface notification, to let the user know that the app is trying to reconnect to the session and that audio-video streams are temporarily disconnected.
See: : - ReconnectionSuccess, Disconnected
ReconnectionSuccess
event EventHandler ReconnectionSuccess
When the connection is lost, the Session object sends the Session.ReconnectionStart event, prior to sending the Session.ReconnectionSuccess event. If the client cannot reconnect to the session, the Session object sends the Session.Disconnected event.
Any existing publishers and subscribers are automatically reconnected when the client reconnects and this method is called.
By default, any signals initiated by the local client using the SendSignal(string, string, Connection, bool) method are sent when the client reconnects. To prevent any signals initiated while disconnected from being sent, set the retryAfterReconnect parameter of the SendSignal method to false. (All signals sent by other clients while your client was disconnected are received upon reconnecting.)
See: : - ReconnectionStart
ArchiveStarted
event EventHandler<ArchiveStartedEventArgs> ArchiveStarted
Called when an archive of the session starts recording. In response to this method, you may want to add a user interface notification (such as an icon in the Publisher view) that indicates the session is being recorded.
ArchiveStopped
event EventHandler<ArchiveStoppedEventArgs> ArchiveStopped
Called when an archive of the session stops being recorded. In response to this method, you may want to remove a user interface notification (such as an icon in the Publisher view) the session recording has stopped.
MuteForced
event EventHandler<MuteForcedEventArgs> MuteForced
Called when a moderator forces clients publishing streams to the session to mute audio (the IsActive property of the MuteForcedEventArgs object is set to true), or when a moderator disables the mute audio state in the session (the IsActive property of the MuteForcedEventArgs object is set to false).