Inherits from NSObject
Declared in OTSession.h

Overview

The first step in using the OpenTok iOS SDK is to initialize an OTSession object with 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

Properties

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

connectionCount

The number of discrete clients connected to this session. Individual iOS clients connect to a session by sending the [OTSession connectWithApiKey:token:] message.

@property (readonly) int connectionCount

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, weak) 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:

  • OTSessionConnectionStatusConnected – The session is connected.
  • OTSessionConnectionStatusConnecting – The session is connecting.
  • OTSessionConnectionStatusDisconnected – The session is not connected.
  • OTSessionConnectionStatusFailed – The attempt to connect to the session failed.

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

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. Once initialized, this is an immutable value.

@property (nonatomic, copy) 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

connectWithApiKey:token:

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

- (void)connectWithApiKey:(NSString *)apiKey token:(NSString *)token

Parameters

apiKey

Your OpenTok API key.

token

The token generated for this connection.

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. See the OTSessionErrorCode emum defined in OTError.h. It defines code values for the error. An error with code OTSDKUpdateRequired indicates that the OpenTok iOS SDK used to compile the app is not longer compatible with the OpenTok infrastructure.

Declared In

OTSession.h

disconnect

Disconnect from an active OpenTok session.

- (void)disconnect

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

initWithSessionId:delegate:

Initialize this session with a given session ID and delegate before connecting to OpenTok. Send the [OTSession connectWithApiKey:token:] message to connect to the session.

- (id)initWithSessionId:(NSString *)sessionId delegate:(id<OTSessionDelegate>)delegate

Parameters

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:

Adds a publisher to the session.

- (void)publish:(OTPublisher *)publisher

Parameters

publisher

The OTPublisher object for the stream to be published.

Discussion

When the publisher begins streaming data, the [OTSessionDelegate session:didReceiveStream:] message is sent to the session’s delegate. You can compare the connection.connectionId property of the OTSession object with the connection.connectionId property of the OTStream object. If they match, the stream is published from your connection.

Also, when the publisher begins streaming data the [OTPublisherDelegate publisherDidStartStreaming:] message is sent to the publisher’s delegate.

If publishing fails, the [OTPublisherDelegate publisher:didFailWithError:] is sent to the publisher’s delegate.

When running in the XCode iOS Simulator, the [OTPublisher initWithDelegate:] and [OTPublisher initWithDelegate:name:] methods return nil. Sending the [OTSession publish:] message to nil results in no operation.

Note that multiple publishers are not supported.

Declared In

OTSession.h

unpublish:

Removes a publisher from the session.

- (void)unpublish:(OTPublisher *)publisher

Parameters

publisher

The OTPublisher object to remove from the session.

Discussion

Upon removing the publisher, the [OTPublisherDelegate publisherDidStopStreaming:] message is sent to the publisher’s delegate. The publisher’s view is removed from its superview. Also, the [OTSessionDelegate session:didDropStream:] message is sent to the session’s delegate.

Declared In

OTSession.h