Inherits from NSObject
Declared in OTSession.h

Overview

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

Tasks

Getting information about the session

Initializing and connecting to a session

Publishing audio-video streams to a session

Sending and receiving signals in a session

Properties

apiQueue

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.

@property (nonatomic, assign) dispatch_queue_t apiQueue

Declared In

OTSession.h

connection

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.

@property (readonly) OTConnection *connection

Declared In

OTSession.h

delegate

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

@property (nonatomic, assign) id<OTSessionDelegate> delegate

Declared In

OTSession.h

sessionConnectionStatus

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

@property (readonly) OTSessionConnectionStatus sessionConnectionStatus

Discussion

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.

Declared In

OTSession.h

sessionId

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

@property (readonly) NSString *sessionId

Declared In

OTSession.h

streams

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

@property (readonly) NSDictionary *streams

Declared In

OTSession.h

Instance Methods

connectWithToken:error:

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

- (void)connectWithToken:(id)token error:(id)error

Parameters

token

The token generated for this connection.

error

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.

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

Discussion

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.

Declared In

OTSession.h

disconnect:

Disconnect from an active OpenTok session.

- (void)disconnect:(id)error

Parameters

error

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.

Discussion

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

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

Declared In

OTSession.h

initWithApiKey:sessionId:delegate:

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.

- (id)initWithApiKey:(id)apiKey sessionId:(id)sessionId delegate:(id)delegate

Parameters

apiKey

Your OpenTok API key.

sessionId

The session ID of this instance.

delegate

The delegate (OTSessionDelegate) that handles messages on behalf of this session.

Return Value

The OTSession object, or nil if initialization fails.

Declared In

OTSession.h

publish:error:

Adds a publisher to the session.

- (void)publish:(id)publisher error:(id)error

Parameters

publisher

The OTPublisherKit object to stream with.

error

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.

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

Discussion

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.

Declared In

OTSession.h

signalWithType:string:connection:error:

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

- (void)signalWithType:(id)type string:(id)string connection:(id)connection error:(id)error

Parameters

type

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

The data to send. The limit to the size of data is 8KB.

connection

A destination OTConnection object. Set this parameter to nil to signal all participants in the session.

error

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.

Discussion

For information on charges for signaling, see the OpenTok pricing page.

See [OTSessionDelegate session:receivedSignalType:fromConnection:withString:].

Declared In

OTSession.h

subscribe: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.

- (void)subscribe:(id)subscriber error:(id)error

Parameters

subscriber

The subscriber to connect and begin subscribing.

error

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.

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

Declared In

OTSession.h

unpublish:error:

Removes a publisher from the session.

- (void)unpublish:(id)publisher error:(id)error

Parameters

publisher

The OTPublisher object to remove from the session.

error

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.

Discussion

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

Declared In

OTSession.h

unsubscribe:error:

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

- (void)unsubscribe:(id)subscriber error:(id)error

Parameters

subscriber

The subscriber to disconnect and remove from this session.

error

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.

Declared In

OTSession.h