public class Session
extends java.lang.Object
When you create the Session instance, you pass in the OpenTok session ID, token, and API key. You get an API key when you sign up for an OpenTok account. For test purposes, you can generate test session IDs and tokens by logging in to your TokBox account. Use the OpenTok server-side libraries to generate session IDs and tokens in your shipping app.
Modifier and Type | Class and Description |
---|---|
static interface |
Session.ArchiveListener
Monitors when an archive recording of the session starts and stops.
|
static class |
Session.Builder |
static class |
Session.Capabilities
Defines the value returned by the
getCapabilities() method. |
protected static class |
Session.ConfigurableSessionOptions |
static interface |
Session.ConnectionListener
Monitors when other clients connect and disconnect to the session.
|
static interface |
Session.ReconnectionListener
Monitors when an a client tries to automatically reconnect after losing its connection to an
OpenTok session.
|
static interface |
Session.SessionListener
Monitors state changes in a
Session object. |
static class |
Session.SessionOptions
A base class for defining advanced session options with the
Session.Builder.sessionOptions(Session.SessionOptions sessionOptions) method. |
static interface |
Session.SessionOptionsProvider
Deprecated.
|
static interface |
Session.SignalListener
Monitors when a signal is sent in the session.
|
static interface |
Session.StreamPropertiesListener
Monitors when properties of streams in the session change.
|
Modifier and Type | Field and Description |
---|---|
protected java.lang.String |
apiKey |
protected Session.ArchiveListener |
archiveListener |
protected Connection |
connection |
protected boolean |
connectionEventsSuppressed |
protected Session.ConnectionListener |
connectionListener |
protected boolean |
ipWhitelist |
protected Session.ReconnectionListener |
reconnectionListener |
protected java.lang.String |
sessionId |
protected Session.SessionListener |
sessionListener |
protected Session.SignalListener |
signalListener |
protected Session.StreamPropertiesListener |
streamPropertiesListener |
Modifier | Constructor and Description |
---|---|
|
Session(android.content.Context context,
java.lang.String apiKey,
java.lang.String sessionId)
Deprecated.
|
protected |
Session(android.content.Context context,
java.lang.String apiKey,
java.lang.String sessionId,
boolean connectionEventsSuppressed,
Session.SessionOptions sessionOptions,
Session.Builder.TransportPolicy routing,
Session.Builder.IncludeServers turnConfig,
Session.Builder.IceServer[] iceServers,
java.net.URL apiUrl,
boolean ipWhitelist,
java.lang.String proxyUrl) |
|
Session(android.content.Context context,
java.lang.String apiKey,
java.lang.String sessionId,
Session.SessionOptions sessionOptions)
Deprecated.
|
|
Session(android.content.Context context,
java.lang.String apiKey,
java.lang.String sessionId,
Session.SessionOptionsProvider optionsProvider)
Deprecated.
|
Modifier and Type | Method and Description |
---|---|
void |
connect(java.lang.String token)
Connects to the OpenTok session provided in the Session constructor, using the
provided authentication token.
|
void |
disconnect()
Disconnects from this session.
|
protected void |
finalize() |
Session.Capabilities |
getCapabilities()
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.
|
Connection |
getConnection()
Returns the
Connection corresponding to this client's connection
to this Session. |
java.lang.String |
getSessionId()
Returns the Session ID passed in during instantiation.
|
protected void |
onArchiveStarted(java.lang.String id,
java.lang.String name)
Called when an archive of the session starts recording.
|
protected void |
onArchiveStopped(java.lang.String id)
Called when an archive of the session stops being recorded.
|
protected void |
onConnected()
Invoked when the client connects to the OpenTok session.
|
protected void |
onConnectionCreated(Connection connection)
Invoked when another client connects to the session.
|
protected void |
onConnectionDestroyed(Connection connection)
Invoked when another client leaves the session.
|
protected void |
onDisconnected()
Invoked when the client is no longer connected to the OpenTok
session.
|
protected void |
onError(OpentokError error)
Invoked when something goes wrong when connecting or connected to the
session.
|
void |
onPause()
Call this method when the app's activity pauses.
|
protected void |
onReconnected()
Invoked when the local client has reconnected to the OpenTok session after its
network connection was lost temporarily.
|
protected void |
onReconnecting()
Invoked when the local client has lost its connection to an OpenTok session and is trying
to reconnect.
|
void |
onResume()
Call this method when the app's activity resumes.
|
void |
onSignalReceived(java.lang.String type,
java.lang.String data,
Connection connection)
Called when a signal is received in the session.
|
protected void |
onStreamDropped(Stream stream)
Invoked when another client stops publishing a stream to this
OpenTok session.
|
protected void |
onStreamHasAudioChanged(Stream stream,
int hasAudio)
Called when a stream in the session changes between having audio and
not having audio.
|
protected void |
onStreamHasVideoChanged(Stream stream,
int hasVideo)
Called when a stream in the session changes between having video and
not having video.
|
protected void |
onStreamReceived(Stream stream)
Invoked when a there is a new stream published by another
client in this OpenTok session.
|
protected void |
onStreamVideoDimensionsChanged(Stream stream,
int width,
int height)
Called when the video dimensions of a stream in the session change.
|
protected void |
onStreamVideoTypeChanged(Stream stream,
Stream.StreamVideoType videoType)
Called when the video type of a stream in the session change.
|
void |
publish(PublisherKit publisher)
Starts a Publisher streaming to the session.
|
java.lang.String |
reportIssue()
Report that your app experienced an issue.
|
void |
sendSignal(java.lang.String type,
java.lang.String data)
Sends a signal to all clients in a session.
|
void |
sendSignal(java.lang.String type,
java.lang.String data,
boolean retryAfterReconnect)
Sends a signal to all clients in a session.
|
void |
sendSignal(java.lang.String type,
java.lang.String data,
Connection connection)
Sends a signal to a specific client in a session.
|
void |
sendSignal(java.lang.String type,
java.lang.String data,
Connection connection,
boolean retryAfterReconnect)
Sends a signal to a specific client in a session.This version of the method includes
a
retryAfterReconnect parameter. |
void |
setArchiveListener(Session.ArchiveListener listener)
Sets an
Session.ArchiveListener object to monitor when an archive recording
starts or stops in this session. |
void |
setConnectionListener(Session.ConnectionListener listener)
Sets a
Session.ConnectionListener object to monitor when other clients
connect and disconnect from this session. |
void |
setReconnectionListener(Session.ReconnectionListener listener)
Sets a
Session.ReconnectionListener object to be notified when the client is
attempting to reconnect or reconnected to an OpenTok session. |
void |
setSessionListener(Session.SessionListener listener)
Sets a
Session.SessionListener object to monitor state changes for this
Session object. |
void |
setSignalListener(Session.SignalListener listener)
Sets a
Session.SignalListener object to monitor when signals are
sent in this session. |
void |
setStreamPropertiesListener(Session.StreamPropertiesListener listener)
Sets a
Session.StreamPropertiesListener object to monitor properties
of streams in this session change. |
void |
subscribe(SubscriberKit subscriber)
Start receiving and rendering audio-video stream data for the specified
subscriber.
|
void |
unpublish(PublisherKit publisher)
Disconnects the Publisher from the session.
|
void |
unsubscribe(SubscriberKit subscriber)
Stops subscribing (receiving a stream) to a specified subscriber in the
session.
|
protected Session.SessionListener sessionListener
protected Session.ConnectionListener connectionListener
protected Session.StreamPropertiesListener streamPropertiesListener
protected Session.SignalListener signalListener
protected Session.ArchiveListener archiveListener
protected Session.ReconnectionListener reconnectionListener
protected java.lang.String apiKey
protected java.lang.String sessionId
protected boolean connectionEventsSuppressed
protected boolean ipWhitelist
protected Connection connection
@Deprecated public Session(android.content.Context context, java.lang.String apiKey, java.lang.String sessionId)
Session.Builder
instead.context
- The Android application context associated with this process.apiKey
- Your OpenTok API key. See the your
TokBox account page.sessionId
- The OpenTok session ID this instance should connect to. For
test purposes, you can generate test session by logging into your
TokBox account.
Use the OpenTok
server-side SDKs to generate session IDs in your shipping
app.setSessionListener(com.opentok.android.Session.SessionListener)
@Deprecated public Session(android.content.Context context, java.lang.String apiKey, java.lang.String sessionId, Session.SessionOptionsProvider optionsProvider)
This constructor is deprecated. Use the Session.Builder
instead and call the
Session.Builder.sessionOptions(Session.SessionOptions sessionOptions)
method.
context
- The Android application context associated with this process.apiKey
- Your OpenTok API key. See your
TokBox account page.sessionId
- The OpenTok session ID this instance should connect to. For
test purposes, you can generate test session by logging onto your
TokBox account page.
Use the OpenTok
server-side SDKs to generate session IDs in your shipping
app.optionsProvider
- The object that implements the SessionOptionsProvider interface.setSessionListener(com.opentok.android.Session.SessionListener)
@Deprecated public Session(android.content.Context context, java.lang.String apiKey, java.lang.String sessionId, Session.SessionOptions sessionOptions)
Session.Builder
instead.context
- The Android application context associated with this process.apiKey
- Your OpenTok API key. See your
TokBox account page.sessionId
- The OpenTok session ID this instance should connect to. For
test purposes, you can generate test session by logging onto your
TokBox account page.
Use the OpenTok
server-side SDKs to generate session IDs in your shipping
app.sessionOptions
- The object that inherits from SessionOptions object.setSessionListener(com.opentok.android.Session.SessionListener)
protected Session(android.content.Context context, java.lang.String apiKey, java.lang.String sessionId, boolean connectionEventsSuppressed, Session.SessionOptions sessionOptions, Session.Builder.TransportPolicy routing, Session.Builder.IncludeServers turnConfig, Session.Builder.IceServer[] iceServers, java.net.URL apiUrl, boolean ipWhitelist, java.lang.String proxyUrl)
public Connection getConnection()
Connection
corresponding to this client's connection
to this Session.
When a Stream is created, the
Session.SessionListener.onStreamReceived(Session session, Stream stream)
method is called. Compare the Connection object returned by the
Stream.getConnection()
method with the Connection object returned
by Sesssion.getConnection()
to see if the new stream is published
by your client.
Session.SessionListener.onConnected(Session session)
,
Session.SessionListener.onStreamReceived(Session session, Stream
stream)
,
Stream.getConnection()
public java.lang.String getSessionId()
public void setSessionListener(Session.SessionListener listener)
Session.SessionListener
object to monitor state changes for this
Session object.listener
- The Session.SessionListener
instance.public void setConnectionListener(Session.ConnectionListener listener)
Session.ConnectionListener
object to monitor when other clients
connect and disconnect from this session.listener
- The Session.ConnectionListener
instance.public void setStreamPropertiesListener(Session.StreamPropertiesListener listener)
Session.StreamPropertiesListener
object to monitor properties
of streams in this session change. These include properties indicating whether
the stream has audio, whether it has video video, and its video dimensions.listener
- The Session.StreamPropertiesListener
instance.public void setSignalListener(Session.SignalListener listener)
Session.SignalListener
object to monitor when signals are
sent in this session.listener
- The Session.SignalListener
instance.public void setArchiveListener(Session.ArchiveListener listener)
Session.ArchiveListener
object to monitor when an archive recording
starts or stops in this session.listener
- The Session.ArchiveListener
instance.public void setReconnectionListener(Session.ReconnectionListener listener)
Session.ReconnectionListener
object to be notified when the client is
attempting to reconnect or reconnected to an OpenTok session.listener
- The Session.ReconnectionListener
instance.public void connect(java.lang.String token)
When the session connects, the
Session.SessionListener.onConnected(Session session)
method is
called.
If the session fails to connect, the
Session.SessionListener.onError(Session session, OpentokError error)
method is called.
token
- The token for the user. See Token
Creation Overview.public void disconnect()
When the session disconnects, the
Session.SessionListener.onDisconnected(Session session)
method is
called.
public void onPause()
Cameras used by OpenTok publishers are now released when you call this method.
Publishers reacquire cameras when you call the onResume()
method.
public void onResume()
Any cameras (used by OpenTok publishers) which were released when you
called the onPause()
method are reacquired when you call
Session.onResume()
.
public void publish(PublisherKit publisher)
publisher
- The Publisher that you want to stream to the session.public void unpublish(PublisherKit publisher)
publisher
- The Publisher to unpublish.public void subscribe(SubscriberKit subscriber)
subscriber
- The subscriber bound to the stream to be received.public void unsubscribe(SubscriberKit subscriber)
subscriber
- The Subcriber you want to stop subscribing to.public void sendSignal(java.lang.String type, java.lang.String data)
type
- The type of the signal. The type is also set in the
Session.SignalListener.onSignalReceived(Session session, String type,
String data, Connection connection)
method.data
- The data to send. The limit to the size of data is 8kB.sendSignal(String type, String data, Connection connection)
,
sendSignal(String type, String data, boolean retryAfterReconnect)
,
Session.SignalListener.onSignalReceived(Session session, String
type, String data, Connection connection)
public void sendSignal(java.lang.String type, java.lang.String data, boolean retryAfterReconnect)
retryAfterReconnect
parameter.type
- The type of the signal. The type is also set in the
Session.SignalListener.onSignalReceived(Session session,
String type, String data, Connection connection)
method.data
- The data to send. The limit to the size of data is 8kB.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
Session.ReconnectionListener.onReconnecting(Session session)
method
is called. 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
.)sendSignal(String type, String data)
,
Session.ReconnectionListener.onReconnecting(Session session)
,
Session.SignalListener.onSignalReceived(Session session, String
type, String data, Connection connection)
public void sendSignal(java.lang.String type, java.lang.String data, Connection connection)
type
- The type of the signal. The type is also set in the
Session.SignalListener.onSignalReceived(Session session, String type,
String data, Connection connection)
method.data
- The data to send. The limit to the size of data is 8kB.connection
- A Connection object. The Connection object represents the
connection of a client to the session. This is the client to
which the message is sent. (See
Session.ConnectionListener.onConnectionCreated(Session session,
Connection connection)
and Connection
.sendSignal(String type, String data)
,
sendSignal(String type, String data, Connection connection, boolean retryAfterReconnect)
,
Session.SignalListener.onSignalReceived(Session session, String
type, String data, Connection connection)
public void sendSignal(java.lang.String type, java.lang.String data, Connection connection, boolean retryAfterReconnect)
retryAfterReconnect
parameter.type
- The type of the signal. The type is also set in the
Session.SignalListener.onSignalReceived(Session session,
String type, String data, Connection connection)
method.data
- The data to send. The limit to the size of data is 8kB.connection
- A Connection object. The Connection object represents the
connection of a client to the session. This is the client to
which the message is sent. (See
Session.ConnectionListener.onConnectionCreated(Session session,
Connection connection)
and Connection
.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
Session.ReconnectionListener.onReconnecting(Session session)
method
is called. 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
.)sendSignal(String type, String data)
,
sendSignal(String type, String data, Connection connection)
,
sendSignal(String type, String data, boolean retryAfterReconnect)
,
Session.SignalListener.onSignalReceived(Session session, String
type, String data, Connection connection)
public Session.Capabilities getCapabilities()
null
until you have connected to a session and the
Session.SessionListener.onConnected(Session session)
method has been called.public java.lang.String reportIssue()
protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
protected void onArchiveStarted(java.lang.String id, java.lang.String name)
If you extend the Session class, you can override this method instead of the
onArchiveStarted()
method of the Session.ArchiveListener
interface.
id
- The unique ID of the archive.name
- The name of the archive (if one was provided when the archive was created).protected void onArchiveStopped(java.lang.String id)
If you extend the Session class, you can override this method instead of the
onArchiveStopped()
method of the Session.ArchiveListener
interface.
id
- The unique ID of the archive.protected void onStreamHasAudioChanged(Stream stream, int hasAudio)
If you extend the Session class, you can override this method instead of the
onStreamHasAudioChanged()
method of the Session.StreamPropertiesListener
interface.
stream
- The stream.hasAudio
- Whether the stream has audio (true
) or not (
false
).protected void onStreamHasVideoChanged(Stream stream, int hasVideo)
If you extend the Session class, you can override this method instead of the
onStreamHasVideoChanged()
method of the Session.StreamPropertiesListener
interface.
stream
- The stream.hasVideo
- Whether the stream has video (true
) or not (
false
).protected void onStreamVideoDimensionsChanged(Stream stream, int width, int height)
If you extend the Session class, you can override this method instead of the
onStreamVideoDimensionsChanged()
method of the Session.StreamPropertiesListener
interface.
stream
- The stream.width
- The new width of the stream, in pixels.height
- The new height of the stream, in pixels.protected void onStreamVideoTypeChanged(Stream stream, Stream.StreamVideoType videoType)
If you extend the Session class, you can override this method instead of the
onStreamVideoTypeChanged()
method of the Session.StreamPropertiesListener
interface.
stream
- The stream.videoType
- The new video type of the stream.protected void onConnectionCreated(Connection connection)
Session.SessionListener.onConnected(Session session)
method
is called.
If you extend the Session class, you can override this method instead of the
onConnectionCreated()
method of the Session.ConnectionListener
interface.
connection
- The new connection in the session.protected void onConnectionDestroyed(Connection connection)
Session.SessionListener.onDisconnected(Session session)
method is called.
If you extend the Session class, you can override this method instead of the
onConnectionDestroyed()
method of the Session.ConnectionListener
interface.
connection
- The connection that left the session the session.public void onSignalReceived(java.lang.String type, java.lang.String data, Connection connection)
If you extend the Session class, you can override this method instead of the
onSignalReceived()
method of the Session.SignalListener
interface.
type
- The type string of the signal.data
- The signal data.connection
- The connection identifying the client that sent the
message. This value can be null
.protected void onReconnecting()
Session.ReconnectionListener.onReconnected(Session session)
method is called.
Otherwise, if the client cannot reconnect, the
Session.SessionListener.onDisconnected(Session session)
method is called.
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.
If you extend the Session class, you can override this method instead of the
onReconnecting()
method of the Session.ReconnectionListener
interface.
onReconnected()
protected void onReconnected()
Session.ReconnectionListener.onReconnecting(Session session)
method is called,
prior to the Session.ReconnectionListener.onReconnected(Session session)
method. If the client cannot reconnect to the session, the
Session.SessionListener.onDisconnected(Session session)
method is called.
Any existing publishers and subscribers are automatically reconnected when the client reconnects and this method is called.
By default, any signals initiated by the the local client using the
sendSignal(String type, String data)
method are sent when the client
reconnects. To prevent any signals initiated while disconnected from being sent,
use the sendSignal(String type, String data, boolean retryAfterReconnect)
method to send the signal, and set the retryAfterReconnect
parameter to
false
. (All signals sent by other clients while your client was disconnected
are received upon reconnecting.)
If you extend the Session class, you can override this method instead of the
onReconnected()
method of the Session.ReconnectionListener
interface.
onReconnecting()
protected void onConnected()
If you extend the Session class, you can override this method instead of the
onConnected()
method of the Session.SessionListener
interface.
protected void onDisconnected()
If you extend the Session class, you can override this method instead of the
onDisconnected()
method of the Session.SessionListener
interface.
protected void onStreamReceived(Stream stream)
If you extend the Session class, you can override this method instead of the
onStreamReceived()
method of the Session.SessionListener
interface.
stream
- A Stream object representing the new stream, which can be
used to create a Subscriber.protected void onStreamDropped(Stream stream)
If you extend the Session class, you can override this method instead of the
onStreamDropped()
method of the Session.SessionListener
interface.
stream
- A Stream object representing the dropped stream, which can
be used to identify a Subscriber.protected void onError(OpentokError error)
This method is called if the attempt to connect to the session fails.
It is also called if the connection to the session drops due to an error after
a successful connection, and in this case the method is called just before
the Session.SessionListener.onDisconnected(Session session)
method is called.
If you extend the Session class, you can override this method instead of the
onError()
method of the Session.SessionListener
interface.
error
- An error describing the cause for error.