drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: Fixes to the Data Layer Wear class." into lmp-dev

Browse Source
This commit is contained in:
Ricardo Cervera
2014-11-20 19:49:52 +00:00
committed by Android (Google) Code Review
parent c79173c7da eff209d2c4
commit c8543b4f46
7 changed files with 81 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/html/google/play-services/setup.jd
View File

@ -60,7 +60,8 @@ to <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</
<a href="{@docRoot}sdk/installing/studio-build.html">Building Your Project with
Gradle</a> for more information about Gradle.</p></li>
<li>Add a new build rule under <code>dependencies</code> for the latest version of
<code>play-services</code>. For example:
<code>play-services</code>.
<p>For example, for mobile modules:</p>
<pre class="no-pretty-print">
apply plugin: 'android'
...
@ -70,7 +71,16 @@ dependencies {
<strong>compile 'com.google.android.gms:play-services:6.1.+'</strong>
}
</pre>
<p>Be sure you update this version number each time Google Play services is updated.</p>
<p>For wearable modules:</p>
<pre class="no-pretty-print">
apply plugin: 'android'
...
dependencies {
<strong>compile 'com.google.android.gms:play-services-wearable:6.1.+'</strong>
}
</pre>
<p>Be sure you update this version number each time Google Play services is updated.</p>
</li>
<li>Save the changes and click <strong>Sync Project with Gradle Files</strong>
<img src="{@docRoot}images/tools/sync-project.png" style="vertical-align:bottom;margin:0;height:19px" />

14
docs/html/training/wearables/data-layer/accessing.jd
View File

@ -20,7 +20,7 @@ page.title=Accessing the Wearable Data Layer
</div>
</div>
<p>To call the data layer API, create an instance of
<p>To call the Data Layer API, create an instance of
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html"><code>GoogleApiClient</code></a>,
the main entry point for any of the Google Play services APIs.
</p>
@ -42,7 +42,7 @@ GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this)
&#64;Override
public void onConnected(Bundle connectionHint) {
Log.d(TAG, "onConnected: " + connectionHint);
// Now you can use the data layer API
// Now you can use the Data Layer API
}
&#64;Override
public void onConnectionSuspended(int cause) {
@ -71,8 +71,10 @@ Wearable}</a> API. For more information, see <a
href="{@docRoot}google/auth/api-client.html#WearableApi">Access the Wearable API</a>.</p>
<p>Before you use the data layer API, start a connection on your client by calling the
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()">connect()</a>
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()">
<code>connect()</code></a>
method, as described in
<a href="{@docRoot}google/auth/api-client.html#Starting">Accessing Google Play services APIs</a>.
When the system invokes the <code>onConnected()</code> callback for your client, you're ready
to use the data layer API.</p>
<a href="{@docRoot}google/auth/api-client.html#Starting">Start a Connection</a>.
When the system invokes the
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">
<code>onConnected()</code></a> callback for your client, you're ready to use the Data Layer API.</p>

14
docs/html/training/wearables/data-layer/assets.jd
View File

@ -16,18 +16,18 @@ page.title=Transferring Assets
<p>
To send large blobs of binary data over the Bluetooth transport, such as images, attach an
<a href="{@docRoot}reference/com/google/android/gms/wearable/Asset.html">Asset</a> to a
<a href="{@docRoot}reference/com/google/android/gms/wearable/Asset.html"><code>Asset</code></a> to a
data item and the put the data item into the replicated data store.
</p>
<p>Assets automatically handle caching of data to prevent retransmission and conserve Bluetooth bandwidth.
A common pattern is for a handheld app to download an image, shrink it to an appropriate size
for display on the wearable, and transmit it to the wearable app as an Asset. The following examples
demonstrates this pattern.
for display on the wearable, and transmit it to the wearable app as an asset. The following examples
demonstrate this pattern.
</p>
<p class="note"><b>Note:</b> Although the size of data items are limited to 100KB,
assets can be as large as desired. However, transferring large assets affect the
<p class="note"><b>Note:</b> Although the size of data items is limited to 100KB,
assets can be as large as desired. However, transferring large assets affects the
user experience in many cases, so test your apps to ensure that they perform well
if you're transferring large assets.
<p>
@ -49,7 +49,6 @@ private static Asset createAssetFromBitmap(Bitmap bitmap) {
</pre>
<p>When you have an asset, attach it to a data item with the <code>putAsset()</code> method in
<a href="{@docRoot}reference/com/google/android/gms/wearable/DataMap.html"><code>DataMap</code></a>
or
<a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html"><code>PutDataRequest</code></a>
@ -77,12 +76,13 @@ PendingResult&lt;DataApi.DataItemResult&gt; pendingResult = Wearable.DataApi
.putDataItem(mGoogleApiClient, request);
</pre>
<h2 id="ReceiveAsset">Receive assets</h2>
<p>
When an asset is created, you probably want to read and extract
it on other side of the connection. Here's an example of how to implement the
callback to detect an asset change and extract the Asset:
callback to detect an asset change and extract the asset:
</p>
<pre>

22
docs/html/training/wearables/data-layer/data-items.jd
View File

@ -15,9 +15,9 @@ page.title=Syncing Data Items
</div>
<p>
A <a href="@{docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a>
A <a href="{@docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a>
defines the data interface that the system uses to synchronize data between handhelds
and wearables. A <a href="@{docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a> generally
and wearables. A <a href="{@docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a> generally
consists of the following items:</p>
<ul>
<li><b>Payload</b> - A byte array, which you can set with whatever data you wish, allowing you
@ -28,15 +28,15 @@ consists of the following items:</p>
</ul>
<p>
You normally don't implement <a href="@{docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a>
You normally don't implement <a href="{@docRoot}reference/com/google/android/gms/wearable/DataItem.html"><code>DataItem</code></a>
directly. Instead, you:
<ol>
<li>Create a <a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html"><code>PutDataRequest</code></a> object,
specifying a string path to uniquely identify the item.
</li>
<li>Call <a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html#setData(byte[])">setData()</a> to set
the payload.
<li>Call <a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html#setData(byte[])">
<code>setData()</code></a> to set the payload.
</li>
<li>Call <a href="{@docRoot}reference/com/google/android/gms/wearable/DataApi.html#putDataItem(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.wearable.PutDataRequest)"><code>DataApi.putDataItem()</code></a> to request the system to create the data item.
</li>
@ -51,6 +51,7 @@ we recommend you <a href="#SyncData">use a data map</a>, which exposes
a data item in an easy-to-use {@link android.os.Bundle}-like interface.
</p>
<h2 id="SyncData">Sync Data with a Data Map</h2>
<p>
When possible, use the <a href="{@docRoot}reference/com/google/android/gms/wearable/DataMap.html"><code>DataMap</code></a> class.
@ -67,7 +68,7 @@ object, setting the path of the data item.
<p class="note"><b>Note:</b> The path string is a unique identifier for the
data item that allows you to access it from either side of the connection. The path must begin
with a forward slash. If you're using hierarchical data in your
app, you should create a path scheme that matches the structure of the data.
app, you should create a path scheme that matches the structure of the data.
</p>
</li>
<li>Call
@ -82,12 +83,12 @@ app, you should create a path scheme that matches the structure of the data.
<li>Call <a href="{@docRoot}reference/com/google/android/gms/wearable/DataApi.html#putDataItem(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.wearable.PutDataRequest)"><code>DataApi.putDataItem()</code></a> to request the system to create the data item.
<p class="note"><b>Note:</b>
If the handset and wearable devices are disconnected,
the data is buffered and and synced when the connection is re-established.
the data is buffered and synced when the connection is re-established.
</p>
</li>
</ol>
<p>The following example shows how to create a data map, set data on it, and create it:</p>
<p>The following example shows how to create a data map and put data on it:</p>
<pre>
PutDataMapRequest dataMap = PutDataMapRequest.create("/count");
@ -103,7 +104,7 @@ to be notified of any changes on the other side of the connection.
You can do this by implementing a listener for data item events.
<p>For example, here's what a typical callback looks like to carry out certain actions
when data changes.</p>
when data changes:</p>
<pre>
&#64;Override
@ -120,5 +121,6 @@ public void onDataChanged(DataEventBuffer dataEvents) {
<p>
This is just a snippet that requires more implementation details. Learn about
how to implement a full listener service or activity in
<a href="{@docRoot}training/wearables/data-layer/events.html#Listen">Listening for Data Layer Events</a>.
<a href="{@docRoot}training/wearables/data-layer/events.html#Listen">Listen for Data Layer
Events</a>.
</p>

44
docs/html/training/wearables/data-layer/events.jd
View File

@ -14,14 +14,14 @@ page.title=Handling Data Layer Events
</div>
</div>
<p>When you make calls with the data layer, you can receive the status
<p>When you make calls to the Data Layer API, you can receive the status
of the call when it completes as well as listen for any changes that
the call ends up making with listeners.
</p>
<h2 id="Wait">Wait for the Status of Data Layer Calls</h2>
<p>You'll notice that calls to the data layer API sometimes return a
<p>You'll notice that calls to the Data Layer API sometimes return a
<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html"><code>PendingResult</code></a>,
such as
<a href="{@docRoot}reference/com/google/android/gms/wearable/DataApi.html#putDataItem(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.wearable.PutDataRequest)"><code>putDataItem()</code></a>.
@ -33,9 +33,9 @@ after the operation completes, so the
lets you wait for the result status, either synchronously or asynchronously.
</p>
<h3 id="async-waiting">Asynchronously waiting</h3>
<p>If your code is running on the main UI thread, do not making blocking calls
to the data layer API. You can run the calls asynchronously by adding a callback
<h3 id="async-waiting">Asynchronous calls</h3>
<p>If your code is running on the main UI thread, do not make blocking calls
to the Data Layer API. You can run the calls asynchronously by adding a callback method
to the <a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html"><code>PendingResult</code></a> object,
which fires when the operation is completed:</p>
<pre>
@ -49,12 +49,14 @@ pendingResult.setResultCallback(new ResultCallback&lt;DataItemResult&gt;() {
});
</pre>
<h3 id="sync-waiting">Synchronously waiting</h3>
<h3 id="sync-waiting">Synchronous calls</h3>
<p>If your code is running on a separate handler thread in a background service (which is the case
in a <a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html"><code>WearableListenerService</code></a>),
it's fine for the calls to block. In this case, you can call
<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html#await()"><code>await()</code></a>
on the PendingResult object, which will block until the request has completed, and return a Result
on the <a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html"><code>PendingResult</code></a>
object, which blocks until the request completes and returns a
<a href="{@docRoot}reference/com/google/android/gms/common/api/Result.html"><code>Result</code></a>
object:
</p>
@ -82,14 +84,14 @@ are created, messages are received, or when the wearable and handset are connect
</li>
</ul>
<p>With both these options, you override any of the data event callbacks that you care about
handling in your implementation.</p>
<p>With both these options, you override the data event callback methods for the events you
are interested in handling.</p>
<h3 id="listener-service">With a WearableListenerService</h3>
<p>
You typically create instances of this service in both your wearable and handheld apps. If you
don't care about data events in one of these apps, then you don't need to implement this
are not interested in data events in one of these apps, then you don't need to implement this
service in that particular app.</p>
<p>For example, you can have a handheld app that sets and gets data item objects and a wearable app
@ -107,8 +109,9 @@ triggers this callback on both sides.</li>
- A message sent from one side of a connection triggers this callback on the other side of the connection.</li>
<li><a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html#onMessageReceived(com.google.android.gms.wearable.MessageEvent)"><code>onPeerConnected()</code></a>
and <a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html#onPeerDisconnected(com.google.android.gms.wearable.Node)"><code>onPeerDisconnected()</code></a> -
Called when connection with the handheld or wearable is connected or disconnected.
Changes in connection state on one side of the connection triggers these callbacks on both sides of the connection.
Called when the connection with the handheld or wearable is connected or disconnected.
Changes in connection state on one side of the connection trigger these callbacks on both sides
of the connection.
</li>
</ul>
@ -118,8 +121,8 @@ triggers this callback on both sides.</li>
<li>Create a class that extends
<a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html"><code>WearableListenerService</code></a>.
</li>
<li>Listen for the events that you care about, such as
<a href="{@docRoot}/reference/com/google/android/gms/wearable/WearableListenerService.html#onDataChanged(com.google.android.gms.wearable.DataEventBuffer)"><code>onDataChanged()</code></a>.
<li>Listen for the events that you're interested in, such as
<a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html#onDataChanged(com.google.android.gms.wearable.DataEventBuffer)"><code>onDataChanged()</code></a>.
</li>
<li>Declare an intent filter in your Android manifest to notify the system about your
<a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html"><code>WearableListenerService</code></a>.
@ -165,7 +168,7 @@ public class DataLayerListenerService extends WearableListenerService {
// Get the node id from the host value of the URI
String nodeId = uri.getHost();
// Set the data of the message to be the bytes of the URI.
// Set the data of the message to be the bytes of the URI
byte[] payload = uri.toString().getBytes();
// Send the RPC
@ -189,7 +192,8 @@ public class DataLayerListenerService extends WearableListenerService {
<h4>Permissions within Data Layer Callbacks</h4>
<p>In order to deliver callbacks to your application for data layer events, Google Play services
<p>
To deliver callbacks to your application for data layer events, Google Play services
binds to your <a href="{@docRoot}reference/com/google/android/gms/wearable/WearableListenerService.html"><code>WearableListenerService</code></a>,
and calls your callbacks via IPC. This has the consequence
that your callbacks inherit the permissions of the calling process.</p>
@ -233,7 +237,7 @@ of the following interfaces:
<li>Implement the desired interfaces.</li>
<li>In {@link android.app.Activity#onCreate}, create an instance of
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html"><code>GoogleApiClient</code></a>
to work with the data layer API.
to work with the Data Layer API.
<li>
In {@link android.app.Activity#onStart onStart()}, call <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()"><code>connect()</code></a> to connect the client to Google Play services.
</li>
@ -283,7 +287,7 @@ public class MainActivity extends Activity implements
}
}
&#64;Override
&#64;Override
public void onConnected(Bundle connectionHint) {
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "Connected to Google Api Service");
@ -306,8 +310,8 @@ public class MainActivity extends Activity implements
if (event.getType() == DataEvent.TYPE_DELETED) {
Log.d(TAG, "DataItem deleted: " + event.getDataItem().getUri());
} else if (event.getType() == DataEvent.TYPE_CHANGED) {
Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri());
Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri());
}
}
}
</pre>
</pre>

2
docs/html/training/wearables/data-layer/index.jd
View File

@ -66,7 +66,7 @@ channel.
<h2>Lessons</h2>
<dl>
<dt><a href="{@docRoot}training/wearables/data-layer/data-items.html">Accessing the Wearable Data Layer</a></dt>
<dt><a href="{@docRoot}training/wearables/data-layer/accessing.html">Accessing the Wearable Data Layer</a></dt>
<dd>This lesson shows you how to create a client to access the Data Layer APIs.</dd>
<dt><a href="{@docRoot}training/wearables/data-layer/data-items.html">Syncing Data Items</a></dt>

34
docs/html/training/wearables/data-layer/messages.jd
View File

@ -22,20 +22,16 @@ and attach the following items to the message:</p>
<li>A path that uniquely identifies the message's action</li>
</ul>
<p>
Unlike data items, there is no syncing between the handheld and wearable apps.
Unlike with data items, there is no syncing between the handheld and wearable apps.
Messages are a one-way communication mechanism that's good for remote procedure calls (RPC),
such as sending a message to the wearable
to start an activity. You can also use messages in request/response model
where one side of the connection sends a message, does some work,
and sends back a response message.</p>
such as sending a message to the wearable to start an activity.</p>
<h2 id="SendMessage">Send a Message</h2>
<p>The following example shows how to send a message that indicates to the other
side of the connect to start an activity.
This call is made synchronously, which blocks until the message
is received or when the request times out:
</p>
side of the connection to start an activity.
This call is synchronous and blocks processing until the message is received or until the request
times out:</p>
<p class="note"><b>Note:</b> Read more about asynchronous and synchronous calls
to Google Play services and when to use each in
@ -61,7 +57,7 @@ send messages to:</p>
<pre>
private Collection&lt;String&gt; getNodes() {
HashSet &lt;String&gt;results= new HashSet&lt;String&gt;();
HashSet &lt;String&gt;results = new HashSet&lt;String&gt;();
NodeApi.GetConnectedNodesResult nodes =
Wearable.NodeApi.getConnectedNodes(mGoogleApiClient).await();
for (Node node : nodes.getNodes()) {
@ -71,14 +67,17 @@ private Collection&lt;String&gt; getNodes() {
}
</pre>
<h2 id="ReceiveMessage">Receiving a Message</h2>
<h2 id="ReceiveMessage">Receive a Message</h2>
<p>
To be notified of received messages, you implement a listener for message events.
This example shows how you might do this by checking the <code>START_ACTIVITY_PATH</code>
that the previous example used to send the message. If this condition is <code>true</code>,
a specific activity is started.
To be notified of received messages, you implement the
<a href="{@docRoot}reference/com/google/android/gms/wearable/MessageApi.MessageListener.html">
<code>MessageListener</code></a> interface to provide a listener for message events. Then you register your
listener with the
<a href="{@docRoot}reference/com/google/android/gms/wearable/MessageApi.html#addListener(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.wearable.MessageApi.MessageListener)">
<code>MessageApi.addListener()</code></a> method. This example shows how you might implement the listener
to check the <code>START_ACTIVITY_PATH</code> that the previous example used to send the message.
If this condition is <code>true</code>, a specific activity is started.
</p>
<pre>
@ -95,5 +94,6 @@ public void onMessageReceived(MessageEvent messageEvent) {
<p>
This is just a snippet that requires more implementation details. Learn about
how to implement a full listener service or activity in
<a href="{@docRoot}training/wearables/data-layer/events.html#Listen">Listening for Data Layer Events</a>.
<a href="{@docRoot}training/wearables/data-layer/events.html#Listen">Listening for Data Layer
Events</a>.
</p>