OTSession Class Reference
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.
Getting information about the session
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
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
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
capabilities
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.
@property (readonly) OTSessionCapabilities *capabilities
Declared In
OTSession.h
Initializing and connecting to a session
– 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:(NSString *)apiKey sessionId:(NSString *)sessionId delegate:(id<OTSessionDelegate>)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
– connectWithToken:error:
Once your application has a valid token, connect with your API key to begin participating in an OpenTok session.
- (void)connectWithToken:(NSString *)token error:(OTError **)error
Parameters
token |
The token generated for this connection. |
---|---|
error |
Set if an error occurs synchronously while processing the
request. The 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:(OTError **)error
Parameters
error |
Set if an error occurs synchronously while processing the
request. The |
---|
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
Publishing audio-video streams to a session
– publish:error:
Adds a publisher to the session.
- (void)publish:(OTPublisherKit *)publisher error:(OTError **)error
Parameters
publisher |
The OTPublisherKit object to stream with. |
---|---|
error |
Set if an error occurs synchronously while processing the
request. The 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
– unpublish:error:
Removes a publisher from the session.
- (void)unpublish:(OTPublisherKit *)publisher error:(OTError **)error
Parameters
publisher |
The OTPublisher object to remove from the session. |
---|---|
error |
Set if an error occurs synchronously while processing the
request. The |
Discussion
Upon removing the publisher, the [OTPublisherKitDelegate publisher:streamDestroyed:] message is sent to the publisher delegate after streaming has stopped.
Declared In
OTSession.h
Subscribing to audio-video streams
– 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:(OTSubscriberKit *)subscriber error:(OTError **)error
Parameters
subscriber |
The subscriber to connect and begin subscribing. |
---|---|
error |
Set if an error occurs synchronously while processing the
request. The If an asynchronous error occurs, the [OTSubscriberKitDelegate subscriber:didFailWithError:] message is sent to the subscriber’s delegate. |
Declared In
OTSession.h
– unsubscribe:error:
Disconnects this subscriber instance from the session and begins object cleanup.
- (void)unsubscribe:(OTSubscriberKit *)subscriber error:(OTError **)error
Parameters
subscriber |
The subscriber to disconnect and remove from this session. |
---|---|
error |
Set if an error occurs synchronously while processing the
request. The |
Declared In
OTSession.h
Sending and receiving signals in a session
– signalWithType:string:connection:error:
Sends a signal to one or more clients in a session.
- (void)signalWithType:(NSString *)type string:(NSString *)string connection:(OTConnection *)connection error:(OTError **)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
See [OTSession signalWithType:string:connection:retryAfterReconnect:error:] and [OTSessionDelegate session:receivedSignalType:fromConnection:withString:].
Declared In
OTSession.h
– signalWithType:string:connection:retryAfterReconnect:error:
Sends a signal to one or more clients in a session. This version of the method
includes a retryAfterReconnect
parameter.
- (void)signalWithType:(NSString *)type string:(NSString *)string connection:(OTConnection *)connection retryAfterReconnect:(BOOL)retryAfterReconnect error:(OTError **)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 “~”. See [OTSession signalWithType:string:connection:retryAfterReconnect:error:], [OTSessionDelegate session:receivedSignalType:fromConnection:withString:], and [OTSessionDelegate sessionDidBeginReconnecting:]. |
---|---|
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. |
retryAfterReconnect |
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 |
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. |
Declared In
OTSession.h
Reporting an issue
– reportIssue:
Report that your app experienced an issue. You can use the issue ID with the Inspector or when discussing an issue with the TokBox support team.
- (void)reportIssue:(NSString **)issueId
Parameters
issueId |
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. |
---|
Declared In
OTSession.h