MessageClient

public abstract class MessageClient extends GoogleApi<Wearable.WearableOptions>

Exposes an API for components to send messages to other nodes.

Messages are delivered to connected network nodes. A message is considered successful if it has been queued for delivery to the specified node. A message will only be queued if the specified node is connected. A DataClient should be used for messages to nodes which are not currently connected (to be delivered on connection).

Messages should generally contain ephemeral, small payloads. Use Assets with a DataClient to store more persistent or larger data efficiently.

A message is private to the application that created it and accessible only by that application on other nodes.

Nested Class Summary

@interface MessageClient.FilterType Message filter types. 
interface MessageClient.OnMessageReceivedListener Used with MessageClient.addListener(MessageClient.OnMessageReceivedListener) to receive message events. 
interface MessageClient.RpcService Used with MessageClient.addRpcService(MessageClient.RpcService, String) to receive incoming RPC requests. 

Constant Summary

String ACTION_MESSAGE_RECEIVED Message received action for use in manifest-based listener filters.
String ACTION_REQUEST_RECEIVED RPC request received action for use in manifest-based listener filters.
int FILTER_LITERAL Filter type for addListener(OnMessageReceivedListener, Uri, int): if this filter is set, the given URI will be taken as a literal path, and the operation will apply to the matching message only.
int FILTER_PREFIX Filter type for addListener(OnMessageReceivedListener, Uri, int): if this filter is set, the given URI will be taken as a path prefix, and the operation will apply to all matching messages.

Public Method Summary

abstract Task<Void>
addListener(MessageClient.OnMessageReceivedListener listener, Uri uri, int filterType)
Registers a listener to be notified of received messages.
abstract Task<Void>
addListener(MessageClient.OnMessageReceivedListener listener)
Registers a listener to be notified of received messages.
abstract Task<Void>
addRpcService(MessageClient.RpcService service, String pathPrefix)
Registers a service to deliver RPC requests to.
abstract Task<Void>
addRpcService(MessageClient.RpcService service, String pathPrefix, String nodeId)
Registers a service to deliver RPC requests to.
abstract Task<Boolean>
abstract Task<Boolean>
removeRpcService(MessageClient.RpcService listener)
Removes a listener which was previously added through addRpcService(RpcService, String) or addRpcService(RpcService, String, String) (OnMessageReceivedListener, Uri, int)}.
abstract Task<Integer>
sendMessage(String nodeId, String path, byte[] data)
Sends byte[] data to the specified node.
abstract Task<Integer>
sendMessage(String nodeId, String path, byte[] data, MessageOptions options)
Sends byte[] data to the specified node.
abstract Task<byte[]>
sendRequest(String nodeId, String path, byte[] data)
Sends a RPC request containing byte[] data to the specified node.

Inherited Method Summary

Constants

public static final String ACTION_MESSAGE_RECEIVED

Message received action for use in manifest-based listener filters.

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

public static final String ACTION_REQUEST_RECEIVED

RPC request received action for use in manifest-based listener filters.

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

public static final int FILTER_LITERAL

Filter type for addListener(OnMessageReceivedListener, Uri, int): if this filter is set, the given URI will be taken as a literal path, and the operation will apply to the matching message only.

Constant Value: 0

public static final int FILTER_PREFIX

Filter type for addListener(OnMessageReceivedListener, Uri, int): if this filter is set, the given URI will be taken as a path prefix, and the operation will apply to all matching messages.

Constant Value: 1

Public Methods

public abstract Task<Void> addListener (MessageClient.OnMessageReceivedListener listener, Uri uri, int filterType)

Registers a listener to be notified of received messages. Calls to this method should be balanced with removeListener(OnMessageReceivedListener) to avoid leaking resources.

uri and filterType can be used to filter the messages sent to the listener. For example, if uri and filterType create a path prefix filter, then only messages matching that prefix will be notified. The uri follows the rules of the <data> element of <intent-filter>. The path is ignored if a URI host is not specified. The host should be an Android Wear node ID, or * to match any node. i.e., you should use:

wear://*/<path>
or
wear://<nodeId>/<path>

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

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

public abstract Task<Void> addListener (MessageClient.OnMessageReceivedListener listener)

Registers a listener to be notified of received messages. Calls to this method should be balanced with removeListener(OnMessageReceivedListener) to avoid leaking resources.

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

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

public abstract Task<Void> addRpcService (MessageClient.RpcService service, String pathPrefix)

Registers a service to deliver RPC requests to. Calls to this method should be balanced with removeRpcService(RpcService) to avoid leaking resources.

pathPrefix can be used to filter the messages sent to the listener. If pathPrefix is not "/", then only RPCs matching that prefix will be delivered.

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

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

public abstract Task<Void> addRpcService (MessageClient.RpcService service, String pathPrefix, String nodeId)

Registers a service to deliver RPC requests to. Calls to this method should be balanced with removeRpcService(RpcService) to avoid leaking resources.

pathPrefix and nodeId can be used to filter the messages sent to the listener. If pathPrefix is not "/", then only RPCs matching that prefix will be delivered. The nodeId specifies the Android Wear node ID of the RPC sender.

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

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

public abstract Task<Boolean> removeListener (MessageClient.OnMessageReceivedListener listener)

Removes a listener which was previously added through addListener(OnMessageReceivedListener) or addListener(OnMessageReceivedListener, Uri, int).

public abstract Task<Boolean> removeRpcService (MessageClient.RpcService listener)

Removes a listener which was previously added through addRpcService(RpcService, String) or addRpcService(RpcService, String, String) (OnMessageReceivedListener, Uri, int)}.

public abstract Task<Integer> sendMessage (String nodeId, String path, byte[] data)

Sends byte[] data to the specified node.

Parameters
nodeId identifier for a particular node on the Android Wear network. Valid targets may be obtained through CapabilityClient.getCapability(String, int) or from the host in DataItem.getUri().
path identifier used to specify a particular endpoint at the receiving node
data small array of information to pass to the target node. Generally not larger than 100k
Returns
  • if successful, an ID used to identify the sent message, otherwise an ApiException. A successful result doesn't guarantee delivery.

public abstract Task<Integer> sendMessage (String nodeId, String path, byte[] data, MessageOptions options)

Sends byte[] data to the specified node.

Parameters
nodeId identifier for a particular node on the Android Wear network. Valid targets may be obtained through CapabilityClient.getCapability(String, int) or from the host in DataItem.getUri().
path identifier used to specify a particular endpoint at the receiving node
data small array of information to pass to the target node. Generally not larger than 100k
options options used to specify priority of the message
Returns
  • if successful, an ID used to identify the sent message, otherwise an ApiException. A successful result doesn't guarantee delivery.

public abstract Task<byte[]> sendRequest (String nodeId, String path, byte[] data)

Sends a RPC request containing byte[] data to the specified node.

Parameters
nodeId identifier for a particular node on the Android Wear network. Valid targets may be obtained through CapabilityClient.getCapability(String, int) or from the host in DataItem.getUri().
path identifier used to specify a particular endpoint at the receiving node
data small array of information to pass to the target node. Generally not larger than 100k
Returns
  • if successful, the byte[] payload received from the remote node, otherwise an ApiException. If a response is not received within 1 minute, the returned Task completes with a failure.