OTSession

The first step in using the OpenTok iOS SDK is to initialize an OTSession object with your API key and a valid session ID Use the OTSession object to connect to OpenTok using your developer API key and a valid token.

Properties

sessionConnectionStatus

Type: OTSessionConnectionStatus

The status of this OTSession instance. Useful for ad-hoc queries about session status.

Valid values are defined in OTSessionConnectionStatus:

  • OTSessionConnectionStatusNotConnected - The session is not connected.
  • OTSessionConnectionStatusConnected - The session is connected.
  • OTSessionConnectionStatusConnecting - The session is connecting.
  • OTSessionConnectionStatusDisconnecting - The session is disconnecting.
  • OTSessionConnectionStatusFailed - The session has experienced a fatal error

On instantiation, expect the sessionConnectionStatus to have the value OTSessionConnectionStatusNotConnected.

You can use a key-value observer to monitor this property. However, the [OTSessionDelegate sessionDidConnect:] and [OTSessionDelegate sessionDidDisconnect:] messages are sent to the session's delegate when the session connects and disconnects.

sessionId

Type: NSString *

The session ID of this instance. This is an immutable value.

streams

Type: NSDictionary<NSString *, OTStream *> *

The streams that are a part of this session, keyed by streamId.

connection

Type: OTConnection *

The OTConnection object for this session. The connection property is only available once the [OTSessionDelegate sessionDidConnect:] message is sent. If the session fails to connect, this property shall remain nil.

delegate

Type: id&lt;OTSessionDelegate&gt;

The OTSessionDelegate object that serves as a delegate object for this OTSession object, handling messages on behalf of this session.

apiQueue

Type: dispatch_queue_t

The delegate callback queue is application-definable. The GCD queue for issuing callbacks to the delegate may be overridden to allow integration with XCTest (new in XCode 5) or other frameworks that need the to operate in the main thread.

capabilities

Type: OTSessionCapabilities *

An OTSessionCapabilities object, which indicates whether the client can publish and subscribe to streams in the session, based on the role assigned to the token used to connect to the session. This property is set to nil until you have connected to a session and the [OTSessionDelegate sessionDidConnect:] method has been called.

Methods

Name Description
initWithApiKey:sessionId:delegate:(apiKey, sessionId, delegate) → {id} Initialize this session with your OpenTok API key , a session ID, and delegate before connecting to OpenTok.
initWithApiKey:sessionId:delegate:settings:(apiKey, sessionId, delegate, settings) → {id} Initialize the OTSession object with settings defined by an OTSessionSettings object.
connectWithToken:error:(token, error) Once your application has a valid token, connect with your API key to begin participating in an OpenTok session.
disconnect:(error) Disconnect from an active OpenTok session.
disconnect()
publish:error:(publisher, error) Adds a publisher to the session.
publish:(publisher)
unpublish:error:(publisher, error) Removes a publisher from the session.
unpublish:(publisher)
subscribe:error:(subscriber, error) Connects this subscriber instance to the session and begins subscribing.
subscribe:(subscriber)
unsubscribe:error:(subscriber, error) Disconnects this subscriber instance from the session and begins object cleanup.
unsubscribe:(subscriber)
signalWithType:string:connection:error:(type, string, connection, error) Sends a signal to one or more clients in a session.
signalWithType:string:connection:retryAfterReconnect:error:(type, string, connection, retryAfterReconnect, error) Sends a signal to one or more clients in a session.
forceMuteAll:error:(excludedStreams, error) Forces all publishers in the session (except for those publishing excluded streams) to mute audio.
disableForceMute:(error) Disables the active mute state of the session.
forceMuteStream:error:(stream, error) Forces the publisher of a specified stream to mute its audio.
forceDisconnect:error:(connection, error) Forces a client to disconnect from the session.
reportIssue:(issueId) Report that your app experienced an issue.
setEncryptionSecret:error:(secret, error) Sets the end-to-end encryption secret used by all publishers and subscribers.
init() → {instancetype}

initWithApiKey:sessionId:delegate:(apiKey, sessionId, delegate) → {id}

Initialize this session with your OpenTok API key , a session ID, and delegate before connecting to OpenTok. Send the [OTSession connectWithToken:error:] message to connect to the session.

Important: If you are using a Vonage application (instead of an OpenTok project), pass in the application ID (not an OpenTok API key) for this parameter.

Parameters:
Name Type Description
apiKey NSString * Your OpenTok API key.
sessionId NSString * The session ID of this instance.
delegate id&lt;OTSessionDelegate&gt; The delegate (OTSessionDelegate) that handles messages on behalf of this session.
Returns:

The OTSession object, or nil if initialization fails.

initWithApiKey:sessionId:delegate:settings:(apiKey, sessionId, delegate, settings) → {id}

Initialize the OTSession object with settings defined by an OTSessionSettings object.

Important: If you are using the Video API with a Vonage application (instead of an OpenTok project), pass in the application ID (not an OpenTok API key) for this parameter.

Parameters:
Name Type Description
apiKey NSString * Your OpenTok API key.
sessionId NSString * The session ID of this instance.
delegate id&lt;OTSessionDelegate&gt; The delegate (OTSessionDelegate) object for the session.
settings OTSessionSettings * The (OTSessionSettings) object that defines settings for the session.
Returns:

connectWithToken:error:(token, error)

Once your application has a valid token, connect with your API key to begin participating in an OpenTok session.

When the session connects successfully, the [OTSessionDelegate sessionDidConnect:] message is sent to the session's delegate.

If the session cannot connect, the [OTSessionDelegate session:didFailWithError:] message is sent to the session's delegate.

When the session disconnects, the [OTSessionDelegate sessionDidDisconnect:] message is sent to the session's delegate.

Note that sessions automatically disconnect when the app is suspended.

Be sure to set up a delegate method for the [OTSessionDelegate session:didFailWithError:] message.

If an asynchronous error occurs, the [OTSessionDelegate session:didFailWithError:] message is sent to the session's delegate.

Parameters:
Name Type Description
token NSString * The token generated for this connection.
error OTError * * Set if an error occurs synchronously while processing the request. The OTSessionErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no synchronous error occurs.

disconnect:(error)

Disconnect from an active OpenTok session.

This method tears down all OTPublisher and OTSubscriber objects that have been initialized.

As a best practice, before calling this method, call the [OTSession unpublish:error:]> method for all publishers and wait for the [OTPublisherKitDelegate publisher:streamDestroyed:] message. 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 [OTSessionDelegate sessionDidDisconnect:] message is sent to the session's delegate.

Parameters:
Name Type Description
error OTError * * Set if an error occurs synchronously while processing the request. The OTSessionErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no error occurs.

disconnect()

publish:error:(publisher, error)

Adds a publisher to the session.

When the publisher begins streaming data, the [OTPublisherKitDelegate publisher:streamCreated:] message is sent to the publisher delegate delegate.

If publishing fails, [OTPublisherKitDelegate publisher:didFailWithError:] is sent to the publisher delegate and no session delegate message will be passed.

Note that multiple publishers are not supported.

If an asynchronous error occurs, the [OTPublisherKitDelegate publisher:didFailWithError:] message is sent to the publisher's delegate.

Parameters:
Name Type Description
publisher OTPublisherKit * The OTPublisherKit object to stream with.
error OTError * * Set if an error occurs synchronously while processing the request. The OTPublisherErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no error occurs.

publish:(publisher)

Parameters:
Name Type Description
publisher OTPublisherKit *

unpublish:error:(publisher, error)

Removes a publisher from the session.

Upon removing the publisher, the [OTPublisherKitDelegate publisher:streamDestroyed:] message is sent to the publisher delegate after streaming has stopped.

Parameters:
Name Type Description
publisher OTPublisherKit * The OTPublisher object to remove from the session.
error OTError * * Set if an error occurs synchronously while processing the request. The OTPublisherErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no error occurs.

unpublish:(publisher)

Parameters:
Name Type Description
publisher OTPublisherKit *

subscribe:error:(subscriber, error)

Connects this subscriber instance to the session and begins subscribing. If the subscriber passed is created from an OTStream instance from a different OTSession instance, the behavior of this function is undefined.

If an asynchronous error occurs, the [OTSubscriberKitDelegate subscriber:didFailWithError:] message is sent to the subscriber's delegate.

Parameters:
Name Type Description
subscriber OTSubscriberKit * The subscriber to connect and begin subscribing.
error OTError * * Set if an error occurs synchronously while processing the request. The OTSubscriberErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no error occurs.

subscribe:(subscriber)

Parameters:
Name Type Description
subscriber OTSubscriberKit *

unsubscribe:error:(subscriber, error)

Disconnects this subscriber instance from the session and begins object cleanup.

Parameters:
Name Type Description
subscriber OTSubscriberKit * The subscriber to disconnect and remove from this session.
error OTError * * Set if an error occurs synchronously while processing the request. The OTSubscriberErrorCode enum (defined in the OTError.h file) defines values for the code property of this object. This object is NULL if no error occurs.

unsubscribe:(subscriber)

Parameters:
Name Type Description
subscriber OTSubscriberKit *

signalWithType:string:connection:error:(type, string, connection, error)

Sends a signal to one or more clients in a session.

See [OTSession signalWithType:string:connection:retryAfterReconnect:error:] and [OTSessionDelegate session:receivedSignalType:fromConnection:withString:].

Parameters:
Name Type Description
type NSString * The type of the signal. The type is also set in the [OTSessionDelegate session:receivedSignalType:fromConnection:withString:] message. The maximum length of the type string is 128 characters, and it must contain only letters (A-Z and a-z), numbers (0-9), "-", "_", and "~".
string NSString * The data to send. The limit to the size of data is 8KB.
connection OTConnection * A destination OTConnection object. Set this parameter to nil to signal all participants in the session.
error OTError * * If sending a signal fails, this value is set to an OTError object. The OTSessionErrorCode enum (in OTError.h) includes OTSessionInvalidSignalType and OTSessionSignalDataTooLong constants for these errors. Note that success indicates that the options passed into the method are valid and the signal was sent. It does not indicate that the signal was sucessfully received by any of the intended recipients.

signalWithType:string:connection:retryAfterReconnect:error:(type, string, connection, retryAfterReconnect, error)

Sends a signal to one or more clients in a session. This version of the method includes a retryAfterReconnect parameter.

See [OTSession signalWithType:string:connection:retryAfterReconnect:error:], [OTSessionDelegate session:receivedSignalType:fromConnection:withString:], and [OTSessionDelegate sessionDidBeginReconnecting:].

Parameters:
Name Type Description
type NSString * The type of the signal. The type is also set in the [OTSessionDelegate session:receivedSignalType:fromConnection:withString:] message. The maximum length of the type string is 128 characters, and it must contain only letters (A-Z and a-z), numbers (0-9), "-", "_", and "~".
string NSString * The data to send. The limit to the size of data is 8KB.
connection OTConnection * A destination OTConnection object. Set this parameter to nil to signal all participants in the session.
retryAfterReconnect BOOL Upon reconnecting to the session, whether to send any signals that were initiated while disconnected. If your client loses its connection to the OpenTok session, due to a drop in network connectivity, the client attempts to reconnect to the session, and the [OTSessionDelegate sessionDidBeginReconnecting:] message is sent. By default, signals initiated while disconnected are sent when (and if) the client reconnects to the OpenTok session. You can prevent this by setting the retryAfterReconnect parameter to false. (The default value is true.)
error OTError * * If sending a signal fails, this value is set to an OTError object. The OTSessionErrorCode enum (in OTError.h) includes OTSessionInvalidSignalType and OTSessionSignalDataTooLong constants for these errors. Note that success indicates that the options passed into the method are valid and the signal was sent. It does not indicate that the signal was sucessfully received by any of the intended recipients.

forceMuteAll:error:(excludedStreams, error)

Forces all publishers in the session (except for those publishing excluded streams) to mute audio.

Also, any streams that are published after the call to the [OTSession forceMuteAll:error:]> method are published with audio muted. You can remove the mute state of a session by calling the [OTSession disableForceMute:] method. After you call the [OTSession disableForceMute:] method, new streams published to the session will no longer have audio muted.

Calling this method causes the OTSessionDelegate session:muteForced:muteForcedInfo message to be sent in each client connected to the session, with the active property of the muteForcedInfo object set to YES.

Check the canForceMute property of the [OTSession 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 [OTSession forceMuteStream:error:], [OTSession capabilities], [OTSessionDelegate session:muteForced:], [OTPublisherKitDelegate muteForced:], and Muting the audio of streams in a session.

Parameters:
Name Type Description
excludedStreams NSArray<OTStream *> * Streams to be exclued from the mute request. Set this to null to mute all streams in the session (including those published by the local client).
error OTError * * If the action fails, this value is set to an OTError object. Note that success indicates that the options passed into the method are valid and the request to mute streams was sent. It does not indicate that the request was successfully acted upon by the target clients.

disableForceMute:(error)

Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.

After you call the [OTSession forceMuteAll:error:] 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 OTSessionDelegate session:muteForced:muteForcedInfo message to be sent in each client connected to the session, with the active property of the muteForcedInfo object set to NO.

Check the canForceMute property of the [OTSession 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 [OTSession forceMuteAll:error:], [OTSession capabilities], [OTSessionDelegate session:muteForced:], and Muting the audio of streams in a session.

Parameters:
Name Type Description
error OTError * * If the action fails, this is set to an OTError object.

forceMuteStream:error:(stream, error)

Forces the publisher of a specified stream to mute its audio.

Check the canForceMute property of the [OTSession 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 [OTSession forceMuteAll:error:], [OTSession capabilities], [OTSessionDelegate session:muteForced:], [OTPublisherKitDelegate muteForced:], and Muting the audio of streams in a session.

Parameters:
Name Type Description
stream OTStream * The stream to be muted.
error OTError * * If the action fails, this value is set to an OTError object. Note that success indicates that the options passed into the method are valid and the request to mute streams was sent. It does not indicate that the request was successfully acted upon by the target clients.

forceDisconnect:error:(connection, error)

Forces a client to disconnect from the session.

While you can use the [OTSession forceDisconnect:error:] method to terminate your own connection, calling the [OTSession disconnect:] method is simpler. An error is returned if the client's role does not include permissions required to force other users to disconnect. You define a client's role when you create the user token. When a connection is terminated using this method , [OTSessionDelegate sessionDidDisconnect:], [OTSessionDelegate session:connectionDestroyed:] and [OTPublisherKitDelegate publisher:streamDestroyed:] messages are dispatched in the same way as they would be if the connection had terminated itself using [OTSession disconnect:]

Parameters:
Name Type Description
connection OTConnection * The OTConnection to disconnect.
error OTError * * If force disconnect fails, this value is set to an OTError object. The OTSessionErrorCode enum (in OTError.h) includes OTSessionUnableToForceDisconnect for these errors.

reportIssue:(issueId)

Report that your app experienced an issue. You can use the issue ID with the Inspector or when discussing an issue with the Vonage Video API support team.

Parameters:
Name Type Description
issueId NSString * * A pointer to a string that will be set the unique identifier for the reported issue. If the call to the method fails (for example, because of no network connection), this value is set to nil.

setEncryptionSecret:error:(secret, error)

Sets the end-to-end encryption secret used by all publishers and subscribers.

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 reports OTSessionEncryptionNotEnabled 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 nil 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 OTSessionInvalidEncryptionSecret is reported.

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 NSString * Value of the encryption secret, or nil or an empty string to reset the previously set encryption secret.
error OTError * * If the action fails, this parameter is set to an OTError object.

init() → {instancetype}

Returns: