From b3a449c53df4bf32610a679c10dee23572b40bcd Mon Sep 17 00:00:00 2001 From: David Friedman Date: Mon, 29 Feb 2016 20:20:30 -0800 Subject: [PATCH] Docs: Adds info about setUrgent() to Syncing Data Items. Bug: 25702199 Change-Id: I95c4c8f3b7d7123c23bc2096580ff99ed36965f8 --- .../wearables/data-layer/data-items.jd | 71 ++++++++++++++++--- 1 file changed, 63 insertions(+), 8 deletions(-) diff --git a/docs/html/training/wearables/data-layer/data-items.jd b/docs/html/training/wearables/data-layer/data-items.jd index 520a06ad889b4..b5269463c2f98 100644 --- a/docs/html/training/wearables/data-layer/data-items.jd +++ b/docs/html/training/wearables/data-layer/data-items.jd @@ -38,25 +38,34 @@ directly. Instead, you:
  • Call setData() to set the payload.
    • + +
  • + If a delay in syncing would negatively impact user experience, call + + {@code setUrgent()}. +
    • +
  • Call DataApi.putDataItem() to request the system to create the data item.
    • -
  • When requesting data items, the system returns objects - that properly implement the DataItem interface. -
    • - +

    -However, instead of working with raw bytes using setData(), -we recommend you use a data map, which exposes +When requesting data items, the system returns objects that properly implement the +DataItem + interface. However, instead of working with raw bytes using + +setData(), we recommend you use a data map, which exposes a data item in an easy-to-use {@link android.os.Bundle}-like interface.

    Sync Data with a Data Map

    -When possible, use the DataMap class. +When possible, use the +DataMap class. This approach lets you work with data items in the form of an Android {@link android.os.Bundle}, -so object serialization and de-serialization is done for you, and you can manipulate data with key-value pairs. +so the system does object serialization and deserialization for you, and you can manipulate data +with key-value pairs.

    To use a data map:

    @@ -77,11 +86,23 @@ app, you should create a path scheme that matches the structure of the data.
  • Set any desired values for the data map using the put...() methods, such as putString().
    • + +
  • + If a delay in syncing would negatively impact user experience, call + + {@code setUrgent()}. +
    • + +
  • Call PutDataMapRequest.asPutDataRequest() to obtain a PutDataRequest object.
    • + +
  • Call DataApi.putDataItem() to request the system to create the data item. +

    Note: + If the handset and wearable devices are disconnected, the data is buffered and synced when the connection is re-established.

    @@ -124,6 +145,40 @@ public class MainActivity extends Activity implements Layer Calls.

    +

    Set DataItem priority

    + +

    +In Google Play services 8.3 and later, +the +{@code DataApi} interface +allows urgent requests for syncing of +{@code DataItems}. +Normally, the system may delay delivery of +{@code DataItems} +to the Wear network in order to improve battery life +for user devices, but if a delay in syncing +{@code DataItems} +would negatively impact user experience, you +can mark them as urgent. For example, in a remote control app where the user expects their actions to be +reflected immediately, you can have the system sync your +{@code DataItems} +immediately by calling + +{@code setUrgent()}. +

    + +

    +If you do not call + +{@code setUrgent()}, the system may delay up to 30 minutes before syncing non-urgent +{@code DataItems}, +but you can usually expect the delay to be a few minutes, if at all. +The default urgency is now non-urgent, so you must use + +{@code setUrgent()} if you wish to retain the immediate-sync behavior that +existed in previous versions of the Wear API. +

    +

    Listen for Data Item Events

    If one side of the data layer connection changes a data item, you probably want