Package com.opentok.android

Class Session

  • public class Session
extends java.util.Observable
    Represents an OpenTok session in which the client is participating. The first step in using the OpenTok Android SDK is to initialize a Session instance by calling the Session() constructor.

    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 Vonage Video API account. Use the OpenTok server-side libraries to generate session IDs and tokens in your shipping app.

    See Also:
    Session Creation, Token Creation

    • Constructor Detail

      • Session

        @Deprecated
public Session​(android.content.Context context,
               java.lang.String apiKey,
               java.lang.String sessionId)
        throws java.lang.Exception
        Deprecated.
        Create a Session instance. This constructor is deprecated. Use the Session.Builder instead.
        Parameters:
        context - The Android application context associated with this process.
        apiKey - Your OpenTok API key. See your Vonage Video API account page. 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.
        sessionId - The OpenTok session ID this instance should connect to. For test purposes, you can generate test session by logging into your Vonage Video API account. Use the OpenTok server-side SDKs to generate session IDs in your shipping app.
        Throws:
        java.lang.Exception
        See Also:
        setSessionListener(com.opentok.android.Session.SessionListener)

      • Session

        @Deprecated
public Session​(android.content.Context context,
               java.lang.String apiKey,
               java.lang.String sessionId,
               Session.SessionOptions sessionOptions)
        throws java.lang.Exception
        Deprecated.
        Use this constructor to create a Session instance and use a SessionOptions object to define hardware video decoding options. This constructor is deprecated. Use the Session.Builder instead.
        Parameters:
        context - The Android application context associated with this process.
        apiKey - Your OpenTok API key. See your Vonage Video API account page.
        sessionId - The OpenTok session ID this instance should connect to. For test purposes, you can generate test session by logging onto your Vonage Video API account page. Use the OpenTok server-side SDKs to generate session IDs in your shipping app.
        sessionOptions - The object that inherits from SessionOptions object.
        Throws:
        java.lang.Exception
        See Also:
        setSessionListener(com.opentok.android.Session.SessionListener)

      • Session

        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,
                  boolean singlePeerConnection)
           throws java.lang.Exception
        Creates a new Session object. If you extend the Session class, you can call this constructor from the child class.
        Parameters:
        context - The Android application context associated with this process.
        apiKey - Your OpenTok API key. See your Vonage Video API account page. 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.
        sessionId - The OpenTok session ID this instance should connect to. For test purposes, you can generate test session by logging onto your Vonage Video API account page. Use the OpenTok server-side SDKs to generate session IDs in your shipping app.
        connectionEventsSuppressed - Prevent connection events (such as Session.ConnectionListener.onConnectionCreated(Session session, Connection connection)) from being dispatched
        sessionOptions - The object that inherits from SessionOptions object.
        routing - This is part of the configurable TURN feature.
        turnConfig - This is part of the configurable TURN feature.
        iceServers - This is part of the configurable TURN feature.
        apiUrl - This is not used.
        ipWhitelist - Set this to true if allowed IP list feature is enabled for your project. (This is available as an add-on feature.)
        proxyUrl - Set this to the URL of the IP proxy server. This is available as an add-on feature. See the OpenTok pricing page and the IP proxy developer guide.
        singlePeerConnection - Single Peer Connection (SPC) is a feature that encapsulates all subscriber connections to a single peer connection. The benefits of enabling SPC include reduced OS resource consumption, improved rate control, and, in case of mobile native devices, support for larger sessions. SPC is disabled by default. When disabled, the session will use Multiple Peer Connection (MPC), where a separate peer connection is established between each endpoint.
        Throws:
        java.lang.Exception

    • Method Detail

      • getSessionId

        public java.lang.String getSessionId()
        Returns the Session ID passed in during instantiation.
        Returns:
        The OpenTok Session ID for this instance.

      • disconnect

        public void disconnect()
        Disconnects from this session. All Subscriber and Publisher instances will be disconnected. As a best practice, before calling this method, call the unpublish(PublisherKit) method for all publishers and wait for the PublisherKit.onStreamDestroyed(Stream) callback. 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 Session.SessionListener.onDisconnected(Session session) method is called.

      • onPause

        public void onPause()
        Call this method when the app's activity pauses. This pauses the video renderer and capturer of any publishers to the session. It also pauses the video renderers of all subscribers.

        Cameras used by OpenTok publishers are now released when you call this method. Publishers reacquire cameras when you call the onResume() method.

      • onResume

        public void onResume()
        Call this method when the app's activity resumes. This resumes the video renderer and capturer of any publisher to the session. It also resumes the video renderers of all subscribers.

        Any cameras (used by OpenTok publishers) which were released when you called the onPause() method are reacquired when you call Session.onResume().

      • publish

        public void publish​(PublisherKit publisher)
        Starts a Publisher streaming to the session.
        Parameters:
        publisher - The Publisher that you want to stream to the session.

      • unpublish

        public void unpublish​(PublisherKit publisher)
        Disconnects the Publisher from the session.
        Parameters:
        publisher - The Publisher to unpublish.

      • subscribe

        public void subscribe​(SubscriberKit subscriber)
        Start receiving and rendering audio-video stream data for the specified subscriber.
        Parameters:
        subscriber - The subscriber bound to the stream to be received.

      • unsubscribe

        public void unsubscribe​(SubscriberKit subscriber)
        Stops subscribing (receiving a stream) to a specified subscriber in the session.
        Parameters:
        subscriber - The Subcriber you want to stop subscribing to.

      • getCapabilities

        public 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. This method returns null until you have connected to a session and the Session.SessionListener.onConnected(Session session) method has been called.

      • reportIssue

        public java.lang.String 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.
        Returns:
        The ID associated with the issue.

      • setEncryptionSecret

        public void setEncryptionSecret​(java.lang.String secret)
        Sets the end-to-end encryption secret used by all publishers and subscribers.

        See the End-to-end encryption developer guide.

        Parameters:
        secret - Value of the encryption secret.

      • onArchiveStarted

        protected void onArchiveStarted​(java.lang.String id,
                                java.lang.String name)
        Called when an archive of the session starts recording. In response to this method, you may want to add a user interface notification (such as an icon in the Publisher view) that indicates the session is being recorded.

        If you extend the Session class, you can override this method instead of the onArchiveStarted() method of the Session.ArchiveListener interface.

        Parameters:
        id - The unique ID of the archive.
        name - The name of the archive (if one was provided when the archive was created).

      • onArchiveStopped

        protected void onArchiveStopped​(java.lang.String id)
        Called when an archive of the session stops being recorded. In response to this method, you may want to remove a user interface notification (such as an icon in the Publisher view) the session recording has stopped.

        If you extend the Session class, you can override this method instead of the onArchiveStopped() method of the Session.ArchiveListener interface.

        Parameters:
        id - The unique ID of the archive.

      • onStreamHasAudioChanged

        protected void onStreamHasAudioChanged​(Stream stream,
                                       int hasAudio)
        Called when a stream in the session changes between having audio and not having audio.

        If you extend the Session class, you can override this method instead of the onStreamHasAudioChanged() method of the Session.StreamPropertiesListener interface.

        Parameters:
        stream - The stream.
        hasAudio - Whether the stream has audio (true) or not ( false).

      • onStreamHasCaptionsChanged

        protected void onStreamHasCaptionsChanged​(Stream stream,
                                          int hasCaptions)
        Called when a stream in the session changes between having captions and not having captions.

        If you extend the Session class, you can override this method instead of the onStreamHasCaptionsChanged() method of the Session.StreamPropertiesListener interface.

        Parameters:
        stream - The stream.
        hasCaptions - Whether the stream has captions (true) or not ( false).

      • onStreamHasVideoChanged

        protected void onStreamHasVideoChanged​(Stream stream,
                                       int hasVideo)
        Called when a stream in the session changes between having video and not having video.

        If you extend the Session class, you can override this method instead of the onStreamHasVideoChanged() method of the Session.StreamPropertiesListener interface.

        Parameters:
        stream - The stream.
        hasVideo - Whether the stream has video (true) or not ( false).

      • onStreamVideoDimensionsChanged

        protected void onStreamVideoDimensionsChanged​(Stream stream,
                                              int width,
                                              int height)
        Called when the video dimensions of a stream in the session change.

        If you extend the Session class, you can override this method instead of the onStreamVideoDimensionsChanged() method of the Session.StreamPropertiesListener interface.

        Parameters:
        stream - The stream.
        width - The new width of the stream, in pixels.
        height - The new height of the stream, in pixels.

      • onStreamVideoTypeChanged

        protected void onStreamVideoTypeChanged​(Stream stream,
                                        int videoType)
        Called when the video type of a stream in the session change.

        If you extend the Session class, you can override this method instead of the onStreamVideoTypeChanged() method of the Session.StreamPropertiesListener interface.

        Parameters:
        stream - The stream.
        videoType - The new video type of the stream.

      • onConnectionCreated

        protected void onConnectionCreated​(Connection connection)
        Invoked when another client connects to the session. The Connection object represents the client's connection to the session. Note that this method is invoked when other clients connect to the session. When your own client client connects, the 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.

        Parameters:
        connection - The new connection in the session.

      • onConnectionDestroyed

        protected void onConnectionDestroyed​(Connection connection)
        Invoked when another client leaves the session. The Connection object represents the client's previous connection to the session. When your own client client disconnects, the 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.

        Parameters:
        connection - The connection that left the session the session.

      • onSignalReceived

        protected void onSignalReceived​(java.lang.String type,
                                java.lang.String data,
                                Connection connection)
        Called when a signal is received in the session.

        If you extend the Session class, you can override this method instead of the onSignalReceived() method of the Session.SignalListener interface.

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

      • onReconnecting

        protected void onReconnecting()
        Invoked when the local client has lost its connection to an OpenTok session and is trying to reconnect. This results from a loss in network connectivity. If the client can reconnect to the session, the 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.

        See Also:
        onReconnected()

      • onReconnected

        protected void onReconnected()
        Invoked when the local client has reconnected to the OpenTok session after its network connection was lost temporarily. When the connection is lost, the 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.

        See Also:
        onReconnecting()

      • onConnected

        protected void onConnected()
        Invoked when the client connects to the OpenTok session.

        If you extend the Session class, you can override this method instead of the onConnected() method of the Session.SessionListener interface.

      • onDisconnected

        protected void onDisconnected()
        Invoked when the client is no longer connected to the OpenTok session.

        If you extend the Session class, you can override this method instead of the onDisconnected() method of the Session.SessionListener interface.

      • onStreamReceived

        protected void onStreamReceived​(Stream stream)
        Invoked when a there is a new stream published by another client in this OpenTok session.

        If you extend the Session class, you can override this method instead of the onStreamReceived() method of the Session.SessionListener interface.

        Parameters:
        stream - A Stream object representing the new stream, which can be used to create a Subscriber.

      • onStreamDropped

        protected void onStreamDropped​(Stream stream)
        Invoked when another client stops publishing a stream to this OpenTok session.

        If you extend the Session class, you can override this method instead of the onStreamDropped() method of the Session.SessionListener interface.

        Parameters:
        stream - A Stream object representing the dropped stream, which can be used to identify a Subscriber.

      • onError

        protected void onError​(OpentokError error)
        Invoked when something goes wrong when connecting or connected to the session. After this method is invoked, the Session should be treated as dead and unavailable. Do not attempt to reconnect or to call other methods of the Session object.

        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.

        Parameters:
        error - An error describing the cause for error.

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Called by the garbage collector when it determines that there are no more references to the Session object.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable