# Class WearableConnection

java.lang.Object
com.codename1.wearable.WearableConnection

public final class WearableConnection extends Object

The link between a phone app and its watch app. The same API on both ends, and the same API on Apple Watch and Wear OS.

    // On the phone: publish state the watch should show whenever it next wakes.
    WearableConnection.putData(new WearableMessage("/steps").put("count", steps));

    // On the watch: react to it, and ask for a fresh value on demand.
    WearableConnection.addDataListener(new WearableDataListener() {
        public void dataChanged(WearableMessage data) { label.setText("" + data.getInt("count", 0)); }
        public void dataRemoved(String path) { label.setText("--"); }
    });

Register listeners from your app's `init()`. A payload that arrives before the first listener is registered -- including the one that made the platform launch your app -- is queued and replayed, but only to a listener that exists by the time the EDT gets to it.

When there is nothing on the other end, `isSupported()` returns false and every call here is an inert no-op, so this API needs no platform conditionals around it. See the package documentation for how to choose between a message, replicated data and a file transfer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addDataListener(WearableDataListener l)`
  Registers a listener for replicated data changes.
  `static void`
  `addMessageListener(WearableMessageListener l)`
  Registers a listener for live messages from the peer.
  `static void`
  `addStateListener(WearableStateListener l)`
  Registers a listener for changes to the link itself -- reachability, pairing, whether the peer app is installed.
  `static void`
  `deliverDataChanged(String path, byte[] payload)`
  Framework/port entry point: reports that the peer published or updated a replicated value.
  `static void`
  `deliverDataRemoved(String path)`
  Framework/port entry point: reports that the peer removed a replicated value.
  `static void`
  `deliverMessage(String path, byte[] payload, int replyToken)`
  Framework/port entry point: hands a message received from the peer to the app.
  `static void`
  `deliverReply(int replyToken, byte[] payload, String error)`
  Framework/port entry point: hands the peer's answer to the waiting reply handler.
  `static List<WearableNode>`
  `getConnectedNodes()`
  Returns the counterpart devices currently connected.
  `static WearableMessage`
  `getData(String path)`
  Reads the replicated value at a path, as published by either side.
  `static List<String>`
  `getDataPaths()`
  Returns every path that currently holds a replicated value.
  `static boolean`
  `isCompanionAppInstalled()`
  Returns true when the counterpart app is installed on the paired device.
  `static boolean`
  `isPaired()`
  Returns true when a counterpart device is paired, whether or not it is switched on or in range.
  `static boolean`
  `isReachable()`
  Returns true when the peer app can receive a live message right now.
  `static boolean`
  `isSupported()`
  Returns true when this device can talk to a counterpart app at all.
  `static void`
  `notifyStateChanged()`
  Framework/port entry point: reports that reachability, pairing or peer-app installation changed.
  `static void`
  `putData(WearableMessage data)`
  Publishes the current value at a path, replacing whatever was there.
  `static void`
  `removeData(String path)`
  Removes the replicated value at a path.
  `static void`
  `removeDataListener(WearableDataListener l)`
  Removes a previously registered data listener.
  `static void`
  `removeMessageListener(WearableMessageListener l)`
  Removes a previously registered message listener.
  `static void`
  `removeStateListener(WearableStateListener l)`
  Removes a previously registered state listener.
  `static void`
  `sendMessage(WearableMessage message)`
  Sends a live message to the peer app, with no reply expected.
  `static void`
  `sendMessage(WearableMessage message, WearableReplyHandler reply)`
  Sends a live message to the peer app and waits for its answer.
  `static void`
  `transferFile(String path, String name, byte[] contents)`
  Sends a file to the peer in the background.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isSupported

    public static boolean isSupported()

    Returns true when this device can talk to a counterpart app at all. False on a desktop build, on a phone whose platform has no wearable link, and in the simulator with no watch window open. When this is false every other call here does nothing.

    ###### Returns

    true if the wearable link is available

  - ### isPaired

    public static boolean isPaired()

    Returns true when a counterpart device is paired, whether or not it is switched on or in range.

    ###### Returns

    true if a counterpart device is paired

  - ### isReachable

    public static boolean isReachable()

    Returns true when the peer app can receive a live message right now. This is the condition `sendMessage(WearableMessage)` needs; `putData(WearableMessage)` does not.

    ###### Returns

    true if the peer app is reachable

  - ### isCompanionAppInstalled

    public static boolean isCompanionAppInstalled()

    Returns true when the counterpart app is installed on the paired device. A watch that is paired but has no watch app installed is worth prompting the user about, and is the usual reason a correct-looking `sendMessage` never arrives.

    ###### Returns

    true if the peer app is installed

  - ### getConnectedNodes

    public static List<WearableNode> getConnectedNodes()

    Returns the counterpart devices currently connected. Apple pairs one watch at a time, so expect at most one; Wear OS allows several.

    ###### Returns

    the connected nodes, never null

  - ### sendMessage

    public static void sendMessage(WearableMessage message)

    Sends a live message to the peer app, with no reply expected.

    The message is delivered only if the peer is reachable; if it is not, the message is dropped. Use `putData(WearableMessage)` when the peer needs to see it eventually rather than now.

    ###### Parameters

    - `message`: the payload to send

  - ### sendMessage

    public static void sendMessage(WearableMessage message, WearableReplyHandler reply)

    Sends a live message to the peer app and waits for its answer.

    Exactly one method on the handler is called, on the EDT. A reply is not guaranteed: the peer may be asleep, out of range, or running a version of your app that does not know this path.

    ###### Parameters

    - `message`: the payload to send
    - `reply`: notified with the answer, or null when no answer is wanted

  - ### putData

    public static void putData(WearableMessage data)

    Publishes the current value at a path, replacing whatever was there.

    This is the transport to reach for by default. The value survives both apps being killed and reaches the peer whenever it next runs, so the peer always converges on the latest value. Because each path holds one value, this is state replication and not a message queue -- two rapid updates to the same path may be collapsed into one delivery.

    ###### Parameters

    - `data`: the payload to publish, addressed to the path to publish under

  - ### getData

    public static WearableMessage getData(String path)

    Reads the replicated value at a path, as published by either side.

    ###### Parameters

    - `path`: the path to read

    ###### Returns

    the value, or null when nothing is published at that path

  - ### removeData

    public static void removeData(String path)

    Removes the replicated value at a path. The peer is notified through `WearableDataListener.dataRemoved(String)`.

    ###### Parameters

    - `path`: the path to clear

  - ### getDataPaths

    public static List<String> getDataPaths()

    Returns every path that currently holds a replicated value.

    ###### Returns

    the published paths, never null

  - ### transferFile

    public static void transferFile(String path, String name, byte[] contents)

    Sends a file to the peer in the background.

    Delivery is not immediate and may happen after this app has exited -- that is the point. Use it for anything too big for a message: a captured image, a synced document, a map tile.

    ###### Parameters

    - `path`: the path the peer matches on
    - `name`: the file name to present to the peer
    - `contents`: the file bytes

  - ### addMessageListener

    public static void addMessageListener(WearableMessageListener l)

    Registers a listener for live messages from the peer. Register from your app's `init()`: a message queued while the app was starting is replayed only to listeners that exist by the time the EDT drains the queue.

    ###### Parameters

    - `l`: the listener to add

  - ### removeMessageListener

    public static void removeMessageListener(WearableMessageListener l)

    Removes a previously registered message listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### addDataListener

    public static void addDataListener(WearableDataListener l)

    Registers a listener for replicated data changes. Register from your app's `init()` for the same reason as `addMessageListener(WearableMessageListener)`.

    ###### Parameters

    - `l`: the listener to add

  - ### removeDataListener

    public static void removeDataListener(WearableDataListener l)

    Removes a previously registered data listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### addStateListener

    public static void addStateListener(WearableStateListener l)

    Registers a listener for changes to the link itself -- reachability, pairing, whether the peer app is installed.

    ###### Parameters

    - `l`: the listener to add

  - ### removeStateListener

    public static void removeStateListener(WearableStateListener l)

    Removes a previously registered state listener.

    ###### Parameters

    - `l`: the listener to remove

  - ### deliverMessage

    public static void deliverMessage(String path, byte[] payload, int replyToken)

    Framework/port entry point: hands a message received from the peer to the app. Called by the platform port on whatever thread the native transport uses; delivery is marshalled to the EDT, and queued if no listener has been registered yet.

    ###### Parameters

    - `path`: the path the message arrived on
    - `payload`: the encoded payload
    - `replyToken`: a positive token when the peer is waiting for an answer, otherwise 0

  - ### deliverReply

    public static void deliverReply(int replyToken, byte[] payload, String error)

    Framework/port entry point: hands the peer's answer to the waiting reply handler. Called by the platform port; a token with no waiting handler is ignored.

    ###### Parameters

    - `replyToken`: the token returned with the original request
    - `payload`: the encoded reply payload, or null when the request failed
    - `error`: a description of the failure, or null on success

  - ### deliverDataChanged

    public static void deliverDataChanged(String path, byte[] payload)

    Framework/port entry point: reports that the peer published or updated a replicated value. Called by the platform port; queued across a cold start like a message.

    ###### Parameters

    - `path`: the path whose value changed
    - `payload`: the encoded new value

  - ### deliverDataRemoved

    public static void deliverDataRemoved(String path)

    Framework/port entry point: reports that the peer removed a replicated value. Called by the platform port.

    ###### Parameters

    - `path`: the path whose value is gone

  - ### notifyStateChanged

    public static void notifyStateChanged()
    Framework/port entry point: reports that reachability, pairing or peer-app installation changed. Called by the platform port. Unlike payload delivery this is not queued -- state is re-queried by the listener, so a stale notification is worthless.