docs: Added note about permission/feature changes with network/GPS.

As of API level 21, the ACCESS_COARSE_LOCATION permission no longer
implies the android.hardware.location.network feature, and the
ACCESS_FINE_LOCATION permission no longer implies the
android.hardware.location.gps feature. Updated several docs
accordingly.

Bug: 28052540
Change-Id: Ia86dfd390f85c7a99b50af862d5096f0ac64a133

diff --git a/docs/html/guide/topics/location/strategies.jd b/docs/html/guide/topics/location/strategies.jd
index 2dfed2c..eb436d0 100755 (executable)
--- a/docs/html/guide/topics/location/strategies.jd
+++ b/docs/html/guide/topics/location/strategies.jd
@@ -133,36 +133,66 @@ notifications and the third is the minimum change in distance between notificati
 both to zero requests location notifications as frequently as possible. The last parameter is your
 {@link android.location.LocationListener}, which receives callbacks for location updates.</p>
 
-<p>To request location updates from the GPS provider,
-substitute <code>GPS_PROVIDER</code> for <code>NETWORK_PROVIDER</code>. You can also request
-location updates from both the GPS and the Network Location Provider by calling {@link
-android.location.LocationManager#requestLocationUpdates requestLocationUpdates()} twice&mdash;once
-for <code>NETWORK_PROVIDER</code> and once for <code>GPS_PROVIDER</code>.</p>
+<p>To request location updates from the GPS provider, use {@link
+android.location.LocationManager#GPS_PROVIDER} instead of {@link
+android.location.LocationManager#NETWORK_PROVIDER}. You can also request
+location updates from both the GPS and the Network Location Provider by calling
+{@link android.location.LocationManager#requestLocationUpdates
+requestLocationUpdates()} twice&mdash;once for {@link
+android.location.LocationManager#NETWORK_PROVIDER} and once for {@link
+android.location.LocationManager#GPS_PROVIDER}.</p>
 
 
 <h3 id="Permission">Requesting User Permissions</h3>
 
-<p>In order to receive location updates from <code>NETWORK_PROVIDER</code> or
-<code>GPS_PROVIDER</code>, you must request user permission by declaring either the {@code
-ACCESS_COARSE_LOCATION} or {@code ACCESS_FINE_LOCATION} permission, respectively, in your Android
-manifest file. For example:</p>
+<p>
+  In order to receive location updates from {@link
+  android.location.LocationManager#NETWORK_PROVIDER} or {@link
+  android.location.LocationManager#GPS_PROVIDER}, you must request the user's
+  permission by declaring either the {@code ACCESS_COARSE_LOCATION} or {@code
+  ACCESS_FINE_LOCATION} permission, respectively, in your Android manifest file.
+  Without these permissions, your application will fail at runtime when
+  requesting location updates.
+</p>
+
+<p>
+  If you are using both {@link
+  android.location.LocationManager#NETWORK_PROVIDER} and {@link
+  android.location.LocationManager#GPS_PROVIDER}, then you need to request only
+  the {@code ACCESS_FINE_LOCATION} permission, because it includes permission
+  for both providers. (Permission for {@code ACCESS_COARSE_LOCATION} includes
+  permission only for {@link
+  android.location.LocationManager#NETWORK_PROVIDER}.)
+</p>
+
+<p class="note">
+  <strong>Note:</strong> If your app targets Android 5.0 (API level 21) or
+  higher, you must also declare that your app uses the
+  <code>android.hardware.location.network</code> or
+  <code>android.hardware.location.gps</code> hardware feature in the manifest
+  file, depending on whether your app receives location updates from {@link
+  android.location.LocationManager#NETWORK_PROVIDER} or from {@link
+  android.location.LocationManager#GPS_PROVIDER}. If your app receives location
+  information from both of these providers, you need to declare that the app
+  uses both <code>android.hardware.location.network</code> and
+  <code>android.hardware.location.gps</code>.
+</p>
 
+<p>
+   The following code sample demonstrates how to declare the permission and
+   hardware feature in the manifest file of an app that reads data from the
+   device's GPS:
+</p>
 <pre>
 &lt;manifest ... &gt;
     &lt;uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /&gt;
     ...
+    &lt;!-- Needed only if your app targets Android 5.0 (API level 21) or higher. --&gt;
+    &lt;uses-feature android:name="android.hardware.location.gps" /&gt;
+    ...
 &lt;/manifest&gt;
 </pre>
 
-<p>Without these permissions, your application will fail at runtime when requesting
-location updates.</p>
-
-<p class="note"><strong>Note:</strong> If you are using both <code>NETWORK_PROVIDER</code> and
-<code>GPS_PROVIDER</code>, then you need to request only the {@code ACCESS_FINE_LOCATION}
-permission, because it includes permission for both providers. (Permission for {@code
-ACCESS_COARSE_LOCATION} includes permission only for <code>NETWORK_PROVIDER</code>.)</p>
-
-
 <h2 id="BestPerformance">Defining a Model for the Best Performance</h2>
 
   <p>Location-based applications are now commonplace, but due to the less than optimal
@@ -404,9 +434,10 @@ don't have a device, you can still test your location-based features by mocking
 the Android emulator. There are three different ways to send your application mock location
 data: using Android Studio, DDMS, or the "geo" command in the emulator console.</p>
 
-<p class="note"><strong>Note:</strong> Providing mock location data is injected as GPS location
-data, so you must request location updates from <code>GPS_PROVIDER</code> in order for mock location
-data to work.</p>
+<p class="note"><strong>Note:</strong> Providing mock location data is injected
+as GPS location data, so you must request location updates from {@link
+android.location.LocationManager#GPS_PROVIDER} in order for mock location data
+to work.</p>
 
 <h3 id="MockAVD">Using Android Studio</h3>
 

diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd
index 10841d6..8478940 100755 (executable)
--- a/docs/html/guide/topics/manifest/uses-feature-element.jd
+++ b/docs/html/guide/topics/manifest/uses-feature-element.jd
@@ -1685,6 +1685,15 @@ densities: '160'
 
 <pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
 
+<p class="note">
+  <strong>Note:</strong> If your app targets Android 5.0 (API level 21) or
+  higher and uses the <code>ACCESS_COARSE_LOCATION</code> or
+  <code>ACCESS_FINE_LOCATION</code> permission in order to receive location
+  updates from the network or a GPS, respectively, you must also explicitly
+  declare that your app uses the <code>android.hardware.location.network</code>
+  or <code>android.hardware.location.gps</code> hardware feature, respectively.
+</p>
+
 <p class="table-caption" id="permissions-features">
   <strong>Table 2. </strong>Device permissions that imply device hardware use.
 </p>
@@ -1736,14 +1745,29 @@ densities: '160'
 </tr>
 <tr>
   <td><code>ACCESS_COARSE_LOCATION</code></td>
-  <td><code>android.hardware.location.network</code> <em>and</em>
-<br><code>android.hardware.location</code></td>
+  <td>
+    <p>
+      <code>android.hardware.location</code>
+    </p>
+    <p>
+      <code>android.hardware.location.network</code> (Target API level 20 or
+      lower only.)
+    </p>
+  </td>
 <!--  <td></td> -->
 </tr>
 <tr>
   <td><code>ACCESS_FINE_LOCATION</code></td>
-  <td><code>android.hardware.location.gps</code> <em>and</em>
-<br><code>android.hardware.location</code></td>
+  <td>
+    <p>
+      <code>android.hardware.location</code>
+    </p>
+    <p>
+      <code>android.hardware.location.gps</code> (Target API level 20 or lower
+      only.)
+    </p>
+  </td>
+
 <!--  <td></td> -->
 </tr>
 

diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd
index 4995a13..fcf1ab1 100644 (file)
--- a/docs/html/guide/topics/media/camera.jd
+++ b/docs/html/guide/topics/media/camera.jd
@@ -154,10 +154,16 @@ application must request the audio capture permission.
 <uses-permission android:name="android.permission.RECORD_AUDIO" />
 </pre>
   </li>
-  <li><strong>Location Permission</strong> - If your application tags images with GPS location
-information, you must request location permission:
+  <li>
+    <p><strong>Location Permission</strong> - If your application tags images
+    with GPS location information, you must request the "fine location"
+    permission. Note that, if your app targets Android 5.0 (API level 21) or
+    higher, you also need to declare that your app uses the device's GPS:</p>
 <pre>
 &lt;uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /&gt;
+...
+&lt;!-- Needed only if your app targets Android 5.0 (API level 21) or higher. --&gt;
+&lt;uses-feature android:name="android.hardware.location.gps" /&gt;
 </pre>
 <p>For more information about getting user location, see
 <a href="{@docRoot}guide/topics/location/strategies.html">Location Strategies</a>.</p>

diff --git a/docs/html/training/tv/start/hardware.jd b/docs/html/training/tv/start/hardware.jd
index 97cf7ff..0639871 100644 (file)
--- a/docs/html/training/tv/start/hardware.jd
+++ b/docs/html/training/tv/start/hardware.jd
@@ -227,13 +227,19 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
   </tr>
   <tr>
     <td>{@link android.Manifest.permission#ACCESS_COARSE_LOCATION}</td>
-    <td>{@code android.hardware.location} <em>and</em> <br>
-      {@code android.hardware.location.network}</td>
+    <td>
+      <p>{@code android.hardware.location}</p>
+      <p>{@code android.hardware.location.network} (Target API level 20 or lower
+      only.)</p>
+    </td>
   </tr>
   <tr>
     <td>{@link android.Manifest.permission#ACCESS_FINE_LOCATION}</td>
-    <td>{@code android.hardware.location} <em>and</em> <br>
-      {@code android.hardware.location.gps}</td>
+    <td>
+      <p>{@code android.hardware.location}</p>
+      <p>{@code android.hardware.location.gps} (Target API level 20 or lower
+      only.)</p>
+    </td>
   </tr>
 </table>
 
@@ -246,6 +252,13 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
   required ({@code android:required="false"}).
 </p>
 
+<p class="note">
+  <strong>Note:</strong> If your app targets Android 5.0 (API level 21) or
+  higher and uses the <code>ACCESS_COARSE_LOCATION</code> or
+  <code>ACCESS_FINE_LOCATION</code> permission, users can still install your
+  app on a TV device, even if the TV device doesn't have a network card or a GPS
+  receiver.
+</p>
 
 <h3 id="check-features">Checking for hardware features</h2>