public interface

# MessageApi

com.google.android.gms.wearable.MessageApi

## Class Overview

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. The `DataApi` 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 the `DataApi` 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.

## Summary

Nested Classes
@interface | MessageApi.FilterType |
interface | MessageApi.MessageListener | Used with `addListener(GoogleApiClient, MessageApi.MessageListener)` to receive message events.
interface | MessageApi.SendMessageResult | Contains the request id assigned to the message.

Constants
String | ACTION_MESSAGE_RECEIVED | Message received action for use in manifest-based listener filters.
int | FILTER_LITERAL | Filter type for `addListener(GoogleApiClient, MessageListener, 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(GoogleApiClient, MessageListener, 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.
int | UNKNOWN_REQUEST_ID | A value returned by `getRequestId()` when `sendMessage(GoogleApiClient, String, String, byte[])` fails.

Public Methods
abstract PendingResult<Status> | addListener(GoogleApiClient client, MessageApi.MessageListener listener, Uri uri, int filterType) Registers a listener to be notified of received messages.
abstract PendingResult<Status> | addListener(GoogleApiClient client, MessageApi.MessageListener listener) Registers a listener to be notified of received messages.
abstract PendingResult<Status> | removeListener(GoogleApiClient client, MessageApi.MessageListener listener) Removes a message listener which was previously added through `addListener(GoogleApiClient, MessageListener)`.
abstract PendingResult<MessageApi.SendMessageResult> | sendMessage(GoogleApiClient client, String nodeId, String path, byte[] data) Sends `byte[]` data to the specified node.

## 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 int FILTER_LITERAL

Filter type for `addListener(GoogleApiClient, MessageListener, 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 (0x00000000)

#### public static final int FILTER_PREFIX

Filter type for `addListener(GoogleApiClient, MessageListener, 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 (0x00000001)

#### public static final int UNKNOWN_REQUEST_ID

A value returned by `getRequestId()` when `sendMessage(GoogleApiClient, String, String, byte[])` fails.

Constant Value: -1 (0xffffffff)

## Public Methods

#### public abstract PendingResult<Status> addListener (GoogleApiClient client, MessageApi.MessageListener listener, Uri uri, int filterType)

Registers a listener to be notified of received messages. Calls to this method should be balanced with `removeListener(GoogleApiClient, MessageListener)` 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>

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

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

#### public abstract PendingResult<Status> addListener (GoogleApiClient client, MessageApi.MessageListener listener)

Registers a listener to be notified of received messages. Calls to this method should be balanced with `removeListener(GoogleApiClient, MessageListener)` 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)`).

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

#### public abstract PendingResult<Status> removeListener (GoogleApiClient client, MessageApi.MessageListener listener)

Removes a message listener which was previously added through `addListener(GoogleApiClient, MessageListener)`.

#### public abstract PendingResult<MessageApi.SendMessageResult> sendMessage (GoogleApiClient client, 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 `getConnectedNodes(GoogleApiClient)` or from the host in `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

- a `PendingResult` that is set when the message is queued to be sent. A successful result doesn't guarantee delivery.