MessageClient

AI-generated Key Takeaways

• MessageClient exposes an API for components to send messages to other connected network nodes.

• Messages should contain ephemeral, small payloads, with larger or persistent data handled by DataClient using Assets.

• Messages are private to the application that created them and are only accessible by that application on other nodes.

• Listeners can be registered to receive message events, either on the main thread or a looper, and can be filtered by URI and filter type.

• Services can be registered to deliver RPC requests, also with filtering options for path prefix and node ID.

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>	removeListener(MessageClient.OnMessageReceivedListener listener) Removes a listener which was previously added through addListener(OnMessageReceivedListener) or addListener(OnMessageReceivedListener, Uri, int).
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<byte[]>	sendRequest(String nodeId, String path, byte[] data) Sends a RPC request containing byte[] data to the specified node.

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_MESSAGE_RECEIVED

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

See Also

• WearableListenerService

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.

See Also

• WearableListenerService

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. For example, 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<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.