Session

public abstract class Session extends Object
Known Direct Subclasses

An abstract base class representing a session with a receiver application. A session is an end-to-end connection from a sender application to a receiver application. When the user selects a receiver device from the media route chooser dialog, a session is created by the SessionManager using its corresponding SessionProvider.

A subclass must override start(Bundle), resume(Bundle) and end(boolean), so that SessionManager can call them to start, resume or end the session. Subclass must also call the appropriate notifier methods to notify the state of the session. For example, call notifySessionStarted(String) when the session has been successfully started, so that the SessionManager will notify the rest of the app that the session has been started.

An implementation of this base class, CastSession, is provided by the SDK to manage connection to a Cast receiver device. This Session base class is provided so that if a sender application supports a receiver device that is not a Cast device, it can implement a custom session to communicate with that device, and still be able to let the SDK create the session when the user selects that device from the media route chooser dialog.

All methods must be called from the main thread.

See Also

Protected Constructor Summary

Session(Context applicationContext, String category, String sessionId)
Constructs a Session with a category string.

Public Method Summary

final String
getCategory()
Returns the category associated with this Session.
final String
getSessionId()
Returns the unique ID for this session.
long
getSessionRemainingTimeMs()
Subclass can override this method to provide a hint of how long the current session will live.
boolean
isConnected()
Returns true if the session is connected.
boolean
isConnecting()
Returns true if the session is connecting or resuming.
boolean
isDisconnected()
Returns true if the session is disconnected.
boolean
isDisconnecting()
Returns true if the session is disconnecting.
boolean
isResuming()
Returns true if the session is resuming.
boolean
isSuspended()
Returns true if the session is suspended.

Protected Method Summary

abstract void
end(boolean stopCasting)
Subclass should override this method to provide business logic of ending a session.
final void
notifyFailedToResumeSession(int error)
Subclass should call this to notify the SDK that a session has failed to resume.
final void
notifyFailedToStartSession(int error)
Subclass should call this to notify the SDK that a session has failed to start.
final void
notifySessionEnded(int error)
Subclass should call this to notify the SDK that a session has ended.
final void
notifySessionResumed(boolean wasSuspended)
Subclass should call this to notify the SDK that a session has been successfully resumed.
final void
notifySessionStarted(String sessionId)
Subclass should call this to notify the SDK that a session has been successfully started.
final void
notifySessionSuspended(int reason)
Subclass should call this to notify the SDK that a session has been suspended.
void
onResuming(Bundle routeInfoExtras)
This method is called prior to resume(Bundle).
void
onStarting(Bundle routeInfoExtras)
This method is called prior to start(Bundle).
abstract void
resume(Bundle routeInfoExtra)
Subclass should override this method to provide business logic of resuming a session.
abstract void
start(Bundle routeInfoExtra)
Subclass should override this method to provide business logic of starting a session.

Inherited Method Summary

Protected Constructors

protected Session (Context applicationContext, String category, String sessionId)

Constructs a Session with a category string. The category uniquely identifies a Session.

Parameters
applicationContext The application Context of the calling app.
category The category string for this Session.
sessionId The session ID of an existing session, if this object will be used to resume a session; otherwise null if it will be used to start a new session.

Public Methods

public final String getCategory ()

Returns the category associated with this Session.

Throws
IllegalStateException If this method is not called on the main thread.

public final String getSessionId ()

Returns the unique ID for this session.

Throws
IllegalStateException If this method is not called on the main thread.

public long getSessionRemainingTimeMs ()

Subclass can override this method to provide a hint of how long the current session will live. The SDK may call this method at any time to decide how long it should try to automatically resume the session if it got disconnected unexpectedly. The default return value is 0.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isConnected ()

Returns true if the session is connected.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isConnecting ()

Returns true if the session is connecting or resuming.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isDisconnected ()

Returns true if the session is disconnected.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isDisconnecting ()

Returns true if the session is disconnecting.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isResuming ()

Returns true if the session is resuming. A session is considered connecting when resuming.

Throws
IllegalStateException If this method is not called on the main thread.

public boolean isSuspended ()

Returns true if the session is suspended. A session is considered connecting when is suspended.

Throws
IllegalStateException If this method is not called on the main thread.

Protected Methods

protected abstract void end (boolean stopCasting)

Subclass should override this method to provide business logic of ending a session. This method is called by the SDK when ending an active session. This method is called on the main thread and must not block.

Parameters
stopCasting Should the receiver app be stopped when the current session ends.

protected final void notifyFailedToResumeSession (int error)

Subclass should call this to notify the SDK that a session has failed to resume.

protected final void notifyFailedToStartSession (int error)

Subclass should call this to notify the SDK that a session has failed to start.

protected final void notifySessionEnded (int error)

Subclass should call this to notify the SDK that a session has ended.

protected final void notifySessionResumed (boolean wasSuspended)

Subclass should call this to notify the SDK that a session has been successfully resumed.

protected final void notifySessionStarted (String sessionId)

Subclass should call this to notify the SDK that a session has been successfully started.

protected final void notifySessionSuspended (int reason)

Subclass should call this to notify the SDK that a session has been suspended.

protected void onResuming (Bundle routeInfoExtras)

This method is called prior to resume(Bundle). Subclass should override this method to do necessary setup. The default implementation does nothing.

Parameters
routeInfoExtras the extra field of the selected media route and it can be obtained by MediaRouter.RouteInfo.getExtras()

protected void onStarting (Bundle routeInfoExtras)

This method is called prior to start(Bundle). Subclass should override this method to do necessary setup. The default implementation does nothing.

Parameters
routeInfoExtras the extra field of the selected media route and it can be obtained by MediaRouter.RouteInfo.getExtras()

protected abstract void resume (Bundle routeInfoExtra)

Subclass should override this method to provide business logic of resuming a session. This method is called by the SDK when resuming a session. This method is called on the main thread and must not block.

Parameters
routeInfoExtra the extra field of the selected media route and it can be obtained by MediaRouter.RouteInfo.getExtras()

protected abstract void start (Bundle routeInfoExtra)

Subclass should override this method to provide business logic of starting a session. This method is called by the SDK when starting a session. This method is called on the main thread and must not block.

Parameters
routeInfoExtra the extra field of the selected media route and it can be obtained by MediaRouter.RouteInfo.getExtras()