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 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.