Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0090727d authored by Kevin Hufnagle's avatar Kevin Hufnagle
Browse files

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
parent de40f9d6

docs/html/guide/topics/location/strategies.jd

+52 −21
Original line number Diff line number Diff line
@@ -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>

docs/html/guide/topics/manifest/uses-feature-element.jd

+28 −4
Original line number Diff line number Diff line
@@ -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>

docs/html/guide/topics/media/camera.jd

+8 −2
Original line number Diff line number Diff line
@@ -154,10 +154,16 @@ application must request the audio capture permission. 
&lt;uses-permission android:name="android.permission.RECORD_AUDIO" /&gt;

</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>

docs/html/training/tv/start/hardware.jd

+17 −4
Original line number Diff line number Diff line
@@ -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>