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> | |
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> | |
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
Constants
public static final String ACTION_CHANNEL_EVENT
ChannelClient.Channel
action for use in listener filters.
See Also
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)
.