ChannelClient

AI-generated Key Takeaways

• ChannelClient is an interface for the Wearable Channel API allowing data exchange between wearable nodes.

• Channels are bidirectional, enabling both reading and writing via input and output streams.

• Channels require connected wearable nodes and will close upon disconnection.

• Callbacks can be registered to be notified of channel events and changes.

public abstract class ChannelClient extends GoogleApi<Wearable.WearableOptions>

Client interface for Wearable Channel API. Allows apps on a wearable device to send and receive data from other wearable nodes.

Channels are bidirectional. Each side, both the initiator and the receiver may both read and write to the channel by using getOutputStream(Channel) and getInputStream(Channel). Once a channel is established, the API for the initiator and receiver are identical.

Channels are only available when the wearable nodes are connected. When the remote node disconnects, all existing channels will be closed. Any callbacks added through registerChannelCallback(ChannelCallback) and any installed WearableListenerService will be notified of the channel closing.

Nested Class Summary

interface	ChannelClient.Channel		A channel created through ChannelClient.openChannel(String, String).
class	ChannelClient.ChannelCallback		A callback which will be notified on changes to channels.
@interface	ChannelClient.CloseReason		An annotation for values passed to ChannelClient.ChannelCallback.onChannelClosed(ChannelClient.Channel, int, int), and other methods on ChannelClient.ChannelCallback.

Constant Summary

String

ACTION_CHANNEL_EVENT

ChannelClient.Channel action for use in listener filters.

Public Method Summary

abstract Task<Void>	close(ChannelClient.Channel channel, int errorCode) Closes a channel, passing an application-defined error code to the remote node.
abstract Task<Void>	close(ChannelClient.Channel channel) Closes a channel, making any future operations on it invalid.
abstract Task<InputStream>	getInputStream(ChannelClient.Channel channel) Returns an input stream which can read data from the remote node.
abstract Task<OutputStream>	getOutputStream(ChannelClient.Channel channel) Returns an output stream which can send data to a remote node.
abstract Task<ChannelClient.Channel>	openChannel(String nodeId, String path) Opens a channel to exchange data with a remote node.
abstract Task<Void>	receiveFile(ChannelClient.Channel channel, Uri uri, boolean append) Reads input from a channel into a file.
abstract Task<Void>	registerChannelCallback(ChannelClient.Channel channel, ChannelClient.ChannelCallback callback) Registers a callback to be notified of events for a channel.
abstract Task<Void>	registerChannelCallback(ChannelClient.ChannelCallback callback) Registers a callback to be notified of channel events.
abstract Task<Void>	sendFile(ChannelClient.Channel channel, Uri uri) Reads from a file into the output side of a channel.
abstract Task<Void>	sendFile(ChannelClient.Channel channel, Uri uri, long startOffset, long length) Reads from a file into the output side of a channel.
abstract Task<Boolean>	unregisterChannelCallback(ChannelClient.Channel channel, ChannelClient.ChannelCallback callback) Removes a callback which was previously added through registerChannelCallback(Channel, ChannelCallback).
abstract Task<Boolean>	unregisterChannelCallback(ChannelClient.ChannelCallback callback) Removes a callback which was previously added through registerChannelCallback(ChannelCallback).

Inherited Method Summary

From class com.google.android.gms.common.api.GoogleApi

String

getApiFallbackAttributionTag(Context arg0)

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Constants

public static final String ACTION_CHANNEL_EVENT

ChannelClient.Channel action for use in listener filters.

See Also

• WearableListenerService

Constant Value: "com.google.android.gms.wearable.CHANNEL_EVENT"

Public Methods

public abstract Task<Void> close (ChannelClient.Channel channel, int errorCode)

Closes a channel, passing an application-defined error code to the remote node. The error code will be passed to ChannelClient.ChannelCallback.onChannelClosed(ChannelClient.Channel, int, int), and will cause remote reads and writes to the channel to fail with ChannelIOException.

The InputStream and OutputStream returned from getInputStream(Channel) or getOutputStream(Channel) should be closed prior to calling this method. If they are not, both streams will throw ChannelIOException on the next read or write operation.

errorCode == 0 is used to indicate that no error occurred.

Parameters

channel	the ChannelClient.Channel to close.
errorCode	an app-defined error code to pass to the remote node.

public abstract Task<Void> close (ChannelClient.Channel channel)

Closes a channel, making any future operations on it invalid.

This method behaves like close(Channel, int), with errorCode == 0.

Parameters

channel	the ChannelClient.Channel to close.

public abstract Task<InputStream> getInputStream (ChannelClient.Channel channel)

Returns an input stream which can read data from the remote node. The stream should be closed when no longer needed.

The returned stream will throw IOException on read if any connection errors occur. This exception might be a ChannelIOException.

Since data for this stream comes over the network, reads may block for a long time.

This method should only be used once on any channel, and once it has been called, receiveFile(Channel, Uri, boolean) cannot be used.

Parameters

channel	the ChannelClient.Channel to return the InputStream for.

public abstract Task<OutputStream> getOutputStream (ChannelClient.Channel channel)

Returns an output stream which can send data to a remote node. The stream should be closed when no longer needed.

The returned stream will throw IOException on write if any connection errors occur. This exception might be a ChannelIOException.

Data written to this stream is buffered. If you wish to send the current data without waiting for the buffer to fill up, flush the stream.

This method should only be used once on any channel, and once it has been called, sendFile(Channel, Uri, long, long) cannot be used.

Parameters

channel	the ChannelClient.Channel to return the OutputStream for.

public abstract Task<ChannelClient.Channel> openChannel (String nodeId, String path)

Opens a channel to exchange data with a remote node.

ChannelClient.Channel which are no longer needed should be closed using close(Channel).

This call involves a network round trip, so may be long running. client must remain connected during that time, or the request will be cancelled (like any other Play Services API calls).

Parameters

nodeId	the node ID of a wearable node, as returned through CapabilityInfo or NodeClient.getConnectedNodes(), etc.
path	an app-specific identifier for the channel

Returns

• the newly created channel, or null, if the connection couldn't be opened.

public abstract Task<Void> receiveFile (ChannelClient.Channel channel, Uri uri, boolean append)

Reads input from a channel into a file. This is equivalent to calling getInputStream(Channel), reading from the input stream and writing it to a file, but is implemented more efficiently. Writing to the file will be done in a background process owned by Google Play services.

This method should only be used once on any channel, and once it has been called, getInputStream(Channel) cannot be used. The channel should not be immediately closed after calling this method. To be notified when the file is ready, install a ChannelClient.ChannelCallback, with an implementation of ChannelClient.ChannelCallback.onInputClosed(Channel, int, int).

Parameters

channel	the ChannelClient.Channel to receive the file from.
uri	URI of the file into which data should be written. This should be a file URI for a file which is accessible to the current process for writing.
append	if true, data from the channel will be appended to the file, instead of overwriting it.

public abstract Task<Void> registerChannelCallback (ChannelClient.Channel channel, ChannelClient.ChannelCallback callback)

Registers a callback to be notified of events for a channel. This is the same as registerChannelCallback(ChannelCallback), but the callback will only be notified of events for this channel. The callback will not receive ChannelClient.ChannelCallback.onChannelOpened(Channel) events.

Calls to this method should balanced with unregisterChannelCallback(Channel, ChannelCallback) to avoid leaking resources.

Callbacks will be made on the main thread, or the looper set in Wearable.WearableOptions.

Parameters

channel	the ChannelClient.Channel to register the callback on.
callback	a callback which will be notified of changes to the specified stream

public abstract Task<Void> registerChannelCallback (ChannelClient.ChannelCallback callback)

Registers a callback to be notified of channel events. Calls to this method should be balanced with calls to unregisterChannelCallback(ChannelCallback) to avoid leaking resources.

Callbacks will be made on the main thread, or the looper set in Wearable.WearableOptions.

Callers wishing to be notified of events in the background should use WearableListenerService.

Parameters

callback	a callback which will be notified of changes to any channel

public abstract Task<Void> sendFile (ChannelClient.Channel channel, Uri uri)

Reads from a file into the output side of a channel. This is equivalent to calling getOutputStream(Channel), reading from a file and writing into the OutputStream, but is implemented more efficiently. Reading from the file will be done in a background process owned by Google Play services.

This method should only be used once on any channel, and once it has been called, getOutputStream(Channel) cannot be used. The channel should not be immediately closed after calling this method. To be notified when the file has been sent, install a ChannelClient.ChannelCallback, with an implementation of ChannelClient.ChannelCallback.onOutputClosed(Channel, int, int).

This method is identical to calling sendFile(Channel, Uri, long, long) with offset == 0 and length == -1.

Parameters

channel	the ChannelClient.Channel to send the file to.
uri	URI of the file from which data should be read. This should be a file URI for a file which is accessible to the current process for reading.

public abstract Task<Void> sendFile (ChannelClient.Channel channel, Uri uri, long startOffset, long length)

Reads from a file into the output side of a channel. This is equivalent to calling getOutputStream(Channel), reading from a file and writing into the OutputStream, but is implemented more efficiently. Reading from the file will be done in a background process owned by Google Play services.

This method should only be used once on any channel, and once it has been called, getOutputStream(Channel) cannot be used. The channel should not be immediately closed after calling this method. To be notified when the file has been sent, install a ChannelClient.ChannelCallback, with an implementation of ChannelClient.ChannelCallback.onOutputClosed(Channel, int, int).

Parameters

channel	the ChannelClient.Channel to send the file to.
uri	URI of the file from which data should be read. This should be a file URI for a file which is accessible to the current process for reading.
startOffset	byte offset from which to start reading
length	maximum number of bytes to read from the file, or -1 if the file should be read to its end. If the file doesn't contain enough bytes to reach length, fewer bytes will be read.

public abstract Task<Boolean> unregisterChannelCallback (ChannelClient.Channel channel, ChannelClient.ChannelCallback callback)

Removes a callback which was previously added through registerChannelCallback(Channel, ChannelCallback).

public abstract Task<Boolean> unregisterChannelCallback (ChannelClient.ChannelCallback callback)

Removes a callback which was previously added through registerChannelCallback(ChannelCallback).