DataApi

  • TheDataApi interface is deprecated andDataClient should be used instead.

  • DataApi exposes an API for reading and writing data items and assets on an Android Wear network.

  • Data items are synchronized across all connected devices and are private to the application that created them.

  • Data items should be small, while assets should be used for larger data like images.

  • Data items are identified by a URI in the formatwear://<node_id>/<path>, with support for wildcard node IDs.

  • Concurrent modification of data items from different nodes can lead to inconsistencies, suggesting the use of ownership patterns like creator ownership or producer-consumer.

public interfaceDataApi

This interface is deprecated.
UseDataClient.

Exposes an API for components to read or writedata items andassets.

ADataItem is synchronized across all devices in an Android Wear network. It is possible to set data items while not connected to any nodes. Those data items will be synchronized when the nodes eventually come online.

Data items are private to the application that created them, and are only accessible by that application on other nodes. They should generally be small in size, relying onassets for the transfer of larger, more persistent data objects such as images.

DataItem URI format

Each data item is identified by a URI, accessible withDataItem.getUri(), that indicates the item's creator and path. Fully specified URIs follow the following format:
wear://<node_id>/<path>
where <node_id> is thenode ID of the wearable node that created the data item, and <path> is an application-defined path. This means that given a data item's URI, callingUri.getHost() will return the creator's node ID.

Some methods, such as getDataItems(GoogleApiClient, Uri) and addListener(GoogleApiClient, DataListener, Uri, int), support wildcard node IDs to match data items with the same path or path prefix created by multiple nodes. A wildcard data item URI has the following format:

wear://*/<path>
See method documentation for details.

Concurrency

Concurrent modification of data items from different nodes may result in inconsistent results. It is recommended that apps are built with some concept of ownership of data items. Two common patterns are:
  • Creator owns data items: Data items may be updated only by the original creator node.
  • Producer-consumer: One node is responsible for creating a data item, and a second node is responsible for deleting it, once it has been processed. Data items should have unique IDs when using this pattern, and data items should not be modified once created.

Nested Class Summary

interfaceDataApi.DataItemResultThis interface is deprecated. See DataClient.getDataItem(Uri).  
interfaceDataApi.DataListenerThis interface is deprecated. Use DataClient.OnDataChangedListener.  
interface DataApi.DeleteDataItemsResultThis interface is deprecated. See DataClient.deleteDataItems(Uri).  
@interfaceDataApi.FilterType 
interface DataApi.GetFdForAssetResultThis interface is deprecated. Use DataClient.GetFdForAssetResponse.  

Constant Summary

String ACTION_DATA_CHANGEDData changed action for use in manifest-based listener filters.
intFILTER_LITERALFilter type for getDataItems(GoogleApiClient, Uri, int), deleteDataItems(GoogleApiClient, Uri, int), addListener(GoogleApiClient, DataListener, 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 item only.
intFILTER_PREFIXFilter type for getDataItems(GoogleApiClient, Uri, int), deleteDataItems(GoogleApiClient, Uri, int), addListener(GoogleApiClient, DataListener, 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 items.

Public Method Summary

abstractPendingResult<Status>
addListener(GoogleApiClient client,DataApi.DataListener listener)
Registers a listener to receive data item changed and deleted events.
abstractPendingResult<Status>
addListener(GoogleApiClient client,DataApi.DataListener listener,Uri uri, int filterType)
Registers a listener to receive data item changed and deleted events.
abstractPendingResult<DataApi.DeleteDataItemsResult>
deleteDataItems(GoogleApiClient client,Uri uri, int filterType)
Removes all specifieddata items from the Android Wear network.
abstractPendingResult<DataApi.DeleteDataItemsResult>
deleteDataItems(GoogleApiClient client,Uri uri)
Removes all specifieddata items from the Android Wear network.
abstractPendingResult<DataApi.DataItemResult>
getDataItem(GoogleApiClient client,Uri uri)
Retrieves a singleDataItem from the Android Wear network.
abstractPendingResult<DataItemBuffer>
getDataItems(GoogleApiClient client,Uri uri, int filterType)
Retrieves alldata items matching the provided URI and filter type, from the Android Wear network.
abstractPendingResult<DataItemBuffer>
getDataItems(GoogleApiClient client)
Retrieves alldata items from the Android Wear network.
abstractPendingResult<DataItemBuffer>
getDataItems(GoogleApiClient client,Uri uri)
Retrieves alldata items matching the provided URI, from the Android Wear network.
abstractPendingResult<DataApi.GetFdForAssetResult>
getFdForAsset(GoogleApiClient client,Asset asset)
Retrieves aParcelFileDescriptor pointing at the bytes of an asset.
abstractPendingResult<DataApi.GetFdForAssetResult>
getFdForAsset(GoogleApiClient client,DataItemAsset asset)
Retrieves aParcelFileDescriptor pointing at the bytes of an asset.
abstractPendingResult<DataApi.DataItemResult>
putDataItem(GoogleApiClient client,PutDataRequest request)
Adds aDataItem to the Android Wear network.
abstractPendingResult<Status>
removeListener(GoogleApiClient client,DataApi.DataListener listener)
Removes a data listener which was previously added through addListener(GoogleApiClient, DataListener).

Constants

public static finalStringACTION_DATA_CHANGED

Data changed action for use in manifest-based listener filters.

Constant Value:"com.google.android.gms.wearable.DATA_CHANGED"

public static final intFILTER_LITERAL

Filter type for getDataItems(GoogleApiClient, Uri, int), deleteDataItems(GoogleApiClient, Uri, int), addListener(GoogleApiClient, DataListener, 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 item only.

Constant Value:0

public static final intFILTER_PREFIX

Filter type for getDataItems(GoogleApiClient, Uri, int), deleteDataItems(GoogleApiClient, Uri, int), addListener(GoogleApiClient, DataListener, 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 items.

Constant Value:1

Public Methods

public abstractPendingResult<Status>addListener(GoogleApiClient client,DataApi.DataListener listener)

Registers a listener to receive data item changed and deleted events. This call should be balanced with a call to removeListener(GoogleApiClient, DataListener), to avoid leaking resources.

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

public abstractPendingResult<Status>addListener(GoogleApiClient client,DataApi.DataListener listener,Uri uri, int filterType)

Registers a listener to receive data item changed and deleted events. This call should be balanced with a call to removeListener(GoogleApiClient, DataListener), to avoid leaking resources.

uri andfilterType can be used to filter the data item changes sent to the listener. For example, ifuri andfilterType create a path prefix filter, then only items matching that prefix will be notified. Theuri 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. For example, you should use:

wear://*/<path>
or
wear://<nodeId>/<path>

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

public abstractPendingResult<DataApi.DeleteDataItemsResult>deleteDataItems(GoogleApiClient client,Uri uri, int filterType)

Removes all specifieddata items from the Android Wear network.

Ifuri is fully specified, this method will delete at most one data item. Ifuri contains a wildcard host, multiple data items may be deleted, since different nodes may create data items with the same path. SeeDataApi for details of the URI format.

ThefilterType parameter changes the interpretation ofuri. For example, ifuri represents a path prefix, all items matching that prefix will be deleted.

public abstractPendingResult<DataApi.DeleteDataItemsResult>deleteDataItems(GoogleApiClient client,Uri uri)

Removes all specifieddata items from the Android Wear network.

Ifuri is fully specified, this method will delete at most one data item. Ifuri contains a wildcard host, multiple data items may be deleted, since different nodes may create data items with the same path. SeeDataApi for details of the URI format.

public abstractPendingResult<DataApi.DataItemResult>getDataItem(GoogleApiClient client,Uri uri)

Retrieves a singleDataItem from the Android Wear network. A fully qualified URI must be specified. The URI's host must be the ID of the node that created the item.

SeeDataApi for details of the URI format.

public abstractPendingResult<DataItemBuffer>getDataItems(GoogleApiClient client,Uri uri, int filterType)

Retrieves alldata items matching the provided URI and filter type, from the Android Wear network.

The URI must contain a path. Ifuri is fully specified, at most one data item will be returned. Ifuri contains a wildcard host, multiple data items may be returned, since different nodes may create data items with the same path. SeeDataApi for details of the URI format.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

ThefilterType parameter changes the interpretation ofuri. For example, ifuri represents a path prefix, all items matching that prefix will be returned.

public abstractPendingResult<DataItemBuffer>getDataItems(GoogleApiClient client)

Retrieves alldata items from the Android Wear network.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

public abstractPendingResult<DataItemBuffer>getDataItems(GoogleApiClient client,Uri uri)

Retrieves alldata items matching the provided URI, from the Android Wear network.

The URI must contain a path. Ifuri is fully specified, at most one data item will be returned. Ifuri contains a wildcard host, multiple data items may be returned, since different nodes may create data items with the same path. SeeDataApi for details of the URI format.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

public abstractPendingResult<DataApi.GetFdForAssetResult>getFdForAsset(GoogleApiClient client,Asset asset)

Retrieves aParcelFileDescriptor pointing at the bytes of an asset. Only assets previously stored in aDataItem may be retrieved.

public abstractPendingResult<DataApi.GetFdForAssetResult>getFdForAsset(GoogleApiClient client,DataItemAsset asset)

Retrieves aParcelFileDescriptor pointing at the bytes of an asset. Only assets previously stored in aDataItem may be retrieved.

public abstractPendingResult<DataApi.DataItemResult>putDataItem(GoogleApiClient client,PutDataRequest request)

Adds aDataItem to the Android Wear network. The updated item is synchronized across all devices.

public abstractPendingResult<Status>removeListener(GoogleApiClient client,DataApi.DataListener listener)

Removes a data listener which was previously added through addListener(GoogleApiClient, DataListener).

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-11-21 UTC.