Merge "Make FUSED_PROVIDER public API"

1 files changed, 49 insertions, 29 deletions

diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java
index 7085a755990f..914beaff225e 100644
--- a/location/java/android/location/LocationManager.java
+++ b/location/java/android/location/LocationManager.java
@@ -159,21 +159,21 @@ public class LocationManager {
     public static final long BLOCK_GPS_STATUS_USAGE = 144027538L;
 
     /**
-     * Name of the network location provider.
+     * Standard name of the network location provider.
      *
-     * <p>This provider determines location based on nearby of cell tower and WiFi access points.
-     * Results are retrieved by means of a network lookup.
+     * <p>If present, this provider determines location based on nearby of cell tower and WiFi
+     * access points. Operation of this provider may require a data connection.
      */
     public static final String NETWORK_PROVIDER = "network";
 
     /**
-     * Name of the GNSS location provider.
+     * Standard name of the GNSS location provider.
      *
-     * <p>This provider determines location using GNSS satellites. Depending on conditions, this
-     * provider may take a while to return a location fix. Requires the
-     * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission.
+     * <p>If present, this provider determines location using GNSS satellites. The responsiveness
+     * and accuracy of location fixes may depend on GNSS signal conditions.
      *
-     * <p>The extras Bundle for the GPS location provider can contain the following key/value pairs:
+     * <p>The extras Bundle for locations derived by this location provider may contain the
+     * following key/value pairs:
      * <ul>
      * <li> satellites - the number of satellites used to derive the fix
      * </ul>
@@ -181,29 +181,22 @@ public class LocationManager {
     public static final String GPS_PROVIDER = "gps";
 
     /**
-     * A special location provider for receiving locations without actually initiating a location
-     * fix.
+     * A special location provider for receiving locations without actively initiating a location
+     * fix. This location provider is always present.
      *
      * <p>This provider can be used to passively receive location updates when other applications or
      * services request them without actually requesting the locations yourself. This provider will
-     * only return locations generated by other providers.  You can query the
-     * {@link Location#getProvider()} method to determine the actual provider that supplied the
-     * location update. Requires the {@link android.Manifest.permission#ACCESS_FINE_LOCATION}
-     * permission, although there is no guarantee of fine locations.
+     * only return locations generated by other providers.
      */
     public static final String PASSIVE_PROVIDER = "passive";
 
     /**
-     * The fused location provider.
-     *
-     * <p>This provider may combine inputs from several location sources to provide the
-     * best possible location fix. It is implicitly used for all API's that involve the
-     * {@link LocationRequest} object.
+     * Standard name of the fused location provider.
      *
-     * @hide
+     * <p>If present, this provider may combine inputs from several other location providers to
+     * provide the best possible location fix. It is implicitly used for all requestLocationUpdates
+     * APIs that involve a {@link Criteria}.
      */
-    @SystemApi
-    @TestApi
     public static final String FUSED_PROVIDER = "fused";
 
     /**
@@ -918,6 +911,9 @@ public class LocationManager {
     /**
      * Register for a single location update using a Criteria and a callback.
      *
+     * <p>Note: Since Android KitKat, Criteria requests will always result in using the
+     * {@link #FUSED_PROVIDER}.
+     *
      * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)} for more detail
      * on how to use this method.
      *
@@ -985,6 +981,9 @@ public class LocationManager {
     /**
      * Register for a single location update using a Criteria and pending intent.
      *
+     * <p>Note: Since Android KitKat, Criteria requests will always result in using the
+     * {@link #FUSED_PROVIDER}.
+     *
      * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)} for more detail
      * on how to use this method.
      *
@@ -1113,6 +1112,9 @@ public class LocationManager {
      * Register for location updates using a provider selected through the given Criteria, and a
      * callback on the specified {@link Looper}.
      *
+     * <p>Note: Since Android KitKat, Criteria requests will always result in using the
+     * {@link #FUSED_PROVIDER}.
+     *
      * <p>See {@link #requestLocationUpdates(String, LocationRequest, Executor, LocationListener)}
      * for more detail on how this method works.
      *
@@ -1124,7 +1126,12 @@ public class LocationManager {
      * @throws IllegalArgumentException if criteria is null
      * @throws IllegalArgumentException if listener is null
      * @throws SecurityException if no suitable permission is present
+     *
+     * @deprecated Use
+     * {@link #requestLocationUpdates(String, long, float, LocationListener, Looper)} instead to
+     * explicitly select a provider.
      */
+    @Deprecated
     @RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION})
     public void requestLocationUpdates(long minTimeMs, float minDistanceM,
             @NonNull Criteria criteria, @NonNull LocationListener listener,
@@ -1138,6 +1145,9 @@ public class LocationManager {
      * Register for location updates using a provider selected through the given Criteria, and a
      * callback on the specified {@link Executor}.
      *
+     * <p>Note: Since Android KitKat, Criteria requests will always result in using the
+     * {@link #FUSED_PROVIDER}.
+     *
      * <p>See {@link #requestLocationUpdates(String, LocationRequest, Executor, LocationListener)}
      * for more detail on how this method works.
      *
@@ -1151,7 +1161,12 @@ public class LocationManager {
      * @throws IllegalArgumentException if executor is null
      * @throws IllegalArgumentException if listener is null
      * @throws SecurityException        if no suitable permission is present
+     *
+     * @deprecated Use
+     * {@link #requestLocationUpdates(String, long, float, Executor, LocationListener)} instead to
+     * explicitly select a provider.
      */
+    @Deprecated
     @RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION})
     public void requestLocationUpdates(
             long minTimeMs,
@@ -1199,6 +1214,9 @@ public class LocationManager {
      * Register for location updates using a provider selected through the given Criteria, and
      * callbacks delivered via the provided {@link PendingIntent}.
      *
+     * <p>Note: Since Android KitKat, Criteria requests will always result in using the
+     * {@link #FUSED_PROVIDER}.
+     *
      * <p>See {@link #requestLocationUpdates(String, long, float, PendingIntent)} for more detail on
      * how this method works.
      *
@@ -1210,7 +1228,11 @@ public class LocationManager {
      * @throws IllegalArgumentException if provider is null or doesn't exist
      * @throws IllegalArgumentException if pendingIntent is null
      * @throws SecurityException if no suitable permission is present
+     *
+     * @deprecated Use {@link #requestLocationUpdates(String, long, float, PendingIntent)} instead
+     * to explicitly select a provider.
      */
+    @Deprecated
     @RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION})
     public void requestLocationUpdates(long minTimeMs, float minDistanceM,
             @NonNull Criteria criteria, @NonNull PendingIntent pendingIntent) {
@@ -1594,9 +1616,8 @@ public class LocationManager {
     }
 
     /**
-     * Returns a list of the names of all known location providers. All providers are returned,
-     * including ones that are not permitted to be accessed by the calling activity or are currently
-     * disabled.
+     * Returns a list of the names of all available location providers. All providers are returned,
+     * including those that are currently disabled.
      *
      * @return list of provider names
      */
@@ -1609,8 +1630,8 @@ public class LocationManager {
     }
 
     /**
-     * Returns a list of the names of location providers. Only providers that the caller has
-     * permission to access will be returned.
+     * Returns a list of the names of available location providers. If {@code enabledOnly} is false,
+     * this is functionally the same as {@link #getAllProviders()}.
      *
      * @param enabledOnly if true then only enabled providers are included
      * @return list of provider names
@@ -1624,8 +1645,7 @@ public class LocationManager {
     }
 
     /**
-     * Returns a list of the names of providers that satisfy the given criteria. Only providers that
-     * the caller has permission to access will be returned.
+     * Returns a list of the names of available location providers that satisfy the given criteria.
      *
      * @param criteria the criteria that providers must match
      * @param enabledOnly if true then only enabled providers are included