org.digitalmediaserver.cast

Class Channel

java.lang.Object

org.digitalmediaserver.cast.Channel

All Implemented Interfaces:

Closeable, AutoCloseable

public class Channel
extends Object
implements Closeable

Internal class for low-level communication with cast devices. It's normally desirable to use CastDevice or Session methods instead of calling this class directly.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Channel.GradualVolumeTask A TimerTask that will gradually increase or decrease the volume level of the cast device until the target level is reached.
protected class	Channel.InputHandler A Thread implementation tailored to process incoming messages on the socket.
protected class	Channel.PingTask A TimerTask that will send PING messages to the cast device upon execution.
protected class	Channel.ResultProcessor<T extends Response> Internal class used to tie responses to requests based on request IDs.
protected class	Channel.ResultProcessorResult<T extends Response> A holder for the resulting Response.

Field Summary

Fields

Modifier and Type	Field and Description
protected InetSocketAddress	address The IP address and port of the cast device
protected Volume	cachedVolume The last received Volume instance
protected Object	cachedVolumeLock The cached volume synchronization object
static org.slf4j.Marker	CAST_API_HEARTBEAT_MARKER The logging Marker used for ping logging
static org.slf4j.Marker	CAST_API_MARKER The logging Marker used for logging
static long	DEFAULT_RESPONSE_TIMEOUT The default response timeout in milliseconds
protected Object	gradualVolumeLock The gradual volume synchronization object
protected TimerTask	gradualVolumeTask The TimerTask that executes the gradual volume change
protected Timer	gradualVolumeTimer The Timer used to handle gradual volume change
protected Channel.InputHandler	inputHandler The Thread that delegates incoming requests to processing threads
protected com.fasterxml.jackson.databind.ObjectMapper	jsonMapper Single mapper object for marshalling JSON
protected CastEvent.CastEventListenerList	listeners The registered CastEvent.CastEventListeners
protected static long	PING_PERIOD The delay between PING requests in milliseconds
protected Timer	pingTimer Timer for PING requests
static String	PLATFORM_RECEIVER_ID Google's fixed receiver ID to use for the cast device itself
static String	PLATFORM_SENDER_ID Google's fixed source ID to use for the "sender platform" (as opposed to the sender application)
protected String	remoteName The name used for the remote party in logging
protected AtomicLong	requestCounter Counter for producing request numbers
protected Map<Long,Channel.ResultProcessor<? extends Response>>	requests Processors of requests by their identifiers
protected Set<Session>	sessions The currently known Sessions belonging to this Channel
protected Object	sessionsLock The sessions synchronization object
protected Socket	socket The Socket instance use to communicate with the remote device.
protected Object	socketLock The socket synchronization object
static int	STANDARD_DEVICE_PORT The standard port used for cast devices
protected static com.fasterxml.jackson.annotation.JsonSubTypes.Type[]	STANDARD_RESPONSE_TYPES An array of what is defined as "standard response" types, to be treated as immutable

Constructor Summary

Constructors

Constructor and Description
Channel(InetAddress address, int port, String remoteName, CastEvent.CastEventListenerList listeners) Creates a new channel using the specified parameters.
Channel(InetAddress address, String remoteName, CastEvent.CastEventListenerList listeners) Creates a new channel using the specified parameters and the standard port.
Channel(InetSocketAddress socketAddress, String remoteName, CastEvent.CastEventListenerList listeners) Creates a new channel using the specified parameters.
Channel(String host, int port, String remoteName, CastEvent.CastEventListenerList listeners) Creates a new channel using the specified parameters.
Channel(String host, String remoteName, CastEvent.CastEventListenerList listeners) Creates a new channel using the specified parameters and the standard port.

Method Summary

Modifier and Type	Method and Description
protected Channel.ResultProcessor<? extends Response>	acquireResultProcessor(long requestId) Claims (retrieves and removes from requests) the Channel.ResultProcessorResult for the specified request ID if one exists.
protected void	cacheVolume(ReceiverStatus receiverStatus) Caches the Volume instance from the specified ReceiverStatus as as long as neither are null.
protected void	cacheVolume(Volume volume) Caches the specified Volume instance as long as it's not null.
protected boolean	cancelPendingClosed(String peerId) Loops through any requests waiting for a response and cancels any that waits for a reply from the specified peer/destination ID.
protected void	cancelPendingDisconnected() Loops through all requests waiting for a response and cancels them.
void	close() Closes this Channel and any Sessions belonging to it.
boolean	closeSession(Session session) Closes the specified Session unless it's already closed, in which case nothing is done.
boolean	connect() Establishes a connection to the associated remote cast device.
protected ReceiverStatus	doSetVolume(Volume volume, boolean synchronous, long responseTimeout) Sets the device volume level using the specified parameters, without any checks or evaluations.
MediaStatus	getMediaStatus(Session session) Request a MediaStatus from the application with the specified Session, using 30000L as the timeout value.
MediaStatus	getMediaStatus(Session session, long responseTimeout) Request a MediaStatus from the application with the specified Session.
ReceiverStatus	getReceiverStatus() Request a ReceiverStatus from the cast device, using 30000L as the timeout value.
ReceiverStatus	getReceiverStatus(long responseTimeout) Request a ReceiverStatus from the cast device.
boolean	isApplicationAvailable(String applicationId) Queries the cast device if the application represented by the specified application ID is available, using 30000L as the timeout value.
boolean	isApplicationAvailable(String applicationId, long responseTimeout) Queries the cast device if the application represented by the specified application ID is available.
boolean	isClosed()
protected static boolean	isCustomMessage(com.fasterxml.jackson.databind.JsonNode parsedMessage) Determines if the message referenced by the specified JsonNode is among the "standard responses" by looking at the type field exclusively.
boolean	isSessionClosed(Session session) Checks whether or not the specified Session is closed.
ReceiverStatus	launch(String applicationId, boolean synchronous) Asks the cast device to launch the application represented by the specified application ID, using 30000L as the timeout value.
ReceiverStatus	launch(String applicationId, boolean synchronous, long responseTimeout) Asks the cast device to launch the application represented by the specified application ID.
MediaStatus	load(Session session, Boolean autoplay, Double currentTime, Media media, boolean synchronous, long responseTimeout) Asks the targeted remote application to load the specified Media using the specified parameters.
MediaStatus	load(Session session, List<Integer> activeTrackIds, Boolean autoplay, String credentials, String credentialsType, Double currentTime, Map<String,Object> customData, LoadOptions loadOptions, Media media, Double playbackRate, QueueData queueData, boolean synchronous, long responseTimeout) Asks the targeted remote application to load the specified Media or QueueDatas using the specified parameters.
MediaStatus	load(Session session, StandardRequest.Load loadRequest, boolean synchronous, long responseTimeout) Asks the targeted remote application to execute the specified StandardRequest.Load request.
MediaStatus	pause(Session session, int mediaSessionId, boolean synchronous) Asks the remote application to pause playback of the media referenced by the specified media session ID, using 30000L as the timeout value.
MediaStatus	pause(Session session, int mediaSessionId, boolean synchronous, long responseTimeout) Asks the remote application to pause playback of the media referenced by the specified media session ID.
MediaStatus	play(Session session, int mediaSessionId, boolean synchronous) Asks the remote application to start playing the media referenced by the specified media session ID, using 30000L as the timeout value.
MediaStatus	play(Session session, int mediaSessionId, boolean synchronous, long responseTimeout) Asks the remote application to start playing the media referenced by the specified media session ID.
protected static ImmutableCastMessage	readMessage(InputStream inputStream) Reads the next CastChannel.CastMessage from the specified InputStream in a blocking fashion.
MediaStatus	seek(Session session, int mediaSessionId, double currentTime, StandardRequest.ResumeState resumeState, boolean synchronous) Asks the remote application to move the playback position of the media referenced by the specified media session ID to the specified position, using 30000L as the timeout value.
MediaStatus	seek(Session session, int mediaSessionId, double currentTime, StandardRequest.ResumeState resumeState, boolean synchronous, long responseTimeout) Asks the remote application to move the playback position of the media referenced by the specified media session ID to the specified position.
<T extends Response> T	send(Session session, String namespace, Request message, String sourceId, String destinationId, Class<T> responseClass, long responseTimeout) Sends the specified Request to the specified destination using the specified parameters.
<T extends Response> T	sendGenericRequest(Session session, String namespace, Request request, Class<T> responseClass) Sends the specified Request with the specified namespace using the specified Session and 30000L as the timeout value.
<T extends Response> T	sendGenericRequest(Session session, String namespace, Request request, Class<T> responseClass, long responseTimeout) Sends the specified Request with the specified namespace using the specified Session.
<T extends Response> T	sendGenericRequest(String sourceId, String destinationId, String namespace, Request request, Class<T> responseClass) Sends the specified Request with the specified namespace using the specified source and destination IDs and 30000L as the timeout value.
<T extends Response> T	sendGenericRequest(String sourceId, String destinationId, String namespace, Request request, Class<T> responseClass, long responseTimeout) Sends the specified Request with the specified namespace using the specified source and destination IDs.
MediaStatus	setMediaVolume(Session session, int mediaSessionId, MediaVolume volume, boolean synchronous) Asks the remote application to change the volume level or mute state of the stream of the specified media session.
MediaStatus	setMediaVolume(Session session, int mediaSessionId, MediaVolume volume, boolean synchronous, long responseTimeout) Asks the remote application to change the volume level or mute state of the stream of the specified media session.
void	setVolume(Volume volume) Sets the device Volume to the values of the specified instance.
Session	startSession(String sourceId, Application application, String userAgent, VirtualConnectionType connectionType) Establishes a Session with the specified Application unless one already exists, in which case the existing Session is returned.
ReceiverStatus	stopApplication(Application application, boolean synchronous) Asks the cast device to stop the specified Application, using 30000L as the timeout value.
ReceiverStatus	stopApplication(Application application, boolean synchronous, long responseTimeout) Asks the cast device to stop the specified Application.
MediaStatus	stopMedia(Session session, int mediaSessionId, boolean synchronous) Asks the remote application to stop playback and unload the media referenced by the specified media session ID, using 30000L as the timeout value.
MediaStatus	stopMedia(Session session, int mediaSessionId, boolean synchronous, long responseTimeout) Asks the remote application to stop playback and unload the media referenced by the specified media session ID.
static void	validateNamespace(String namespace) Validates that the specified namespace conforms to some very basic constraints.
protected void	write(CastChannel.CastMessage message) Writes the specified CastChannel.CastMessage to the socket.
protected void	write(String namespace, Message message, String sourceId, String destinationId) Writes the specified Message to the socket using the specified parameters.
protected void	write(String namespace, String message, String sourceId, String destinationId) Writes the specified (JSON formatted) String to the socket using the specified parameters.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CAST_API_MARKER

public static final org.slf4j.Marker CAST_API_MARKER

The logging Marker used for logging

CAST_API_HEARTBEAT_MARKER

public static final org.slf4j.Marker CAST_API_HEARTBEAT_MARKER

The logging Marker used for ping logging

STANDARD_DEVICE_PORT

public static final int STANDARD_DEVICE_PORT

The standard port used for cast devices

See Also:

Constant Field Values

PING_PERIOD

protected static final long PING_PERIOD

The delay between PING requests in milliseconds

See Also:

Constant Field Values

DEFAULT_RESPONSE_TIMEOUT

public static final long DEFAULT_RESPONSE_TIMEOUT

The default response timeout in milliseconds

See Also:

Constant Field Values

PLATFORM_RECEIVER_ID

public static final String PLATFORM_RECEIVER_ID

Google's fixed receiver ID to use for the cast device itself

See Also:

Constant Field Values

PLATFORM_SENDER_ID

public static final String PLATFORM_SENDER_ID

Google's fixed source ID to use for the "sender platform" (as opposed to the sender application)

See Also:

Constant Field Values

STANDARD_RESPONSE_TYPES

protected static final com.fasterxml.jackson.annotation.JsonSubTypes.Type[] STANDARD_RESPONSE_TYPES

An array of what is defined as "standard response" types, to be treated as immutable

listeners

@Nonnull
protected final CastEvent.CastEventListenerList listeners

The registered CastEvent.CastEventListeners

socketLock

@Nonnull
protected final Object socketLock

The socket synchronization object

socket

@Nullable
protected Socket socket

The Socket instance use to communicate with the remote device.

address

@Nonnull
protected final InetSocketAddress address

The IP address and port of the cast device

remoteName

@Nonnull
protected final String remoteName

The name used for the remote party in logging

pingTimer

protected Timer pingTimer

Timer for PING requests

inputHandler

protected Channel.InputHandler inputHandler

The Thread that delegates incoming requests to processing threads

requestCounter

@Nonnull
protected final AtomicLong requestCounter

Counter for producing request numbers

requests

@Nonnull
protected final Map<Long,Channel.ResultProcessor<? extends Response>> requests

Processors of requests by their identifiers

jsonMapper

@Nonnull
protected final com.fasterxml.jackson.databind.ObjectMapper jsonMapper

Single mapper object for marshalling JSON

sessionsLock

@Nonnull
protected final Object sessionsLock

The sessions synchronization object

sessions

@Nonnull
protected final Set<Session> sessions

The currently known Sessions belonging to this Channel

cachedVolumeLock

@Nonnull
protected final Object cachedVolumeLock

The cached volume synchronization object

cachedVolume

@Nullable
protected Volume cachedVolume

The last received Volume instance

gradualVolumeLock

@Nonnull
protected final Object gradualVolumeLock

The gradual volume synchronization object

gradualVolumeTimer

@Nullable
protected Timer gradualVolumeTimer

The Timer used to handle gradual volume change

gradualVolumeTask

@Nullable
protected TimerTask gradualVolumeTask

The TimerTask that executes the gradual volume change

Constructor Detail

Channel

public Channel(@Nonnull
               String host,
               @Nonnull
               String remoteName,
               @Nonnull
               CastEvent.CastEventListenerList listeners)

Creates a new channel using the specified parameters and the standard port.

Parameters:

host - the host IP address or hostname of the cast device.

remoteName - the name to use for the cast device in logging.

listeners - the CastEvent.CastEventListenerList to use when sending events.

Channel

public Channel(@Nonnull
               String host,
               int port,
               @Nonnull
               String remoteName,
               @Nonnull
               CastEvent.CastEventListenerList listeners)

Creates a new channel using the specified parameters.

Parameters:

host - the host IP address or hostname of the cast device.

port - the port of the cast device.

remoteName - the name to use for the cast device in logging.

listeners - the CastEvent.CastEventListenerList to use when sending events.

Channel

public Channel(@Nonnull
               InetAddress address,
               @Nonnull
               String remoteName,
               @Nonnull
               CastEvent.CastEventListenerList listeners)

Creates a new channel using the specified parameters and the standard port.

Parameters:

address - the IP address of the cast device.

remoteName - the name to use for the cast device in logging.

listeners - the CastEvent.CastEventListenerList to use when sending events.

Throws:

IllegalArgumentException - If listeners is null or if remoteName is blank.

Channel

public Channel(@Nonnull
               InetAddress address,
               int port,
               @Nonnull
               String remoteName,
               @Nonnull
               CastEvent.CastEventListenerList listeners)

Creates a new channel using the specified parameters.

Parameters:

address - the IP address of the cast device.

port - the port of the cast device.

remoteName - the name to use for the cast device in logging.

listeners - the CastEvent.CastEventListenerList to use when sending events.

Throws:

IllegalArgumentException - If listeners is null, if address or remoteName is blank or if port is outside the range of valid port numbers.

Channel

public Channel(@Nonnull
               InetSocketAddress socketAddress,
               @Nonnull
               String remoteName,
               @Nonnull
               CastEvent.CastEventListenerList listeners)

Creates a new channel using the specified parameters.

Parameters:

socketAddress - the SocketAddress of the cast device.

remoteName - the name to use for the cast device in logging.

listeners - the CastEvent.CastEventListenerList to use when sending events.

Throws:

IllegalArgumentException - If socketAddress or listeners is null or if remoteName is blank.

Method Detail

connect

public boolean connect()
                throws IOException,
                       NoSuchAlgorithmException,
                       KeyManagementException

Establishes a connection to the associated remote cast device.

Returns:

true if a connection was established, false if there was no need.

Throws:

KeyManagementException - If there's a problem with key management that prevents connection.

NoSuchAlgorithmException - If the required cryptographic algorithm isn't available in the JVM.

CastException - If there was an authentication problem with the cast device.

IOException - If an error occurs during the operation.

close

public void close()
           throws IOException

Closes this Channel and any Sessions belonging to it. If this Channel is already closed, this is a no-op.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - If an error occurs during the operation.

isClosed

public boolean isClosed()

Returns:

true if this Channel is closed, false if it's open.

send

public <T extends Response> T send(@Nullable
                                   Session session,
                                   String namespace,
                                   Request message,
                                   String sourceId,
                                   String destinationId,
                                   Class<T> responseClass,
                                   long responseTimeout)
                            throws IOException

Sends the specified Request to the specified destination using the specified parameters.

Type Parameters:

T - the class of the Response object.

Parameters:

session - if responseClass is non-null and the destination is an application, this must be the Session that has been established with said application. This makes sure that the waiting for the response will be terminated if the Session is terminated. If responseClass is null or the request is destined to the cast device itself, this should be null.

namespace - the namespace to use.

message - the Request to send.

sourceId - the source ID to use.

destinationId - the destination ID to use.

responseClass - the class of the expected response for synchronous (blocking) behavior, or null for asynchronous behavior that returns null immediately.

responseTimeout - the response timeout in milliseconds if responseClass is non-null. If zero or negative, 30000L will be used.

Returns:

The Response object of the specified type if responseClass is non-null, null if responseClass is null.

Throws:

IllegalArgumentException - If namespace is null or invalid (see validateNamespace(String) for constraints).

IOException - If responseClass is non-null and the response from the cast device is a different type than what was expected, or if an error occurs during the operation.

getReceiverStatus

@Nullable
public ReceiverStatus getReceiverStatus()
                                            throws IOException

Request a ReceiverStatus from the cast device, using 30000L as the timeout value.

Returns:

The resulting ReceiverStatus.

Throws:

IOException - If the response times out or an error occurs during the operation.

getReceiverStatus

@Nullable
public ReceiverStatus getReceiverStatus(long responseTimeout)
                                            throws IOException

Request a ReceiverStatus from the cast device.

Parameters:

responseTimeout - the response timeout in milliseconds. If zero or negative, 30000L will be used.

Returns:

The resulting ReceiverStatus.

Throws:

IOException - If the response times out or an error occurs during the operation.

isApplicationAvailable

public boolean isApplicationAvailable(String applicationId)
                               throws IOException

Queries the cast device if the application represented by the specified application ID is available, using 30000L as the timeout value.

Parameters:

applicationId - the application ID for which to query availability.

Returns:

true if the application is available, false if it's not.

Throws:

IOException - If the response times out or if an error occurs during the operation.

isApplicationAvailable

public boolean isApplicationAvailable(String applicationId,
                                      long responseTimeout)
                               throws IOException

Queries the cast device if the application represented by the specified application ID is available.

Parameters:

applicationId - the application ID for which to query availability.

responseTimeout - the response timeout in milliseconds if. If zero or negative, 30000L will be used.

Returns:

true if the application is available, false if it's not.

Throws:

IOException - If the response times out or if an error occurs during the operation.

launch

@Nullable
public ReceiverStatus launch(String applicationId,
                                        boolean synchronous)
                                 throws IOException

Asks the cast device to launch the application represented by the specified application ID, using 30000L as the timeout value.

Parameters:

applicationId - the application ID for the application to launch.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting ReceiverStatus or null if synchronous is false.

Throws:

IOException - If the response times out or an error occurs during the operation.

launch

@Nullable
public ReceiverStatus launch(String applicationId,
                                        boolean synchronous,
                                        long responseTimeout)
                                 throws IOException

Asks the cast device to launch the application represented by the specified application ID.

Parameters:

applicationId - the application ID for the application to launch.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting ReceiverStatus or null if synchronous is false.

Throws:

IOException - If the response times out or an error occurs during the operation.

stopApplication

public ReceiverStatus stopApplication(@Nonnull
                                      Application application,
                                      boolean synchronous)
                               throws IOException

Asks the cast device to stop the specified Application, using 30000L as the timeout value.

Parameters:

application - the Application to stop.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting ReceiverStatus or null if synchronous is false.

Throws:

IOException - If the response times out or an error occurs during the operation.

stopApplication

public ReceiverStatus stopApplication(@Nonnull
                                      Application application,
                                      boolean synchronous,
                                      long responseTimeout)
                               throws IOException

Asks the cast device to stop the specified Application.

Parameters:

application - the Application to stop.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting ReceiverStatus or null if synchronous is false.

Throws:

NullPointerException - If application is null.

IOException - If the response times out or an error occurs during the operation.

startSession

@Nonnull
public Session startSession(@Nonnull
                                      String sourceId,
                                      @Nonnull
                                      Application application,
                                      @Nullable
                                      String userAgent,
                                      @Nonnull
                                      VirtualConnectionType connectionType)
                               throws IOException

Establishes a Session with the specified Application unless one already exists, in which case the existing Session is returned.

Parameters:

sourceId - the source ID to use.

application - the Application to connect to.

userAgent - the user-agent String or null. It's not entirely clear what this is used for other than reporting to Google, so it might be that it's better left null.

connectionType - The VirtualConnectionType to use. Please note that only VirtualConnectionType.STRONG and VirtualConnectionType.INVISIBLE are allowed.

Returns:

The existing or new Session.

Throws:

IOException - If an error occurs during the operation.

closeSession

public boolean closeSession(@Nullable
                            Session session)
                     throws IOException

Closes the specified Session unless it's already closed, in which case nothing is done.

Parameters:

session - the Session to close.

Returns:

true if the Session was closed, false if it was closed already.

Throws:

IOException - If an error occurs during the operation.

isSessionClosed

public boolean isSessionClosed(@Nullable
                               Session session)

Checks whether or not the specified Session is closed.

Parameters:

session - the Session to check.

Returns:

true if the specified Session is closed, false if it's connected.

getMediaStatus

@Nullable
public MediaStatus getMediaStatus(@Nonnull
                                             Session session)
                                      throws IOException

Request a MediaStatus from the application with the specified Session, using 30000L as the timeout value.

Parameters:

session - the Session to use.

Returns:

The resulting MediaStatus.

Throws:

IOException - If the response times out or an error occurs during the operation.

getMediaStatus

@Nullable
public MediaStatus getMediaStatus(@Nonnull
                                             Session session,
                                             long responseTimeout)
                                      throws IOException

Request a MediaStatus from the application with the specified Session.

Parameters:

session - the Session to use.

responseTimeout - the response timeout in milliseconds. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

load

@Nullable
public MediaStatus load(@Nonnull
                                   Session session,
                                   @Nonnull
                                   StandardRequest.Load loadRequest,
                                   boolean synchronous,
                                   long responseTimeout)
                            throws IOException

Asks the targeted remote application to execute the specified StandardRequest.Load request.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

loadRequest - the StandardRequest.Load request to send.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session or loadRequest is null.

IOException - If the response times out or an error occurs during the operation.

load

@Nullable
public MediaStatus load(@Nonnull
                                   Session session,
                                   @Nullable
                                   Boolean autoplay,
                                   @Nullable
                                   Double currentTime,
                                   @Nonnull
                                   Media media,
                                   boolean synchronous,
                                   long responseTimeout)
                            throws IOException

Asks the targeted remote application to load the specified Media using the specified parameters.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

media - the Media to load.

autoplay - true to ask the remote application to start playback as soon as the Media has been loaded, false to ask it to transition to a paused state after loading.

currentTime - the position in seconds where playback are to be started in the loaded Media.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session or media is null.

IOException - If the response times out or an error occurs during the operation.

load

@Nullable
public MediaStatus load(@Nonnull
                                   Session session,
                                   @Nullable
                                   List<Integer> activeTrackIds,
                                   @Nullable
                                   Boolean autoplay,
                                   @Nullable
                                   String credentials,
                                   @Nullable
                                   String credentialsType,
                                   @Nullable
                                   Double currentTime,
                                   @Nullable
                                   Map<String,Object> customData,
                                   @Nullable
                                   LoadOptions loadOptions,
                                   @Nullable
                                   Media media,
                                   @Nullable
                                   Double playbackRate,
                                   @Nullable
                                   QueueData queueData,
                                   boolean synchronous,
                                   long responseTimeout)
                            throws IOException

Asks the targeted remote application to load the specified Media or QueueDatas using the specified parameters. Either media or queueData must be non-null.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

activeTrackIds - the List of track IDs that are active. If the list is not provided, the default tracks will be active.

autoplay - true to ask the remote application to start playback as soon as the Media has been loaded, false to ask it to transition to a paused state after loading.

credentials - the user credentials, if any.

credentialsType - the credentials type, if any. The type 'cloud' is a reserved type used by load requests that were originated by voice assistant commands.

currentTime - the position in seconds from the start for where playback is to start in the loaded Media. If the content is live content, and currentTime is not specified, the stream will start at the live position.

customData - the custom application data to send to the remote application with the load command.

loadOptions - the additional load options, if any.

media - the Media to load.

playbackRate - the media playback rate.

queueData - the queue data.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

play

@Nullable
public MediaStatus play(@Nonnull
                                   Session session,
                                   int mediaSessionId,
                                   boolean synchronous)
                            throws IOException

Asks the remote application to start playing the media referenced by the specified media session ID, using 30000L as the timeout value.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the play request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

play

@Nullable
public MediaStatus play(@Nonnull
                                   Session session,
                                   int mediaSessionId,
                                   boolean synchronous,
                                   long responseTimeout)
                            throws IOException

Asks the remote application to start playing the media referenced by the specified media session ID.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the play request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

pause

@Nullable
public MediaStatus pause(@Nonnull
                                    Session session,
                                    int mediaSessionId,
                                    boolean synchronous)
                             throws IOException

Asks the remote application to pause playback of the media referenced by the specified media session ID, using 30000L as the timeout value.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the pause request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

pause

@Nullable
public MediaStatus pause(@Nonnull
                                    Session session,
                                    int mediaSessionId,
                                    boolean synchronous,
                                    long responseTimeout)
                             throws IOException

Asks the remote application to pause playback of the media referenced by the specified media session ID.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the pause request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

seek

@Nullable
public MediaStatus seek(@Nonnull
                                   Session session,
                                   int mediaSessionId,
                                   double currentTime,
                                   @Nullable
                                   StandardRequest.ResumeState resumeState,
                                   boolean synchronous)
                            throws IOException

Asks the remote application to move the playback position of the media referenced by the specified media session ID to the specified position, using 30000L as the timeout value.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the pause request applies.

currentTime - the new playback position in seconds.

resumeState - the desired media player state after the seek is complete. If null, it will retain the state it had before seeking.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

seek

@Nullable
public MediaStatus seek(@Nonnull
                                   Session session,
                                   int mediaSessionId,
                                   double currentTime,
                                   @Nullable
                                   StandardRequest.ResumeState resumeState,
                                   boolean synchronous,
                                   long responseTimeout)
                            throws IOException

Asks the remote application to move the playback position of the media referenced by the specified media session ID to the specified position.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the pause request applies.

currentTime - the new playback position in seconds.

resumeState - the desired media player state after the seek is complete. If null, it will retain the state it had before seeking.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

stopMedia

@Nullable
public MediaStatus stopMedia(@Nonnull
                                        Session session,
                                        int mediaSessionId,
                                        boolean synchronous)
                                 throws IOException

Asks the remote application to stop playback and unload the media referenced by the specified media session ID, using 30000L as the timeout value.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the MediaVolume request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

stopMedia

@Nullable
public MediaStatus stopMedia(@Nonnull
                                        Session session,
                                        int mediaSessionId,
                                        boolean synchronous,
                                        long responseTimeout)
                                 throws IOException

Asks the remote application to stop playback and unload the media referenced by the specified media session ID.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the MediaVolume request applies.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

setMediaVolume

@Nullable
public MediaStatus setMediaVolume(@Nonnull
                                             Session session,
                                             int mediaSessionId,
                                             @Nonnull
                                             MediaVolume volume,
                                             boolean synchronous)
                                      throws IOException

Asks the remote application to change the volume level or mute state of the stream of the specified media session. Please note that this is different from the device volume level or mute state, and that this will give the user no visual indication, using 30000L as the timeout value.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the MediaVolume request applies.

volume - the MediaVolume to set.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If session or volume is null.

IOException - If the response times out or an error occurs during the operation.

setMediaVolume

@Nullable
public MediaStatus setMediaVolume(@Nonnull
                                             Session session,
                                             int mediaSessionId,
                                             @Nonnull
                                             MediaVolume volume,
                                             boolean synchronous,
                                             long responseTimeout)
                                      throws IOException

Asks the remote application to change the volume level or mute state of the stream of the specified media session. Please note that this is different from the device volume level or mute state, and that this will give the user no visual indication.

This can only succeed if the remote application supports the "urn:x-cast:com.google.cast.media" namespace.

Parameters:

session - the Session to use.

mediaSessionId - the media session ID for which the MediaVolume request applies.

volume - the MediaVolume to set.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting MediaStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IllegalArgumentException - If sessionId or volume is null.

IllegalArgumentException - If session is null.

IOException - If the response times out or an error occurs during the operation.

setVolume

@Nullable
public void setVolume(Volume volume)
                          throws IOException

Sets the device Volume to the values of the specified instance. A Volume instance contains both the volume level and the mute state.

If the device has Volume.VolumeControlType.MASTER and the this call changes the volume level more than the device specified "step", this method will start a Timer based gradual change towards the specified volume level.

Parameters:

volume - the Volume instance whose values to set.

Throws:

CastException - If the cast device has Volume.VolumeControlType.FIXED.

IOException - If an error occurs during the operation.

doSetVolume

@Nullable
protected ReceiverStatus doSetVolume(Volume volume,
                                                boolean synchronous,
                                                long responseTimeout)
                                         throws IOException

Sets the device volume level using the specified parameters, without any checks or evaluations.

Parameters:

volume - the Volume instance to send to the cast device.

synchronous - true to make this call block until a response is received or times out, false to make it return immediately always returning null.

responseTimeout - the response timeout in milliseconds if synchronous is true. If zero or negative, 30000L will be used.

Returns:

The resulting ReceiverStatus if synchronous is true and a reply is received in time, null if synchronous is false.

Throws:

IOException - If the response times out or an error occurs during the operation.

sendGenericRequest

public <T extends Response> T sendGenericRequest(@Nonnull
                                                 Session session,
                                                 @Nonnull
                                                 String namespace,
                                                 Request request,
                                                 Class<T> responseClass)
                                          throws IOException

Sends the specified Request with the specified namespace using the specified Session and 30000L as the timeout value.

Type Parameters:

T - the class of the Response object.

Parameters:

session - the Session to use.

namespace - the namespace to use.

request - the Request to send.

responseClass - the response class to to block and wait for a response or null to return immediately.

Returns:

The Response if the response is received in time, or null if the responseClass is null or a timeout occurs.

Throws:

IllegalArgumentException - If Session is null or if namespace is null or invalid (see validateNamespace(String) for constraints).

IOException - If an error occurs during the operation.

sendGenericRequest

public <T extends Response> T sendGenericRequest(@Nonnull
                                                 Session session,
                                                 @Nonnull
                                                 String namespace,
                                                 Request request,
                                                 Class<T> responseClass,
                                                 long responseTimeout)
                                          throws IOException

Sends the specified Request with the specified namespace using the specified Session.

Type Parameters:

T - the class of the Response object.

Parameters:

session - the Session to use.

namespace - the namespace to use.

request - the Request to send.

responseClass - the response class to to block and wait for a response or null to return immediately.

responseTimeout - the response timeout in milliseconds if responseClass is non-null. If zero or negative, 30000L will be used.

Returns:

The Response if the response is received in time, or null if the responseClass is null or a timeout occurs.

Throws:

IllegalArgumentException - If Session is null or if namespace is null or invalid (see validateNamespace(String) for constraints).

IOException - If an error occurs during the operation.

sendGenericRequest

public <T extends Response> T sendGenericRequest(@Nonnull
                                                 String sourceId,
                                                 @Nonnull
                                                 String destinationId,
                                                 @Nonnull
                                                 String namespace,
                                                 Request request,
                                                 Class<T> responseClass)
                                          throws IOException

Sends the specified Request with the specified namespace using the specified source and destination IDs and 30000L as the timeout value. This is for requests that aren't associated with a Session.

Type Parameters:

T - the class of the Response object.

Parameters:

sourceId - the source ID to use.

destinationId - the destination ID to use.

namespace - the namespace to use.

request - the Request to send.

responseClass - the response class to to block and wait for a response or null to return immediately.

Returns:

The Response if the response is received in time, or null if the responseClass is null or a timeout occurs.

Throws:

IllegalArgumentException - If namespace is null or invalid (see validateNamespace(String) for constraints).

IOException - If an error occurs during the operation.

sendGenericRequest

public <T extends Response> T sendGenericRequest(@Nonnull
                                                 String sourceId,
                                                 @Nonnull
                                                 String destinationId,
                                                 @Nonnull
                                                 String namespace,
                                                 Request request,
                                                 Class<T> responseClass,
                                                 long responseTimeout)
                                          throws IOException

Sends the specified Request with the specified namespace using the specified source and destination IDs. This is for requests that aren't associated with a Session.

Type Parameters:

T - the class of the Response object.

Parameters:

sourceId - the source ID to use.

destinationId - the destination ID to use.

namespace - the namespace to use.

request - the Request to send.

responseClass - the response class to to block and wait for a response or null to return immediately.

responseTimeout - the response timeout in milliseconds if responseClass is non-null. If zero or negative, 30000L will be used.

Returns:

The Response if the response is received in time, or null if the responseClass is null or a timeout occurs.

Throws:

IllegalArgumentException - If namespace is null or invalid (see validateNamespace(String) for constraints).

IOException - If an error occurs during the operation.

cacheVolume

protected void cacheVolume(@Nullable
                           ReceiverStatus receiverStatus)

Caches the Volume instance from the specified ReceiverStatus as as long as neither are null.

Parameters:

receiverStatus - the ReceiverStatus from which to get the Volume to store.

cacheVolume

protected void cacheVolume(@Nullable
                           Volume volume)

Caches the specified Volume instance as long as it's not null.

Parameters:

volume - the Volume instance to store.

acquireResultProcessor

@Nullable
protected Channel.ResultProcessor<? extends Response> acquireResultProcessor(long requestId)

Claims (retrieves and removes from requests) the Channel.ResultProcessorResult for the specified request ID if one exists.

Parameters:

requestId - the request ID to look up.

Returns:

The one and only Channel.ResultProcessor instance for the specified request ID if it exists and hasn't already been claimed, or null.

write

protected void write(String namespace,
                     Message message,
                     String sourceId,
                     String destinationId)
              throws IOException

Writes the specified Message to the socket using the specified parameters.

Parameters:

namespace - the namespace to use.

message - the Message to write.

sourceId - the source ID to use.

destinationId - the destination ID to use.

Throws:

IOException - If an error occurs during the operation.

write

protected void write(String namespace,
                     String message,
                     String sourceId,
                     String destinationId)
              throws IOException

Writes the specified (JSON formatted) String to the socket using the specified parameters.

Parameters:

namespace - the namespace to use.

message - the message content to write.

sourceId - the source ID to use.

destinationId - the destination ID to use.

Throws:

IOException - If an error occurs during the operation.

write

protected void write(CastChannel.CastMessage message)
              throws IOException

Writes the specified CastChannel.CastMessage to the socket.

Parameters:

message - the CastChannel.CastMessage to write.

Throws:

IOException - If an error occurs during the operation.

cancelPendingClosed

protected boolean cancelPendingClosed(@Nullable
                                      String peerId)

Loops through any requests waiting for a response and cancels any that waits for a reply from the specified peer/destination ID. This is to be used when the Session with the specified peer/destination ID has been closed, since there's no point in waiting for a response that will never arrive.

Parameters:

peerId - the peer/destination ID that whose Session has been closed.

Returns:

true if a waiting request was cancelled, false otherwise.

cancelPendingDisconnected

protected void cancelPendingDisconnected()

Loops through all requests waiting for a response and cancels them. This is to be used when the connection disconnects, since there's no point in waiting for a response that will never arrive.

readMessage

@Nonnull
protected static ImmutableCastMessage readMessage(InputStream inputStream)
                                                     throws IOException

Reads the next CastChannel.CastMessage from the specified InputStream in a blocking fashion. This method will not return until a message is either completely read, EOF is reached or an IOException is thrown.

Parameters:

inputStream - the InputStream from which to read.

Returns:

The resulting ImmutableCastMessage.

Throws:

IOException - If EOF is reached or an error occurs-.

isCustomMessage

protected static boolean isCustomMessage(@Nullable
                                         com.fasterxml.jackson.databind.JsonNode parsedMessage)

Determines if the message referenced by the specified JsonNode is among the "standard responses" by looking at the type field exclusively.

Parameters:

parsedMessage - the JsonNode referencing a parsed, received message.

Returns:

true if the message is deemed not to be among the "standard responses", false if it is.

validateNamespace

public static void validateNamespace(@Nonnull
                                     String namespace)
                              throws IllegalArgumentException

Validates that the specified namespace conforms to some very basic constraints.

Parameters:

namespace - the namespace to validate.

Throws:

IllegalArgumentException - If the validation fails.