summaryrefslogtreecommitdiffstats
path: root/location/java
diff options
context:
space:
mode:
Diffstat (limited to 'location/java')
-rw-r--r--location/java/android/location/Criteria.java4
-rw-r--r--location/java/android/location/Geofence.java10
-rw-r--r--location/java/android/location/Location.java225
-rw-r--r--location/java/android/location/LocationManager.java798
-rw-r--r--location/java/android/location/LocationRequest.java300
5 files changed, 828 insertions, 509 deletions
diff --git a/location/java/android/location/Criteria.java b/location/java/android/location/Criteria.java
index 6258a43..68fb4a0 100644
--- a/location/java/android/location/Criteria.java
+++ b/location/java/android/location/Criteria.java
@@ -24,7 +24,9 @@ import android.os.Parcelable;
* location provider. Providers maybe ordered according to accuracy,
* power usage, ability to report altitude, speed,
* and bearing, and monetary cost.
- * @deprecated {@link LocationRequest} instead
+ *
+ * @deprecated use {@link LocationRequest} instead, and also see notes
+ * at {@link LocationManager}
*/
@Deprecated
public class Criteria implements Parcelable {
diff --git a/location/java/android/location/Geofence.java b/location/java/android/location/Geofence.java
index 353a1ca..03cca84 100644
--- a/location/java/android/location/Geofence.java
+++ b/location/java/android/location/Geofence.java
@@ -20,7 +20,11 @@ import android.os.Parcel;
import android.os.Parcelable;
/**
- * Represents a Geofence
+ * Represents a geographical boundary, also known as a geofence.
+ *
+ * <p>Currently only circular geofences are supported, but this object
+ * is opaque so could be used in the future to represent polygons or other
+ * shapes.
*/
public final class Geofence implements Parcelable {
/** @hide */
@@ -33,6 +37,7 @@ public final class Geofence implements Parcelable {
/**
* Create a horizontal, circular geofence.
+ *
* @param latitude latitude in degrees
* @param longitude longitude in degrees
* @param radius radius in meters
@@ -152,6 +157,9 @@ public final class Geofence implements Parcelable {
return result;
}
+ /**
+ * Two geofences are equal if they have identical properties.
+ */
@Override
public boolean equals(Object obj) {
if (this == obj)
diff --git a/location/java/android/location/Location.java b/location/java/android/location/Location.java
index ece4500..f50ee82 100644
--- a/location/java/android/location/Location.java
+++ b/location/java/android/location/Location.java
@@ -27,15 +27,15 @@ import java.text.DecimalFormat;
import java.util.StringTokenizer;
/**
- * A class representing a geographic location sensed at a particular
- * time (a "fix"). A location consists of a latitude and longitude, a
- * UTC timestamp. and optionally information on altitude, speed, and
- * bearing.
+ * A data class representing a geographic location.
*
- * <p> Information specific to a particular provider or class of
- * providers may be communicated to the application using getExtras,
- * which returns a Bundle of key/value pairs. Each provider will only
- * provide those entries for which information is available.
+ * <p>A location can consist of a latitude, longitude, timestamp,
+ * and other information such as bearing, altitude and velocity.
+ *
+ * <p>All locations generated by the {@link LocationManager} are
+ * guaranteed to have a valid latitude, longitude, and timestamp
+ * (both UTC time and elapsed real-time since boot), all other
+ * parameters are optional.
*/
public class Location implements Parcelable {
/**
@@ -86,20 +86,19 @@ public class Location implements Parcelable {
private float[] mResults = new float[2];
/**
- * Constructs a new Location. By default, time, latitude,
- * longitude, and numSatellites are 0; hasAltitude, hasSpeed, and
- * hasBearing are false; and there is no extra information.
+ * Construct a new Location with a named provider.
+ *
+ * <p>By default time, latitude and longitude are 0, and the location
+ * has no bearing, altitude, speed, accuracy or extras.
*
- * @param provider the name of the location provider that generated this
- * location fix.
+ * @param provider the name of the provider that generated this location
*/
public Location(String provider) {
mProvider = provider;
}
/**
- * Constructs a new Location object that is a copy of the given
- * location.
+ * Construct a new Location object that is copied from an existing one.
*/
public Location(Location l) {
set(l);
@@ -447,9 +446,19 @@ public class Location implements Parcelable {
}
/**
- * Returns the name of the provider that generated this fix,
- * or null if it is not associated with a provider.
+ * Returns the name of the provider that generated this fix.
+ *
+ * <p class="note">At API version 17 we deprecated {@link LocationProvider}
+ * and all API methods that request a provider by name. The new API methods
+ * will produce locations that could come from different sources, and even
+ * locations that are fused from several sources. So you should generally
+ * not care what provider is associated with a location object.
+ *
+ * @return the provider, or null if it has not been set
+ *
+ * @deprecated locations can now be sourced from many providers, or even fused
*/
+ @Deprecated
public String getProvider() {
return mProvider;
}
@@ -462,16 +471,19 @@ public class Location implements Parcelable {
}
/**
- * Return the UTC time of this fix, in milliseconds since January 1,
- * 1970.
+ * Return the UTC time of this fix, in milliseconds since January 1, 1970.
+ *
* <p>Note that the UTC time on a device is not monotonic: it
* can jump forwards or backwards unpredictably. So always use
- * {@link #getElapsedRealtimeNano()} when calculating time deltas.
- * <p>On the other hand, {@link #getTime()} is useful for presenting
+ * {@link #getElapsedRealtimeNano} when calculating time deltas.
+ *
+ * <p>On the other hand, {@link #getTime} is useful for presenting
* a human readable time to the user, or for carefully comparing
* location fixes across reboot or across devices.
- * <p>This method will always return a valid timestamp on
- * Locations generated by a {@link LocationProvider}.
+ *
+ * <p>All locations generated by the {@link LocationManager}
+ * are guaranteed to have a valid UTC time, however remember that
+ * the system time may have changed since the location was generated.
*
* @return time of fix, in milliseconds since January 1, 1970.
*/
@@ -491,13 +503,16 @@ public class Location implements Parcelable {
/**
* Return the time of this fix, in elapsed real-time since system boot.
+ *
* <p>This value can be reliably compared to
- * {@link android.os.SystemClock#elapsedRealtimeNano()},
- * to calculate the age of a fix, and to compare Location fixes, since
- * elapsed real-time is guaranteed monotonic for each system boot, and
- * continues to increment even when the system is in deep sleep.
- * <p>This method will always return a valid timestamp on
- * Locations generated by a {@link LocationProvider}.
+ * {@link android.os.SystemClock#elapsedRealtimeNano},
+ * to calculate the age of a fix and to compare Location fixes. This
+ * is reliable because elapsed real-time is guaranteed monotonic for
+ * each system boot and continues to increment even when the system
+ * is in deep sleep (unlike {@link #getTime}.
+ *
+ * <p>All locations generated by the {@link LocationManager}
+ * are guaranteed to have a valid elapsed real-time.
*
* @return elapsed real-time of fix, in nanoseconds since system boot.
*/
@@ -515,56 +530,59 @@ public class Location implements Parcelable {
}
/**
- * Return the latitude of this fix.
- * <p>This method will always return a valid latitude on
- * Locations generated by a {@link LocationProvider}.
+ * Get the latitude, in degrees.
+ *
+ * <p>All locations generated by the {@link LocationManager}
+ * will have a valid latitude.
*/
public double getLatitude() {
return mLatitude;
}
/**
- * Sets the latitude of this fix.
+ * Set the latitude, in degrees.
*/
public void setLatitude(double latitude) {
mLatitude = latitude;
}
/**
- * Return the longitude of this fix.
- * <p>This method will always return a valid longitude on
- * Locations generated by a {@link LocationProvider}.
+ * Get the longitude, in degrees.
+ *
+ * <p>All locations generated by the {@link LocationManager}
+ * will have a valid longitude.
*/
public double getLongitude() {
return mLongitude;
}
/**
- * Sets the longitude of this fix.
+ * Set the longitude, in degrees.
*/
public void setLongitude(double longitude) {
mLongitude = longitude;
}
/**
- * Returns true if this fix contains altitude information, false
- * otherwise.
+ * True if this location has an altitude.
*/
public boolean hasAltitude() {
return mHasAltitude;
}
/**
- * Returns the altitude of this fix. If {@link #hasAltitude} is false,
- * 0.0f is returned.
+ * Get the altitude if available, in meters above sea level.
+ *
+ * <p>If this location does not have an altitude then 0.0 is returned.
*/
public double getAltitude() {
return mAltitude;
}
/**
- * Sets the altitude of this fix. Following this call,
- * hasAltitude() will return true.
+ * Set the altitude, in meters above sea level.
+ *
+ * <p>Following this call {@link #hasAltitude} will return true.
*/
public void setAltitude(double altitude) {
mAltitude = altitude;
@@ -572,8 +590,10 @@ public class Location implements Parcelable {
}
/**
- * Clears the altitude of this fix. Following this call,
- * hasAltitude() will return false.
+ * Remove the altitude from this location.
+ *
+ * <p>Following this call {@link #hasAltitude} will return false,
+ * and {@link #getAltitude} will return 0.0.
*/
public void removeAltitude() {
mAltitude = 0.0f;
@@ -581,24 +601,25 @@ public class Location implements Parcelable {
}
/**
- * Returns true if this fix contains speed information, false
- * otherwise. The default implementation returns false.
+ * True if this location has a speed.
*/
public boolean hasSpeed() {
return mHasSpeed;
}
/**
- * Returns the speed of the device over ground in meters/second.
- * If hasSpeed() is false, 0.0f is returned.
+ * Get the speed if it is available, in meters/second over ground.
+ *
+ * <p>If this location does not have a speed then 0.0 is returned.
*/
public float getSpeed() {
return mSpeed;
}
/**
- * Sets the speed of this fix, in meters/second. Following this
- * call, hasSpeed() will return true.
+ * Set the speed, in meters/second over ground.
+ *
+ * <p>Following this call {@link #hasSpeed} will return true.
*/
public void setSpeed(float speed) {
mSpeed = speed;
@@ -606,8 +627,10 @@ public class Location implements Parcelable {
}
/**
- * Clears the speed of this fix. Following this call, hasSpeed()
- * will return false.
+ * Remove the speed from this location.
+ *
+ * <p>Following this call {@link #hasSpeed} will return false,
+ * and {@link #getSpeed} will return 0.0.
*/
public void removeSpeed() {
mSpeed = 0.0f;
@@ -615,24 +638,32 @@ public class Location implements Parcelable {
}
/**
- * Returns true if the provider is able to report bearing information,
- * false otherwise. The default implementation returns false.
+ * True if this location has a bearing.
*/
public boolean hasBearing() {
return mHasBearing;
}
/**
- * Returns the direction of travel in degrees East of true
- * North. If hasBearing() is false, 0.0 is returned.
+ * Get the bearing, in degrees.
+ *
+ * <p>Bearing is the horizontal direction of travel of this device,
+ * and is not related to the device orientation. It is guaranteed to
+ * be in the range (0.0, 360.0] if the device has a bearing.
+ *
+ * <p>If this location does not have a bearing then 0.0 is returned.
*/
public float getBearing() {
return mBearing;
}
/**
- * Sets the bearing of this fix. Following this call, hasBearing()
- * will return true.
+ * Set the bearing, in degrees.
+ *
+ * <p>Bearing is the horizontal direction of travel of this device,
+ * and is not related to the device orientation.
+ *
+ * <p>The input will be wrapped into the range (0.0, 360.0].
*/
public void setBearing(float bearing) {
while (bearing < 0.0f) {
@@ -646,8 +677,10 @@ public class Location implements Parcelable {
}
/**
- * Clears the bearing of this fix. Following this call, hasBearing()
- * will return false.
+ * Remove the bearing from this location.
+ *
+ * <p>Following this call {@link #hasBearing} will return false,
+ * and {@link #getBearing} will return 0.0.
*/
public void removeBearing() {
mBearing = 0.0f;
@@ -655,35 +688,47 @@ public class Location implements Parcelable {
}
/**
- * Return true if this Location has an associated accuracy.
- * <p>All Location objects generated by a {@link LocationProvider}
- * will have an accuracy.
+ * True if this location has an accuracy.
+ *
+ * <p>All locations generated by the {@link LocationManager} have an
+ * accuracy.
*/
public boolean hasAccuracy() {
return mHasAccuracy;
}
/**
- * Return the accuracy of this Location fix.
- * <p>Accuracy is measured in meters, and indicates the
- * radius of 95% confidence.
- * In other words, there is a 95% probability that the
- * true location is within a circle centered at the reported
- * location, with radius of the reported accuracy.
- * <p>This is only a measure of horizontal accuracy, and does
- * not indicate the accuracy of bearing, velocity or altitude
- * if those are included in this Location.
- * <p>If {@link #hasAccuracy} is false, 0.0 is returned.
- * <p>All Location object generated by a {@link LocationProvider}
- * will have a valid accuracy.
+ * Get the estimated accuracy of this location, in meters.
+ *
+ * <p>We define accuracy as the radius of 68% confidence. In other
+ * words, if you draw a circle centered at this location's
+ * latitude and longitude, and with a radius equal to the accuracy,
+ * then there is a 68% probability that the true location is inside
+ * the circle.
+ *
+ * <p>In statistical terms, it is assumed that location errors
+ * are random with a normal distribution, so the 68% confidence circle
+ * represents one standard deviation. Note that in practice, location
+ * errors do not always follow such a simple distribution.
+ *
+ * <p>This accuracy estimation is only concerned with horizontal
+ * accuracy, and does not indicate the accuracy of bearing,
+ * velocity or altitude if those are included in this Location.
+ *
+ * <p>If this location does not have an accuracy, then 0.0 is returned.
+ * All locations generated by the {@link LocationManager} include
+ * an accuracy.
*/
public float getAccuracy() {
return mAccuracy;
}
/**
- * Sets the accuracy of this fix. Following this call, hasAccuracy()
- * will return true.
+ * Set the estimated accuracy of this location, meters.
+ *
+ * <p>See {@link #getAccuracy} for the definition of accuracy.
+ *
+ * <p>Following this call {@link #hasAccuracy} will return true.
*/
public void setAccuracy(float accuracy) {
mAccuracy = accuracy;
@@ -691,8 +736,10 @@ public class Location implements Parcelable {
}
/**
- * Clears the accuracy of this fix. Following this call, hasAccuracy()
- * will return false.
+ * Remove the accuracy from this location.
+ *
+ * <p>Following this call {@link #hasAccuracy} will return false, and
+ * {@link #getAccuracy} will return 0.0.
*/
public void removeAccuracy() {
mAccuracy = 0.0f;
@@ -700,8 +747,14 @@ public class Location implements Parcelable {
}
/**
- * Return true if this Location object has enough data set to
- * be considered a valid fix from a {@link LocationProvider}.
+ * Return true if this Location object is complete.
+ *
+ * <p>A location object is currently considered complete if it has
+ * a valid provider, accuracy, wall-clock time and elapsed real-time.
+ *
+ * <p>All locations supplied by the {@link LocationManager} to
+ * applications must be complete.
+ *
* @see #makeComplete
* @hide
*/
@@ -714,9 +767,11 @@ public class Location implements Parcelable {
}
/**
- * Helper to fill in incomplete fields.
- * Only use this to assist in backwards compatibility
- * with Location objects received from applications.
+ * Helper to fill incomplete fields.
+ *
+ * <p>Used to assist in backwards compatibility with
+ * Location objects received from applications.
+ *
* @see #isComplete
* @hide
*/
diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java
index 5f87c84..25da208 100644
--- a/location/java/android/location/LocationManager.java
+++ b/location/java/android/location/LocationManager.java
@@ -46,12 +46,41 @@ import com.android.internal.location.ProviderProperties;
* {@link android.content.Context#getSystemService
* Context.getSystemService(Context.LOCATION_SERVICE)}.
*
- * <div class="special reference">
- * <h3>Developer Guides</h3>
- * <p>For more information about using location services, read the
- * <a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a>
- * developer guide.</p>
- * </div>
+ * <p>At API version 17 the Location API's were simplified.
+ * Previously applications would need to explicitly enumerate, select, and
+ * track Location Providers (such as GPS or Network).
+ * This has been replaced by the concept of
+ * <em>Fused Location</em>. Now applications just specify the quality of service
+ * required for location updates (using the new {@link LocationRequest} class),
+ * and the system will fuse results from individual location providers
+ * as necessary before returning the result to the application.
+ *
+ * <p>As a result of this change, the {@link LocationProvider} and
+ * {@link Criteria} classes have been deprecated, in favor of
+ * {@link LocationRequest}. Furthermore, all Location Manager
+ * methods involving Criteria or explicitly named Providers have
+ * been deprecated, in favor of new variants that use
+ * {@link LocationRequest}.
+ *
+ * <p>A single {@link LocationRequest} object can trigger the use
+ * of all providers (including GPS, Network, and the passive) provider
+ * as necessary. This should result in a lot less work for your application. You
+ * no longer need to track the status and availability of each
+ * location provider. Just set the quality of locations required
+ * in {@link LocationRequest}, and let the system manage the rest.
+ *
+ * <p class="note">Unless noted, all Location API methods require
+ * the {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} or
+ * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permissions.
+ * If your application only has the Coarse permission then it will still
+ * receive location results, but the update rate will be throttled and
+ * the exact location will be obfuscated to a coarse level of accuracy.
+ *
+ * <p> class="note">Before API level 17, the use of 'fine' location
+ * providers such as GPS required the fine permission. As of API level
+ * 17, applications with only the coarse permission may use all providers,
+ * including GPS, but the locations are obfuscated (made coarse) before
+ * being sent to the application.
*/
public class LocationManager {
private static final String TAG = "LocationManager";
@@ -65,56 +94,69 @@ public class LocationManager {
private final GpsStatus mGpsStatus = new GpsStatus();
/**
- * Name of the network location provider. This provider determines location based on
+ * Name of the network location provider.
+ * <p>This provider determines location based on
* availability of cell tower and WiFi access points. Results are retrieved
* by means of a network lookup.
*
- * Requires either of the permissions android.permission.ACCESS_COARSE_LOCATION
- * or android.permission.ACCESS_FINE_LOCATION.
- * @deprecated use the {@link Criteria} class instead
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String NETWORK_PROVIDER = "network";
/**
- * Name of the GPS location provider. This provider determines location using
+ * Name of the GPS location provider.
+ *
+ * <p>This provider determines location using
* satellites. Depending on conditions, this provider may take a while to return
* a location fix.
*
- * Requires the permission android.permission.ACCESS_FINE_LOCATION.
+ * <p>Before API version 17, this provider required the
+ * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission.
+ * From API version 17 and onwards, this provider can also be used with
+ * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}, however
+ * the locations returned will be obfuscated to a coarse level of accuracy.
*
* <p> The extras Bundle for the GPS location provider can contain the
* following key/value pairs:
- *
* <ul>
* <li> satellites - the number of satellites used to derive the fix
* </ul>
- * @deprecated use the {@link Criteria} class instead
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String GPS_PROVIDER = "gps";
/**
* A special location provider for receiving locations without actually initiating
- * a location fix. This provider can be used to passively receive location updates
+ * a location fix.
+ *
+ * <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 return locations generated by other
* providers. You can query the {@link Location#getProvider()} method to determine
* the origin of the location update.
*
- * Requires the permission android.permission.ACCESS_FINE_LOCATION, although if the GPS
- * is not enabled this provider might only return coarse fixes.
- * @deprecated use the {@link Criteria} class instead
+ * <p>Before API version 17, this provider required the
+ * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission.
+ * From API version 17 and onwards, this provider can also be used with
+ * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}, however
+ * the locations returned will be obfuscated to a coarse level of accuracy.
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String PASSIVE_PROVIDER = "passive";
/**
- * Name of the Fused location provider.<p>
- * This provider combines inputs for all possible location sources
- * to provide the best possible Location fix.<p>
+ * Name of the Fused location provider.
+ *
+ * <p>This provider combines inputs for all possible location sources
+ * to provide the best possible Location fix. It is implicitly
+ * used for all API's that involve the {@link LocationRequest}
+ * object.
*
- * Requires the permission android.permission.ACCESS_FINE_LOCATION.
* @hide
*/
public static final String FUSED_PROVIDER = "fused";
@@ -128,7 +170,8 @@ public class LocationManager {
/**
* Key used for a Bundle extra holding an Integer status value
* when a status change is broadcast using a PendingIntent.
- * @deprecated use the {@link Criteria} class instead
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String KEY_STATUS_CHANGED = "status";
@@ -136,7 +179,8 @@ public class LocationManager {
/**
* Key used for a Bundle extra holding an Boolean status value
* when a provider enabled/disabled event is broadcast using a PendingIntent.
- * @deprecated use the {@link Criteria} class instead
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String KEY_PROVIDER_ENABLED = "providerEnabled";
@@ -153,7 +197,7 @@ public class LocationManager {
* where {@code true} means enabled.
* @see #EXTRA_GPS_ENABLED
*
- * {@hide}
+ * @hide
*/
public static final String GPS_ENABLED_CHANGE_ACTION =
"android.location.GPS_ENABLED_CHANGE";
@@ -161,7 +205,8 @@ public class LocationManager {
/**
* Broadcast intent action when the configured location providers
* change.
- * @deprecated use the {@link Criteria} class instead
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public static final String PROVIDERS_CHANGED_ACTION =
@@ -173,7 +218,7 @@ public class LocationManager {
* boolean, where {@code true} means that the GPS is actively receiving fixes.
* @see #EXTRA_GPS_ENABLED
*
- * {@hide}
+ * @hide
*/
public static final String GPS_FIX_CHANGE_ACTION =
"android.location.GPS_FIX_CHANGE";
@@ -183,7 +228,7 @@ public class LocationManager {
* disabled. {@code true} means GPS is enabled. Retrieve it with
* {@link android.content.Intent#getBooleanExtra(String,boolean)}.
*
- * {@hide}
+ * @hide
*/
public static final String EXTRA_GPS_ENABLED = "enabled";
@@ -285,6 +330,7 @@ public class LocationManager {
}
}
}
+
/**
* @hide - hide this constructor because it has a parameter
* of type ILocationManager, which is a system private class. The
@@ -301,12 +347,13 @@ 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 known location providers.
+ * <p>All providers are returned, including ones that are not permitted to
+ * be accessed by the calling activity or are currently disabled.
*
- * @return list of Strings containing names of the providers
- * @deprecated use the {@link Criteria} class instead
+ * @return list of Strings containing names of the provider
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public List<String> getAllProviders() {
@@ -319,15 +366,13 @@ public class LocationManager {
}
/**
- * Returns a list of the names of location providers. Only providers that
- * are permitted to be accessed by the calling activity will be returned.
+ * Returns a list of the names of location providers.
*
* @param enabledOnly if true then only the providers which are currently
* enabled are returned.
* @return list of Strings containing names of the providers
- * @deprecated The {@link LocationProvider} class is deprecated. So
- * use the {@link Criteria} class to request location instead of
- * enumerating providers.
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public List<String> getProviders(boolean enabledOnly) {
@@ -346,12 +391,11 @@ public class LocationManager {
* @param name the provider name
* @return a LocationProvider, or null
*
- * @throws IllegalArgumentException if name is null or does not exisit
+ * @throws IllegalArgumentException if name is null or does not exist
* @throws SecurityException if the caller is not permitted to access the
* given provider.
- * @deprecated The {@link LocationProvider} class is deprecated. So
- * use the {@link Criteria} class to request location instead of
- * enumerating providers.
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public LocationProvider getProvider(String name) {
@@ -377,9 +421,8 @@ public class LocationManager {
* @param enabledOnly if true then only the providers which are currently
* enabled are returned.
* @return list of Strings containing names of the providers
- * @deprecated The {@link LocationProvider} class is deprecated. So
- * use the {@link Criteria} class to request location instead of
- * enumerating providers.
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public List<String> getProviders(Criteria criteria, boolean enabledOnly) {
@@ -413,7 +456,8 @@ public class LocationManager {
* @param criteria the criteria that need to be matched
* @param enabledOnly if true then only a provider that is currently enabled is returned
* @return name of the provider that best matches the requirements
- * @deprecated using an explicit provider doesn't allow fused location
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public String getBestProvider(Criteria criteria, boolean enabledOnly) {
@@ -427,64 +471,11 @@ public class LocationManager {
}
/**
- * Registers the current activity to be notified periodically by
- * the named provider. Periodically, the supplied LocationListener will
- * be called with the current Location or with status updates.
- *
- * <p> It may take a while to receive the first location update. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
+ * Register for location updates using the named provider, and a
+ * pending intent.
*
- * <p> In case the provider is disabled by the user, updates will stop,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
- *
- * <p> The update interval can be controlled using the minTime parameter.
- * The elapsed time between location updates will never be less than
- * minTime, although it can be more depending on the Location Provider
- * implementation and the update interval requested by other applications.
- *
- * <p> Choosing a sensible value for minTime is important to conserve
- * battery life. Each location update requires power from
- * GPS, WIFI, Cell and other radios. Select a minTime value as high as
- * possible while still providing a reasonable user experience.
- * If your application is not in the foreground and showing
- * location to the user then your application should avoid using an active
- * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}),
- * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes)
- * or greater. If your application is in the foreground and showing
- * location to the user then it is appropriate to select a faster
- * update interval.
- *
- * <p> The minDistance parameter can also be used to control the
- * frequency of location updates. If it is greater than 0 then the
- * location provider will only send your application an update when
- * the location has changed by at least minDistance meters, AND
- * at least minTime milliseconds have passed. However it is more
- * difficult for location providers to save power using the minDistance
- * parameter, so minTime should be the primary tool to conserving battery
- * life.
- *
- * <p> If your application wants to passively observe location
- * updates triggered by other applications, but not consume
- * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER}
- * This provider does not actively turn on or modify active location
- * providers, so you do not need to be as careful about minTime and
- * minDistance. However if your application performs heavy work
- * on a location update (such as network activity) then you should
- * select non-zero values for minTime and/or minDistance to rate-limit
- * your update frequency in the case another application enables a
- * location provider with extremely fast updates.
- *
- * <p> The calling thread must be a {@link android.os.Looper} thread such as
- * the main thread of the calling Activity.
- *
- * <p class="note"> Prior to Jellybean, the minTime parameter was
- * only a hint, and some location provider implementations ignored it.
- * From Jellybean and onwards it is mandatory for Android compatible
- * devices to observe both the minTime and minDistance parameters.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param provider the name of the provider with which to register
* @param minTime minimum time interval between location updates, in milliseconds
@@ -497,8 +488,8 @@ public class LocationManager {
* on this device
* @throws IllegalArgumentException if listener is null
* @throws RuntimeException if the calling thread has no Looper
- * @throws SecurityException if no suitable permission is present for the provider.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public void requestLocationUpdates(String provider, long minTime, float minDistance,
@@ -512,63 +503,11 @@ public class LocationManager {
}
/**
- * Registers the current activity to be notified periodically by
- * the named provider. Periodically, the supplied LocationListener will
- * be called with the current Location or with status updates.
- *
- * <p> It may take a while to receive the first location update. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> In case the provider is disabled by the user, updates will stop,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
- *
- * <p> The update interval can be controlled using the minTime parameter.
- * The elapsed time between location updates will never be less than
- * minTime, although it can be more depending on the Location Provider
- * implementation and the update interval requested by other applications.
- *
- * <p> Choosing a sensible value for minTime is important to conserve
- * battery life. Each location update requires power from
- * GPS, WIFI, Cell and other radios. Select a minTime value as high as
- * possible while still providing a reasonable user experience.
- * If your application is not in the foreground and showing
- * location to the user then your application should avoid using an active
- * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}),
- * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes)
- * or greater. If your application is in the foreground and showing
- * location to the user then it is appropriate to select a faster
- * update interval.
+ * Register for location updates using the named provider, and a callback on
+ * the specified looper thread.
*
- * <p> The minDistance parameter can also be used to control the
- * frequency of location updates. If it is greater than 0 then the
- * location provider will only send your application an update when
- * the location has changed by at least minDistance meters, AND
- * at least minTime milliseconds have passed. However it is more
- * difficult for location providers to save power using the minDistance
- * parameter, so minTime should be the primary tool to conserving battery
- * life.
- *
- * <p> If your application wants to passively observe location
- * updates triggered by other applications, but not consume
- * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER}
- * This provider does not actively turn on or modify active location
- * providers, so you do not need to be as careful about minTime and
- * minDistance. However if your application performs heavy work
- * on a location update (such as network activity) then you should
- * select non-zero values for minTime and/or minDistance to rate-limit
- * your update frequency in the case another application enables a
- * location provider with extremely fast updates.
- *
- * <p> The supplied Looper is used to implement the callback mechanism.
- *
- * <p class="note"> Prior to Jellybean, the minTime parameter was
- * only a hint, and some location provider implementations ignored it.
- * From Jellybean and onwards it is mandatory for Android compatible
- * devices to observe both the minTime and minDistance parameters.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param provider the name of the provider with which to register
* @param minTime minimum time interval between location updates, in milliseconds
@@ -577,13 +516,14 @@ public class LocationManager {
* {@link LocationListener#onLocationChanged} method will be called for
* each location update
* @param looper a Looper object whose message queue will be used to
- * implement the callback mechanism, or null to make callbacks on the
- * main thread
+ * implement the callback mechanism, or null to make callbacks on the calling
+ * thread
*
* @throws IllegalArgumentException if provider is null or doesn't exist
* @throws IllegalArgumentException if listener is null
- * @throws SecurityException if no suitable permission is present for the provider.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public void requestLocationUpdates(String provider, long minTime, float minDistance,
@@ -597,52 +537,11 @@ public class LocationManager {
}
/**
- * Registers the current activity to be notified periodically based on
- * the supplied criteria. Periodically, the supplied LocationListener will
- * be called with the current Location or with status updates.
- *
- * <p> It may take a while to receive the first location update. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> In case the provider is disabled by the user, updates will stop,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
- *
- * <p> The update interval can be controlled using the minTime parameter.
- * The elapsed time between location updates will never be less than
- * minTime, although it can be more depending on the Location Provider
- * implementation and the update interval requested by other applications.
- *
- * <p> Choosing a sensible value for minTime is important to conserve
- * battery life. Each location update requires power from
- * GPS, WIFI, Cell and other radios. Select a minTime value as high as
- * possible while still providing a reasonable user experience.
- * If your application is not in the foreground and showing
- * location to the user then your application should avoid using an active
- * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}),
- * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes)
- * or greater. If your application is in the foreground and showing
- * location to the user then it is appropriate to select a faster
- * update interval.
+ * Register for location updates using a Criteria, and a callback
+ * on the specified looper thread.
*
- * <p> The minDistance parameter can also be used to control the
- * frequency of location updates. If it is greater than 0 then the
- * location provider will only send your application an update when
- * the location has changed by at least minDistance meters, AND
- * at least minTime milliseconds have passed. However it is more
- * difficult for location providers to save power using the minDistance
- * parameter, so minTime should be the primary tool to conserving battery
- * life.
- *
- * <p> The supplied Looper is used to implement the callback mechanism.
- *
- * <p class="note"> Prior to Jellybean, the minTime parameter was
- * only a hint, and some location provider implementations ignored it.
- * From Jellybean and onwards it is mandatory for Android compatible
- * devices to observe both the minTime and minDistance parameters.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param minTime minimum time interval between location updates, in milliseconds
* @param minDistance minimum distance between location updates, in meters
@@ -652,13 +551,14 @@ public class LocationManager {
* {@link LocationListener#onLocationChanged} method will be called for
* each location update
* @param looper a Looper object whose message queue will be used to
- * implement the callback mechanism, or null to make callbacks on the
- * main thread.
+ * implement the callback mechanism, or null to make callbacks on the calling
+ * thread
*
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if listener is null
- * @throws SecurityException if no suitable permission is present for the provider.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public void requestLocationUpdates(long minTime, float minDistance, Criteria criteria,
@@ -672,70 +572,11 @@ public class LocationManager {
}
/**
- * Registers the current activity to be notified periodically by
- * the named provider. Periodically, the supplied PendingIntent will
- * be broadcast with the current Location or with status updates.
+ * Register for location updates using the named provider, and a
+ * pending intent.
*
- * <p> Location updates are sent with a key of
- * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value.
- *
- * <p> It may take a while to receive the first location update. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> The update interval can be controlled using the minTime parameter.
- * The elapsed time between location updates will never be less than
- * minTime, although it can be more depending on the Location Provider
- * implementation and the update interval requested by other applications.
- *
- * <p> Choosing a sensible value for minTime is important to conserve
- * battery life. Each location update requires power from
- * GPS, WIFI, Cell and other radios. Select a minTime value as high as
- * possible while still providing a reasonable user experience.
- * If your application is not in the foreground and showing
- * location to the user then your application should avoid using an active
- * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}),
- * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes)
- * or greater. If your application is in the foreground and showing
- * location to the user then it is appropriate to select a faster
- * update interval.
- *
- * <p> The minDistance parameter can also be used to control the
- * frequency of location updates. If it is greater than 0 then the
- * location provider will only send your application an update when
- * the location has changed by at least minDistance meters, AND
- * at least minTime milliseconds have passed. However it is more
- * difficult for location providers to save power using the minDistance
- * parameter, so minTime should be the primary tool to conserving battery
- * life.
- *
- * <p> If your application wants to passively observe location
- * updates triggered by other applications, but not consume
- * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER}
- * This provider does not actively turn on or modify active location
- * providers, so you do not need to be as careful about minTime and
- * minDistance. However if your application performs heavy work
- * on a location update (such as network activity) then you should
- * select non-zero values for minTime and/or minDistance to rate-limit
- * your update frequency in the case another application enables a
- * location provider with extremely fast updates.
- *
- * <p> If the provider is disabled by the user, updates will stop,
- * and an intent will be sent with an extra with key
- * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false.
- * If the provider is re-enabled, an intent will be sent with an
- * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of
- * true and location updates will start again.
- *
- * <p> If the provider's status changes, an intent will be sent with
- * an extra with key {@link #KEY_STATUS_CHANGED} and an integer value
- * indicating the new status. Any extras associated with the status
- * update will be sent as well.
- *
- * <p class="note"> Prior to Jellybean, the minTime parameter was
- * only a hint, and some location provider implementations ignored it.
- * From Jellybean and onwards it is mandatory for Android compatible
- * devices to observe both the minTime and minDistance parameters.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param provider the name of the provider with which to register
* @param minTime minimum time interval between location updates, in milliseconds
@@ -745,8 +586,9 @@ public class LocationManager {
* @throws IllegalArgumentException if provider is null or doesn't exist
* on this device
* @throws IllegalArgumentException if intent is null
- * @throws SecurityException if no suitable permission is present for the provider.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public void requestLocationUpdates(String provider, long minTime, float minDistance,
@@ -760,18 +602,28 @@ public class LocationManager {
}
/**
- * Registers the current activity to be notified periodically based on
- * the supplied criteria. Periodically, the supplied PendingIntent will
- * be broadcast with the current Location or with status updates.
+ * Register for location updates using a Criteria and pending intent.
*
- * <p> Location updates are sent with a key of
- * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value.
+ * <p>The <code>requestLocationUpdates()</code> and
+ * <code>requestSingleUpdate()</code> methods involving
+ * an explicit String provider or {@link Criteria} are deprecated.
+ *
+ * <p>They register the current activity to be updated
+ * periodically by the named provider, or by the provider matching
+ * the specified {@link Criteria}, with location and status updates.
*
* <p> It may take a while to receive the first location update. If
* an immediate location is required, applications may use the
* {@link #getLastKnownLocation(String)} method.
*
- * <p> The update interval can be controlled using the minTime parameter.
+ * <p> Location updates are received either by {@link LocationListener}
+ * callbacks, or by broadcast intents to a supplied {@link PendingIntent}.
+ *
+ * <p> If the caller supplied a pending intent, then location updates
+ * are sent with a key of {@link #KEY_LOCATION_CHANGED} and a
+ * {@link android.location.Location} value.
+ *
+ * <p> The location update interval can be controlled using the minTime parameter.
* The elapsed time between location updates will never be less than
* minTime, although it can be more depending on the Location Provider
* implementation and the update interval requested by other applications.
@@ -797,17 +649,36 @@ public class LocationManager {
* parameter, so minTime should be the primary tool to conserving battery
* life.
*
- * <p> If the provider is disabled by the user, updates will stop,
- * and an intent will be sent with an extra with key
- * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false.
- * If the provider is re-enabled, an intent will be sent with an
- * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of
- * true and location updates will start again.
+ * <p> If your application wants to passively observe location
+ * updates triggered by other applications, but not consume
+ * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER}
+ * This provider does not actively turn on or modify active location
+ * providers, so you do not need to be as careful about minTime and
+ * minDistance. However if your application performs heavy work
+ * on a location update (such as network activity) then you should
+ * select non-zero values for minTime and/or minDistance to rate-limit
+ * your update frequency in the case another application enables a
+ * location provider with extremely fast updates.
*
- * <p> If the provider's status changes, an intent will be sent with
- * an extra with key {@link #KEY_STATUS_CHANGED} and an integer value
- * indicating the new status. Any extras associated with the status
- * update will be sent as well.
+ * <p>In case the provider is disabled by the user, updates will stop,
+ * and a provider availability update will be sent.
+ * As soon as the provider is enabled again,
+ * location updates will immediately resume and a provider availability
+ * update sent. Providers can also send status updates, at any time,
+ * with extra's specific to the provider. If a callback was supplied
+ * then status and availability updates are via
+ * {@link LocationListener#onProviderDisabled},
+ * {@link LocationListener#onProviderEnabled} or
+ * {@link LocationListener#onStatusChanged}. Alternately, if a
+ * pending intent was supplied then status and availability updates
+ * are broadcast intents with extra keys of
+ * {@link #KEY_PROVIDER_ENABLED} or {@link #KEY_STATUS_CHANGED}.
+ *
+ * <p> If a {@link LocationListener} is used but with no Looper specified
+ * then the calling thread must already
+ * be a {@link android.os.Looper} thread such as the main thread of the
+ * calling Activity. If a Looper is specified with a {@link LocationListener}
+ * then callbacks are made on the supplied Looper thread.
*
* <p class="note"> Prior to Jellybean, the minTime parameter was
* only a hint, and some location provider implementations ignored it.
@@ -822,8 +693,9 @@ public class LocationManager {
*
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if intent is null
- * @throws SecurityException if no suitable permission is present for the provider.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public void requestLocationUpdates(long minTime, float minDistance, Criteria criteria,
@@ -837,32 +709,25 @@ public class LocationManager {
}
/**
- * Requests a single location update from the named provider.
- *
- * <p> It may take a while to receive the most recent location. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> In case the provider is disabled by the user, the update will not be received,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
+ * Register for a single location update using the named provider and
+ * a callback.
*
- * <p> The supplied Looper is used to implement the callback mechanism.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param provider the name of the provider with which to register
* @param listener a {#link LocationListener} whose
* {@link LocationListener#onLocationChanged} method will be called when
* the location update is available
* @param looper a Looper object whose message queue will be used to
- * implement the callback mechanism, or null to make callbacks on the
- * main thread
+ * implement the callback mechanism, or null to make callbacks on the calling
+ * thread
*
* @throws IllegalArgumentException if provider is null or doesn't exist
* @throws IllegalArgumentException if listener is null
- * @throws SecurityException if no suitable permission is present for the provider
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest#setNumUpdates} instead
*/
@Deprecated
public void requestSingleUpdate(String provider, LocationListener listener, Looper looper) {
@@ -875,19 +740,11 @@ public class LocationManager {
}
/**
- * Requests a single location update based on the specified criteria.
+ * Register for a single location update using a Criteria and
+ * a callback.
*
- * <p> It may take a while to receive the most recent location. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> In case the provider is disabled by the user, the update will not be received,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
- *
- * <p> The supplied Looper is used to implement the callback mechanism.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param criteria contains parameters for the location manager to choose the
* appropriate provider and parameters to compute the location
@@ -895,14 +752,14 @@ public class LocationManager {
* {@link LocationListener#onLocationChanged} method will be called when
* the location update is available
* @param looper a Looper object whose message queue will be used to
- * implement the callback mechanism, or null to make callbacks on the
- * main thread
+ * implement the callback mechanism, or null to make callbacks on the calling
+ * thread
*
* @throws IllegalArgumentException if criteria is null
* @throws IllegalArgumentException if listener is null
- * @throws SecurityException if no suitable permission is present to access
- * the location services
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest#setNumUpdates} instead
*/
@Deprecated
public void requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper) {
@@ -915,28 +772,19 @@ public class LocationManager {
}
/**
- * Requests a single location update from the named provider.
+ * Register for a single location update using a named provider and pending intent.
*
- * <p> It may take a while to receive the most recent location. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> Location updates are sent with a key of
- * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value.
- *
- * <p> In case the provider is disabled by the user, the update will not be received,
- * and the {@link LocationListener#onProviderDisabled(String)}
- * method will be called. As soon as the provider is enabled again,
- * the {@link LocationListener#onProviderEnabled(String)} method will
- * be called and location updates will start again.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param provider the name of the provider with which to register
* @param intent a {#link PendingIntent} to be sent for the location update
*
* @throws IllegalArgumentException if provider is null or doesn't exist
* @throws IllegalArgumentException if intent is null
- * @throws SecurityException if no suitable permission is present for the provider
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest#setNumUpdates} instead
*/
@Deprecated
public void requestSingleUpdate(String provider, PendingIntent intent) {
@@ -949,21 +797,10 @@ public class LocationManager {
}
/**
- * Requests a single location update based on the specified criteria.
+ * Register for a single location update using a Criteria and pending intent.
*
- * <p> It may take a while to receive the most recent location. If
- * an immediate location is required, applications may use the
- * {@link #getLastKnownLocation(String)} method.
- *
- * <p> Location updates are sent with a key of
- * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value.
- *
- * <p> If the provider is disabled by the user, an update will not be
- * received, and an intent will be sent with an extra with key
- * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false.
- * If the provider is re-enabled, an intent will be sent with an
- * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of
- * true and the location update will occur.
+ * <p>See {@link #requestLocationUpdates(long, float, Criteria, PendingIntent)}
+ * for more detail on how to use this (deprecated) method.
*
* @param criteria contains parameters for the location manager to choose the
* appropriate provider and parameters to compute the location
@@ -971,8 +808,9 @@ public class LocationManager {
*
* @throws IllegalArgumentException if provider is null or doesn't exist
* @throws IllegalArgumentException if intent is null
- * @throws SecurityException if no suitable permission is present for the provider
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest#setNumUpdates} instead
*/
@Deprecated
public void requestSingleUpdate(Criteria criteria, PendingIntent intent) {
@@ -984,12 +822,74 @@ public class LocationManager {
requestLocationUpdates(request, null, null, intent);
}
+ /**
+ * Register for fused location updates using a LocationRequest and callback.
+ *
+ * <p>The system will automatically select and enable the best providers
+ * to compute a location for your application. It may use only passive
+ * locations, or just a single location source, or it may fuse together
+ * multiple location sources in order to produce the best possible
+ * result, depending on the quality of service requested in the
+ * {@link LocationRequest}.
+ *
+ * <p>LocationRequest can be null, in which case the system will choose
+ * default, low power parameters for location updates. You will occasionally
+ * receive location updates as available, without a major power impact on the
+ * system. If your application just needs an occasional location update
+ * without any strict demands, then pass a null LocationRequest.
+ *
+ * <p>Only one LocationRequest can be registered for each unique callback
+ * or pending intent. So a subsequent request with the same callback or
+ * pending intent will over-write the previous LocationRequest.
+ *
+ * <p> If a pending intent is supplied then location updates
+ * are sent with a key of {@link #KEY_LOCATION_CHANGED} and a
+ * {@link android.location.Location} value. If a callback is supplied
+ * then location updates are made using the
+ * {@link LocationListener#onLocationChanged} callback, on the specified
+ * Looper thread. If a {@link LocationListener} is used
+ * but with a null Looper then the calling thread must already
+ * be a {@link android.os.Looper} thread (such as the main thread) and
+ * callbacks will occur on this thread.
+ *
+ * <p> Provider status updates and availability updates are deprecated
+ * because the system is performing provider fusion on the applications
+ * behalf. So {@link LocationListener#onProviderDisabled},
+ * {@link LocationListener#onProviderEnabled}, {@link LocationListener#onStatusChanged}
+ * will not be called, and intents with extra keys of
+ * {@link #KEY_PROVIDER_ENABLED} or {@link #KEY_STATUS_CHANGED} will not
+ * be received.
+ *
+ * @param request quality of service required, null for default low power
+ * @param listener a {#link LocationListener} whose
+ * {@link LocationListener#onLocationChanged} method will be called when
+ * the location update is available
+ * @param looper a Looper object whose message queue will be used to
+ * implement the callback mechanism, or null to make callbacks on the calling
+ * thread
+ *
+ * @throws IllegalArgumentException if listener is null
+ * @throws SecurityException if no suitable permission is present
+ */
public void requestLocationUpdates(LocationRequest request, LocationListener listener,
Looper looper) {
checkListener(listener);
requestLocationUpdates(request, listener, looper, null);
}
+
+ /**
+ * Register for fused location updates using a LocationRequest and a pending intent.
+ *
+ * <p> See {@link #requestLocationUpdates(LocationRequest, LocationListener, Looper)}
+ * for more detail.
+ *
+ * @param request quality of service required, null for default low power
+ * @param intent a {#link PendingIntent} to be sent for the location update
+ *
+ * @throws IllegalArgumentException if intent is null
+ * @throws SecurityException if no suitable permission is present
+ */
public void requestLocationUpdates(LocationRequest request, PendingIntent intent) {
checkPendingIntent(intent);
requestLocationUpdates(request, null, null, intent);
@@ -1023,11 +923,12 @@ public class LocationManager {
}
/**
- * Removes any current registration for location updates of the current activity
- * with the given LocationListener. Following this call, updates will no longer
+ * Removes all location updates for the specified LocationListener.
+ *
+ * <p>Following this call, updates will no longer
* occur for this listener.
*
- * @param listener {#link LocationListener} object that no longer needs location updates
+ * @param listener listener object that no longer needs location updates
* @throws IllegalArgumentException if listener is null
*/
public void removeUpdates(LocationListener listener) {
@@ -1048,11 +949,11 @@ public class LocationManager {
}
/**
- * Removes any current registration for location updates of the current activity
- * with the given PendingIntent. Following this call, updates will no longer
- * occur for this intent.
+ * Removes all location updates for the specified pending intent.
+ *
+ * <p>Following this call, updates will no longer for this pending intent.
*
- * @param intent {#link PendingIntent} object that no longer needs location updates
+ * @param intent pending intent object that no longer needs location updates
* @throws IllegalArgumentException if intent is null
*/
public void removeUpdates(PendingIntent intent) {
@@ -1067,8 +968,10 @@ public class LocationManager {
}
/**
- * Sets a proximity alert for the location given by the position
- * (latitude, longitude) and the given radius. When the device
+ * Set a proximity alert for the location given by the position
+ * (latitude, longitude) and the given radius.
+ *
+ * <p> When the device
* detects that it has entered or exited the area surrounding the
* location, the given PendingIntent will be used to create an Intent
* to be fired.
@@ -1088,10 +991,6 @@ public class LocationManager {
* alert and no longer monitor it. A value of -1 indicates that
* there should be no expiration time.
*
- * <p> In case the screen goes to sleep, checks for proximity alerts
- * happen only once every 4 minutes. This conserves battery life by
- * ensuring that the device isn't perpetually awake.
- *
* <p> Internally, this method uses both {@link #NETWORK_PROVIDER}
* and {@link #GPS_PROVIDER}.
*
@@ -1106,9 +1005,9 @@ public class LocationManager {
* @param intent a PendingIntent that will be used to generate an Intent to
* fire when entry to or exit from the alert region is detected
*
- * @throws SecurityException if no permission exists for the required
- * providers.
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} and {@link Geofence} instead
*/
@Deprecated
public void addProximityAlert(double latitude, double longitude, float radius, long expiration,
@@ -1125,7 +1024,40 @@ public class LocationManager {
}
}
- public void requestGeofence(LocationRequest request, Geofence fence, PendingIntent intent) {
+ /**
+ * Add a geofence with the specified LocationRequest quality of service.
+ *
+ * <p> When the device
+ * detects that it has entered or exited the area surrounding the
+ * location, the given PendingIntent will be used to create an Intent
+ * to be fired.
+ *
+ * <p> The fired Intent will have a boolean extra added with key
+ * {@link #KEY_PROXIMITY_ENTERING}. If the value is true, the device is
+ * entering the proximity region; if false, it is exiting.
+ *
+ * <p> The geofence engine fuses results from all location providers to
+ * provide the best balance between accuracy and power. Applications
+ * can choose the quality of service required using the
+ * {@link LocationRequest} object. If it is null then a default,
+ * low power geo-fencing implementation is used. It is possible to cross
+ * a geo-fence without notification, but the system will do its best
+ * to detect, using {@link LocationRequest} as a hint to trade-off
+ * accuracy and power.
+ *
+ * <p> The power required by the geofence engine can depend on many factors,
+ * such as quality and interval requested in {@link LocationRequest},
+ * distance to nearest geofence and current device velocity.
+ *
+ * @param request quality of service required, null for default low power
+ * @param fence a geographical description of the geofence area
+ * @param intent pending intent to receive geofence updates
+ *
+ * @throws IllegalArgumentException if fence is null
+ * @throws IllegalArgumentException if intent is null
+ * @throws SecurityException if no suitable permission is present
+ */
+ public void addGeofence(LocationRequest request, Geofence fence, PendingIntent intent) {
checkPendingIntent(intent);
checkGeofence(fence);
@@ -1141,7 +1073,11 @@ public class LocationManager {
*
* @param intent the PendingIntent that no longer needs to be notified of
* proximity alerts
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @throws IllegalArgumentException if intent is null
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} and {@link Geofence} instead
*/
@Deprecated
public void removeProximityAlert(PendingIntent intent) {
@@ -1155,6 +1091,19 @@ public class LocationManager {
}
}
+ /**
+ * Remove a single geofence.
+ *
+ * <p>This removes only the specified geofence associated with the
+ * specified pending intent. All other geofences remain unchanged.
+ *
+ * @param fence a geofence previously passed to {@link #addGeofence}
+ * @param intent a pending intent previously passed to {@link #addGeofence}
+ *
+ * @throws IllegalArgumentException if fence is null
+ * @throws IllegalArgumentException if intent is null
+ * @throws SecurityException if no suitable permission is present
+ */
public void removeGeofence(Geofence fence, PendingIntent intent) {
checkPendingIntent(intent);
checkGeofence(fence);
@@ -1167,6 +1116,14 @@ public class LocationManager {
}
}
+ /**
+ * Remove all geofences registered to the specified pending intent.
+ *
+ * @param intent a pending intent previously passed to {@link #addGeofence}
+ *
+ * @throws IllegalArgumentException if intent is null
+ * @throws SecurityException if no suitable permission is present
+ */
public void removeAllGeofences(PendingIntent intent) {
checkPendingIntent(intent);
String packageName = mContext.getPackageName();
@@ -1179,16 +1136,18 @@ public class LocationManager {
}
/**
- * Returns the current enabled/disabled status of the given provider. If the
- * user has enabled this provider in the Settings menu, true is returned
- * otherwise false is returned
+ * Returns the current enabled/disabled status of the given provider.
+ *
+ * <p>If the user has enabled this provider in the Settings menu, true
+ * is returned otherwise false is returned
*
* @param provider the name of the provider
* @return true if the provider is enabled
*
- * @throws SecurityException if no suitable permission is present for the provider.
* @throws IllegalArgumentException if provider is null
- * @deprecated use the {@link LocationRequest} class instead
+ * @throws SecurityException if no suitable permission is present
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public boolean isProviderEnabled(String provider) {
@@ -1202,19 +1161,32 @@ public class LocationManager {
}
}
- public Location getLastLocation(LocationRequest request) {
+ /**
+ * Get the last known location.
+ *
+ * <p>This location could be very old so use
+ * {@link Location#getElapsedRealtimeNano} to calculate its age. It can
+ * also return null if no previous location is available.
+ *
+ * <p>Always returns immediately.
+ *
+ * @return The last known location, or null if not available
+ * @throws SecurityException if no suitable permission is present
+ */
+ public Location getLastLocation() {
try {
- return mService.getLastLocation(request);
+ return mService.getLastLocation(null);
} catch (RemoteException e) {
Log.e(TAG, "RemoteException", e);
return null;
}
}
-
/**
* Returns a Location indicating the data from the last known
- * location fix obtained from the given provider. This can be done
+ * location fix obtained from the given provider.
+ *
+ * <p> This can be done
* without starting the provider. Note that this location could
* be out-of-date, for example if the device was turned off and
* moved to another location.
@@ -1224,9 +1196,10 @@ public class LocationManager {
* @param provider the name of the provider
* @return the last known location for the provider, or null
*
- * @throws SecurityException if no suitable permission is present for the provider.
+ * @throws SecurityException if no suitable permission is present
* @throws IllegalArgumentException if provider is null or doesn't exist
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated Use {@link #getLastLocation} instead
*/
@Deprecated
public Location getLastKnownLocation(String provider) {
@@ -1243,27 +1216,21 @@ public class LocationManager {
}
}
- // Mock provider support
+ // --- Mock provider support ---
+ // TODO: It would be fantastic to deprecate mock providers entirely, and replace
+ // with something closer to LocationProviderBase.java
/**
* Creates a mock location provider and adds it to the set of active providers.
*
* @param name the provider name
- * @param requiresNetwork
- * @param requiresSatellite
- * @param requiresCell
- * @param hasMonetaryCost
- * @param supportsAltitude
- * @param supportsSpeed
- * @param supportsBearing
- * @param powerRequirement
- * @param accuracy
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
* @throws IllegalArgumentException if a provider with the given name already exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite,
@@ -1292,7 +1259,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void removeTestProvider(String provider) {
@@ -1318,7 +1286,8 @@ public class LocationManager {
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
* @throws IllegalArgumentException if the location is incomplete
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void setTestProviderLocation(String provider, Location loc) {
@@ -1351,7 +1320,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void clearTestProviderLocation(String provider) {
@@ -1373,7 +1343,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void setTestProviderEnabled(String provider, boolean enabled) {
@@ -1393,7 +1364,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void clearTestProviderEnabled(String provider) {
@@ -1417,7 +1389,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void setTestProviderStatus(String provider, int status, Bundle extras, long updateTime) {
@@ -1437,7 +1410,8 @@ public class LocationManager {
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated requesting location providers by name is deprecated
*/
@Deprecated
public void clearTestProviderStatus(String provider) {
@@ -1448,7 +1422,7 @@ public class LocationManager {
}
}
- // GPS-specific support
+ // --- GPS-specific support ---
// This class is used to send GPS status events to the client's main thread.
private class GpsStatusListenerTransport extends IGpsStatusListener.Stub {
@@ -1682,7 +1656,8 @@ public class LocationManager {
* The provider may optionally fill the extras Bundle with results from the command.
*
* @return true if the command succeeds.
- * @deprecated use the {@link LocationRequest} class instead
+ *
+ * @deprecated Use {@link LocationRequest} instead, see notes on {@link LocationManager}
*/
@Deprecated
public boolean sendExtraCommand(String provider, String command, Bundle extras) {
@@ -1698,7 +1673,7 @@ public class LocationManager {
* Used by NetInitiatedActivity to report user response
* for network initiated GPS fix requests.
*
- * {@hide}
+ * @hide
*/
public boolean sendNiResponse(int notifId, int userResponse) {
try {
@@ -1720,6 +1695,7 @@ public class LocationManager {
throw new IllegalArgumentException("invalid criteria: " + criteria);
}
}
+
private static void checkListener(LocationListener listener) {
if (listener == null) {
throw new IllegalArgumentException("invalid listener: " + listener);
diff --git a/location/java/android/location/LocationRequest.java b/location/java/android/location/LocationRequest.java
index ce49b41..b1863b8 100644
--- a/location/java/android/location/LocationRequest.java
+++ b/location/java/android/location/LocationRequest.java
@@ -21,24 +21,140 @@ import android.os.Parcelable;
import android.os.SystemClock;
import android.util.TimeUtils;
+
+/**
+ * A data object that contains quality of service parameters for requests
+ * to the {@link LocationManager}.
+ *
+ * <p>LocationRequest objects are used to request a quality of service
+ * for location updates from the Location Manager.
+ *
+ * <p>For example, if your application wants high accuracy location
+ * it should create a location request with {@link #setQuality} set to
+ * {@link #ACCURACY_FINE} or {@link #POWER_HIGH}, and it should set
+ * {@link #setInterval} to less than one second. This would be
+ * appropriate for mapping applications that are showing your location
+ * in real-time.
+ *
+ * <p>At the other extreme, if you want negligible power
+ * impact, but to still receive location updates when available, then use
+ * {@link #setQuality} with {@link #POWER_NONE}. With this request your
+ * application will not trigger (and therefore will not receive any
+ * power blame) any location updates, but will receive locations
+ * triggered by other applications. This would be appropriate for
+ * applications that have no firm requirement for location, but can
+ * take advantage when available.
+ *
+ * <p>In between these two extremes is a very common use-case, where
+ * applications definitely want to receive
+ * updates at a specified interval, and can receive them faster when
+ * available, but still want a low power impact. These applications
+ * should consider {@link #POWER_LOW} combined with a faster
+ * {@link #setFastestInterval} (such as 1 minute) and a slower
+ * {@link #setInterval} (such as 60 minutes). They will only be assigned
+ * power blame for the interval set by {@link #setInterval}, but can
+ * still receive locations triggered by other applications at a rate up
+ * to {@link #setFastestInterval}. This style of request is appropriate for
+ * many location aware applications, including background usage. Do be
+ * careful to also throttle {@link #setFastestInterval} if you perform
+ * heavy-weight work after receiving an update - such as using the network.
+ *
+ * <p>Activities should strongly consider removing all location
+ * request when entering the background
+ * (for example at {@link android.app.Activity#onPause}), or
+ * at least swap the request to a larger interval and lower quality.
+ * Future version of the location manager may automatically perform background
+ * throttling on behalf of applications.
+ *
+ * <p>Applications cannot specify the exact location sources that are
+ * used by Android's <em>Fusion Engine</em>. In fact, the system
+ * may have multiple location sources (providers) running and may
+ * fuse the results from several sources into a single Location object.
+ *
+ * <p>Location requests from applications with
+ * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} and not
+ * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} will
+ * be automatically throttled to a slower interval, and the location
+ * object will be obfuscated to only show a coarse level of accuracy.
+ *
+ * <p>All location requests are considered hints, and you may receive
+ * locations that are more accurate, less accurate, and slower
+ * than requested.
+ */
public final class LocationRequest implements Parcelable {
- // QOS control
- public static final int ACCURACY_FINE = 100; // ~1 meter
- public static final int ACCURACY_BLOCK = 102; // ~100 meters
- public static final int ACCURACY_CITY = 104; // ~10 km
+ /**
+ * Used with {@link #setQuality} to request the most accurate locations available.
+ *
+ * <p>This may be up to 1 meter accuracy, although this is implementation dependent.
+ */
+ public static final int ACCURACY_FINE = 100;
+
+ /**
+ * Used with {@link #setQuality} to request "block" level accuracy.
+ *
+ * <p>Block level accuracy is considered to be about 100 meter accuracy,
+ * although this is implementation dependent. Using a coarse accuracy
+ * such as this often consumes less power.
+ */
+ public static final int ACCURACY_BLOCK = 102;
+
+ /**
+ * Used with {@link #setQuality} to request "city" level accuracy.
+ *
+ * <p>City level accuracy is considered to be about 10km accuracy,
+ * although this is implementation dependent. Using a coarse accuracy
+ * such as this often consumes less power.
+ */
+ public static final int ACCURACY_CITY = 104;
+
+ /**
+ * Used with {@link #setQuality} to require no direct power impact (passive locations).
+ *
+ * <p>This location request will not trigger any active location requests,
+ * but will receive locations triggered by other applications. Your application
+ * will not receive any direct power blame for location work.
+ */
public static final int POWER_NONE = 200;
+
+ /**
+ * Used with {@link #setQuality} to request low power impact.
+ *
+ * <p>This location request will avoid high power location work where
+ * possible.
+ */
public static final int POWER_LOW = 201;
+
+ /**
+ * Used with {@link #setQuality} to allow high power consumption for location.
+ *
+ * <p>This location request will allow high power location work.
+ */
public static final int POWER_HIGH = 203;
+ /**
+ * By default, mFastestInterval = FASTEST_INTERVAL_MULTIPLE * mInterval
+ */
+ private static final double FASTEST_INTERVAL_FACTOR = 6.0; // 6x
+
private int mQuality = POWER_LOW;
- private long mFastestInterval = 6 * 1000; // 6 seconds
- private long mInterval = 60 * 1000; // 1 minute
+ private long mInterval = 60 * 60 * 1000; // 60 minutes
+ private long mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR); // 10 minutes
+ private boolean mExplicitFastestInterval = false;
private long mExpireAt = Long.MAX_VALUE; // no expiry
private int mNumUpdates = Integer.MAX_VALUE; // no expiry
private float mSmallestDisplacement = 0.0f; // meters
private String mProvider = null; // for deprecated API's that explicitly request a provider
+ /**
+ * Create a location request with default parameters.
+ *
+ * <p>Default parameters are for a low power, slowly updated location.
+ * It can then be adjusted as required by the applications before passing
+ * to the {@link LocationManager}
+ *
+ * @return a new location request
+ */
public static LocationRequest create() {
LocationRequest request = new LocationRequest();
return request;
@@ -105,52 +221,217 @@ public final class LocationRequest implements Parcelable {
/** @hide */
public LocationRequest() { }
+ /**
+ * Set the quality of the request.
+ *
+ * <p>Use with a accuracy constant such as {@link #ACCURACY_FINE}, or a power
+ * constant such as {@link #POWER_LOW}. You cannot request both and accuracy and
+ * power, only one or the other can be specified. The system will then
+ * maximize accuracy or minimize power as appropriate.
+ *
+ * <p>The quality of the request is a strong hint to the system for which
+ * location sources to use. For example, {@link #ACCURACY_FINE} is more likely
+ * to use GPS, and {@link #POWER_LOW} is more likely to use WIFI & Cell tower
+ * positioning, but it also depends on many other factors (such as which sources
+ * are available) and is implementation dependent.
+ *
+ * <p>{@link #setQuality} and {@link #setInterval} are the most important parameters
+ * on a location request.
+ *
+ * @param quality an accuracy or power constant
+ * @throws InvalidArgumentException if the quality constant is not valid
+ * @return the same object, so that setters can be chained
+ */
public LocationRequest setQuality(int quality) {
checkQuality(quality);
mQuality = quality;
return this;
}
+ /**
+ * Get the quality of the request.
+ *
+ * @return an accuracy or power constant
+ */
public int getQuality() {
return mQuality;
}
+ /**
+ * Set the desired interval for active location updates, in milliseconds.
+ *
+ * <p>The location manager will actively try to obtain location updates
+ * for your application at this interval, so it has a
+ * direct influence on the amount of power used by your application.
+ * Choose your interval wisely.
+ *
+ * <p>This interval is inexact. You may not receive updates at all (if
+ * no location sources are available), or you may receive them
+ * slower than requested. You may also receive them faster than
+ * requested (if other applications are requesting location at a
+ * faster interval). The fastest rate that that you will receive
+ * updates can be controlled with {@link #setFastestInterval}.
+ *
+ * <p>Applications with only the coarse location permission may have their
+ * interval silently throttled.
+ *
+ * <p>An interval of 0 is allowed, but not recommended, since
+ * location updates may be extremely fast on future implementations.
+ *
+ * <p>{@link #setQuality} and {@link #setInterval} are the most important parameters
+ * on a location request.
+ *
+ * @param millis desired interval in millisecond, inexact
+ * @throws InvalidArgumentException if the interval is less than zero
+ * @return the same object, so that setters can be chained
+ */
public LocationRequest setInterval(long millis) {
checkInterval(millis);
mInterval = millis;
+ if (!mExplicitFastestInterval) {
+ mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR);
+ }
return this;
}
+ /**
+ * Get the desired interval of this request, in milliseconds.
+ *
+ * @return desired interval in milliseconds, inexact
+ */
public long getInterval() {
return mInterval;
}
+ /**
+ * Explicitly set the fastest interval for location updates, in
+ * milliseconds.
+ *
+ * <p>This controls the fastest rate at which your application will
+ * receive location updates, which might be faster than
+ * {@link #setInterval} in some situations (for example, if other
+ * applications are triggering location updates).
+ *
+ * <p>This allows your application to passively acquire locations
+ * at a rate faster than it actively acquires locations, saving power.
+ *
+ * <p>Unlike {@link #setInterval}, this parameter is exact. Your
+ * application will never receive updates faster than this value.
+ *
+ * <p>If you don't call this method, a fastest interval
+ * will be selected for you. It will be a value faster than your
+ * active interval ({@link #setInterval}).
+ *
+ * <p>An interval of 0 is allowed, but not recommended, since
+ * location updates may be extremely fast on future implementations.
+ *
+ * <p>If {@link #setFastestInterval} is set slower than {@link #setInterval},
+ * then your effective fastest interval is {@link #setInterval}.
+ *
+ * @param millis fastest interval for updates in milliseconds, exact
+ * @throws InvalidArgumentException if the interval is less than zero
+ * @return the same object, so that setters can be chained
+ */
public LocationRequest setFastestInterval(long millis) {
checkInterval(millis);
+ mExplicitFastestInterval = true;
mFastestInterval = millis;
return this;
}
+ /**
+ * Get the fastest interval of this request, in milliseconds.
+ *
+ * <p>The system will never provide location updates faster
+ * than the minimum of {@link #getFastestInterval} and
+ * {@link #getInterval}.
+ *
+ * @return fastest interval in milliseconds, exact
+ */
public long getFastestInterval() {
return mFastestInterval;
}
+ /**
+ * Set the duration of this request, in milliseconds.
+ *
+ * <p>The duration begins immediately (and not when the request
+ * is passed to the location manager), so call this method again
+ * if the request is re-used at a later time.
+ *
+ * <p>The location manager will automatically stop updates after
+ * the request expires.
+ *
+ * <p>The duration includes suspend time. Values less than 0
+ * are allowed, but indicate that the request has already expired.
+ *
+ * @param millis duration of request in milliseconds
+ * @return the same object, so that setters can be chained
+ */
public LocationRequest setExpireIn(long millis) {
mExpireAt = millis + SystemClock.elapsedRealtime();
if (mExpireAt < 0) mExpireAt = 0;
return this;
}
+ /**
+ * Set the request expiration time, in millisecond since boot.
+ *
+ * <p>This expiration time uses the same time base as {@link SystemClock#elapsedRealtime}.
+ *
+ * <p>The location manager will automatically stop updates after
+ * the request expires.
+ *
+ * <p>The duration includes suspend time. Values before {@link SystemClock#elapsedRealtime}
+ * are allowed, but indicate that the request has already expired.
+ *
+ * @param millis expiration time of request, in milliseconds since boot including suspend
+ * @return the same object, so that setters can be chained
+ */
public LocationRequest setExpireAt(long millis) {
mExpireAt = millis;
if (mExpireAt < 0) mExpireAt = 0;
return this;
}
+ /**
+ * Get the request expiration time, in milliseconds since boot.
+ *
+ * <p>This value can be compared to {@link SystemClock#elapsedRealtime} to determine
+ * the time until expiration.
+ *
+ * @return expiration time of request, in milliseconds since boot including suspend
+ */
public long getExpireAt() {
return mExpireAt;
}
+ /**
+ * Set the number of location updates.
+ *
+ * <p>By default locations are continuously updated until the request is explicitly
+ * removed, however you can optionally request a set number of updates.
+ * For example, if your application only needs a single fresh location,
+ * then call this method with a value of 1 before passing the request
+ * to the location manager.
+ *
+ * @param numUpdates the number of location updates requested
+ * @throws InvalidArgumentException if numUpdates is 0 or less
+ * @return the same object, so that setters can be chained
+ */
+ public LocationRequest setNumUpdates(int numUpdates) {
+ if (numUpdates <= 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates);
+ mNumUpdates = numUpdates;
+ return this;
+ }
+
+ /**
+ * Get the number of updates requested.
+ *
+ * <p>By default this is {@link Integer#MAX_VALUE}, which indicates that
+ * locations are updated until the request is explicitly removed.
+ * @return number of updates
+ */
public int getNumUpdates() {
return mNumUpdates;
}
@@ -165,11 +446,6 @@ public final class LocationRequest implements Parcelable {
}
}
- public LocationRequest setNumUpdates(int numUpdates) {
- if (numUpdates < 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates);
- mNumUpdates = numUpdates;
- return this;
- }
/** @hide */
public LocationRequest setProvider(String provider) {
@@ -247,10 +523,12 @@ public final class LocationRequest implements Parcelable {
return new LocationRequest[size];
}
};
+
@Override
public int describeContents() {
return 0;
}
+
@Override
public void writeToParcel(Parcel parcel, int flags) {
parcel.writeInt(mQuality);