# Package com.codename1.wearable

package com.codename1.wearable

Talking between a phone app and its watch app.

A watch app and a phone app are two apps on two devices with two sandboxes. Nothing is shared between them automatically: `Storage`, `Preferences` and the SQLite database are per-device, and there is no cross-device container. This package is the channel between them, and it is the same channel on Apple Watch (`WCSession`) and Wear OS (the Wearable Data Layer).

##### Three ways to move information, and how to choose

The platforms offer three transports because they answer three different questions. Picking the wrong one is the usual source of "my watch app didn't get the update":

You need | Use | Delivered
--- | --- | ---
An answer, now, while both apps are awake | `WearableConnection.sendMessage(WearableMessage,WearableReplyHandler)` | Immediately, or it fails
The peer to end up with the latest state, whenever it next looks | `WearableConnection.putData(WearableMessage)` | Eventually, survives sleep and relaunch
To move a file or a large blob | [WearableConnection#transferFile(String,String,byte[])] | In the background, possibly much later

A message is a phone call: it only works if someone picks up (`WearableConnection.isReachable()` is true). Data is a shared noticeboard: you pin the current value at a path and the peer reads it whenever it wakes, so it is what you want for "the watch should show my latest step count". Data replaces the value at a path rather than queueing, so do not use it as a message queue.

##### The dead-process rule

The peer app may not be running when something arrives for it. The platform starts it, which means your listener may not be registered yet. Callbacks that arrive before you register are therefore queued and replayed to your first listener, on the EDT. Register listeners from your `init()` rather than from a form, or you will race the platform and lose the callback that launched you.

##### Degrades instead of failing

Where the platform has no wearable link at all -- a desktop build, or any platform without the API -- there is no bridge, `WearableConnection.isSupported()` returns false and every call is an inert no-op. Application code needs no platform conditionals.

`isSupported()` answers a narrower question than it may appear to: whether the PLATFORM provides the link, not whether a counterpart is there. An iPhone with no watch paired to it still reports true. Use `WearableConnection.isPaired()` to ask whether a counterpart device exists and `WearableConnection.isReachable()` to ask whether its app can receive something now -- offering a wearable feature on the strength of `isSupported()` alone will show it on a phone with no watch.

Merely referencing this package makes the build wire the native plumbing (`WatchConnectivity` on Apple, the `play-services-wearable` dependency and a `WearableListenerService` on Android); apps that never use it pay nothing. See the "Wearables" chapter of the developer guide.

- Related Packages
  Package
  Description
  com.codename1.wearable.spi
  Internal service-provider interface for the `com.codename1.wearable` phone-to-watch API.
- Class
  Description
  WearableConnection
  The link between a phone app and its watch app.
  WearableConnection.DroppedDeliveryHandler
  How a port recovers a parked delivery the cap discarded.
  WearableDataListener
  Notified when replicated data changes on the peer.
  WearableMessage
  A payload addressed to a path, used both for live messages and for replicated data.
  WearableMessageListener
  Notified when the peer app sends a live message.
  WearableNode
  A device on the other end of the link: the watch as seen from the phone, or the phone as seen from the watch.
  WearableReplyHandler
  Receives the answer to a message that asked for one.
  WearableStateListener
  Notified when the link to the peer app changes.