Channel

public interface Channel implements Parcelable

A channel created through openChannel(GoogleApiClient, String, String).

The implementation of this interface is parcelable and immutable, and implements reasonable equals(Object) and hashCode() methods, so can be used in collections.

Nested Class Summary

interface Channel.GetInputStreamResult Result of getInputStream(GoogleApiClient). 
interface Channel.GetOutputStreamResult Result of getOutputStream(GoogleApiClient). 

Inherited Constant Summary

Public Method Summary

abstract PendingResult<Status>
addListener(GoogleApiClient client, ChannelApi.ChannelListener listener)
Registers a listener to be notified of events for this channel.
abstract PendingResult<Status>
close(GoogleApiClient client, int errorCode)
Closes this channel, passing an application-defined error code to the remote node.
abstract PendingResult<Status>
close(GoogleApiClient client)
Closes this channel, making any future operations on it invalid.
abstract PendingResult<Channel.GetInputStreamResult>
getInputStream(GoogleApiClient client)
Opens the input side of the channel to receive data from the remote node.
abstract String
getNodeId()
Returns the node ID of the node on the other side of the channel.
abstract PendingResult<Channel.GetOutputStreamResult>
getOutputStream(GoogleApiClient client)
Opens the output side of the channel to send data to the remote node.
abstract String
getPath()
Returns the path that was used to open the channel.
abstract PendingResult<Status>
receiveFile(GoogleApiClient client, Uri uri, boolean append)
Reads input from this channel into a file.
abstract PendingResult<Status>
removeListener(GoogleApiClient client, ChannelApi.ChannelListener listener)
Removes a listener which was previously added through addListener(GoogleApiClient, ChannelApi.ChannelListener).
abstract PendingResult<Status>
sendFile(GoogleApiClient client, Uri uri)
Reads from a file into the output side of the channel.
abstract PendingResult<Status>
sendFile(GoogleApiClient client, Uri uri, long startOffset, long length)
Reads from a file into the output side of the channel.

Inherited Method Summary

Public Methods

public abstract PendingResult<Status> addListener (GoogleApiClient client, ChannelApi.ChannelListener listener)

Registers a listener to be notified of events for this channel. This is the same as addListener(GoogleApiClient, ChannelApi.ChannelListener), but the listener will only be notified of events for this channel. The listener will not receive onChannelOpened(Channel) events.

Calls to this method should balanced with removeListener(GoogleApiClient, ChannelApi.ChannelListener) to avoid leaking resources.

Listener events will be called on the main thread, or the handler specified on client when it was built (using setHandler(Handler)).

Parameters
client a connected client
listener a listener which will be notified of changes to the specified stream

public abstract PendingResult<Status> close (GoogleApiClient client, int errorCode)

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

The InputStream and OutputStream returned from getInputStream(GoogleApiClient) or getOutputStream(GoogleApiClient) 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
client a connected client
errorCode an app-defined error code to pass to the remote node

public abstract PendingResult<Status> close (GoogleApiClient client)

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

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

Parameters
client a connected client

public abstract PendingResult<Channel.GetInputStreamResult> getInputStream (GoogleApiClient client)

Opens the input side of the channel to receive data from the remote node. Methods on the returned input stream may throw ChannelIOException. See GetInputStreamResult.getInputStream()

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

Parameters
client a connected client

public abstract String getNodeId ()

Returns the node ID of the node on the other side of the channel.

public abstract PendingResult<Channel.GetOutputStreamResult> getOutputStream (GoogleApiClient client)

Opens the output side of the channel to send data to the remote node. Methods on the returned output stream may throw ChannelIOException. See GetOutputStreamResult.getOutputStream()

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

Parameters
client a connected client

public abstract String getPath ()

Returns the path that was used to open the channel.

public abstract PendingResult<Status> receiveFile (GoogleApiClient client, Uri uri, boolean append)

Reads input from this channel into a file. This is equivalent to calling getInputStream(GoogleApiClient), 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 was called, getInputStream(GoogleApiClient) cannot be used. The channel should not be immediately closed after calling this method. To be notified when the file is ready, install a ChannelApi.ChannelListener, with an implementation of onInputClosed(Channel, int, int).

Parameters
client a connected client
uri URI of the file into which data should be written. This should be a {@linkplain Uri#fromFile(java.io.File) 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 PendingResult<Status> removeListener (GoogleApiClient client, ChannelApi.ChannelListener listener)

Removes a listener which was previously added through addListener(GoogleApiClient, ChannelApi.ChannelListener).

Parameters
client a connected client
listener a listener which was added using addListener(GoogleApiClient, ChannelApi.ChannelListener)

public abstract PendingResult<Status> sendFile (GoogleApiClient client, Uri uri)

Reads from a file into the output side of the channel. This is equivalent to calling getOutputStream(GoogleApiClient), 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 was called, getOutputStream(GoogleApiClient) 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 ChannelApi.ChannelListener, with an implementation of onOutputClosed(Channel, int, int).

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

Parameters
client a connected client
uri URI of the file from which data should be read. This should be a {@linkplain Uri#fromFile(java.io.File) file URI} for a file which is accessible to the current process for reading.

public abstract PendingResult<Status> sendFile (GoogleApiClient client, Uri uri, long startOffset, long length)

Reads from a file into the output side of the channel. This is equivalent to calling getOutputStream(GoogleApiClient), 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 was called, getOutputStream(GoogleApiClient) 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 ChannelApi.ChannelListener, with an implementation of onOutputClosed(Channel, int, int).

Parameters
client a connected client
uri URI of the file from which data should be read. This should be a {@linkplain Uri#fromFile(java.io.File) 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.