diff options
Diffstat (limited to 'location/java')
| -rw-r--r-- | location/java/android/location/Criteria.java | 4 | ||||
| -rw-r--r-- | location/java/android/location/Geofence.java | 10 | ||||
| -rw-r--r-- | location/java/android/location/Location.java | 225 | ||||
| -rw-r--r-- | location/java/android/location/LocationManager.java | 798 | ||||
| -rw-r--r-- | location/java/android/location/LocationRequest.java | 300 |
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); |