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 Asset
s 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> | |
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.
See Also
public static final String ACTION_REQUEST_RECEIVED
RPC request received action for use in manifest-based listener filters.
See Also
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.
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.
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>
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.