Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add javadoc for new location API's.

Browse Source 
Change-Id: If15024ee88421c07ba3a174747774fc451fd002e
This commit is contained in:
Nick Pelly
2012-08-13 19:35:39 -07:00
parent 74fa7eabda
commit 4e31c4fffb
8 changed files with 840 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
api/current.txt
View File

@@ -10549,7 +10549,7 @@ package android.location {
method public android.os.Bundle getExtras();
method public double getLatitude();
method public double getLongitude();
method public java.lang.String getProvider();
method public deprecated java.lang.String getProvider();
method public float getSpeed();
method public long getTime();
method public boolean hasAccuracy();
@@ -10587,6 +10587,7 @@ package android.location {
}
public class LocationManager {
method public void addGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent);
method public boolean addGpsStatusListener(android.location.GpsStatus.Listener);
method public boolean addNmeaListener(android.location.GpsStatus.NmeaListener);
method public deprecated void addProximityAlert(double, double, float, long, android.app.PendingIntent);
@@ -10598,7 +10599,7 @@ package android.location {
method public deprecated java.lang.String getBestProvider(android.location.Criteria, boolean);
method public android.location.GpsStatus getGpsStatus(android.location.GpsStatus);
method public deprecated android.location.Location getLastKnownLocation(java.lang.String);
method public android.location.Location getLastLocation(android.location.LocationRequest);
method public android.location.Location getLastLocation();
method public deprecated android.location.LocationProvider getProvider(java.lang.String);
method public deprecated java.util.List<java.lang.String> getProviders(boolean);
method public deprecated java.util.List<java.lang.String> getProviders(android.location.Criteria, boolean);
@@ -10611,7 +10612,6 @@ package android.location {
method public deprecated void removeTestProvider(java.lang.String);
method public void removeUpdates(android.location.LocationListener);
method public void removeUpdates(android.app.PendingIntent);
method public void requestGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent);
method public deprecated void requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener);
method public deprecated void requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener, android.os.Looper);
method public deprecated void requestLocationUpdates(long, float, android.location.Criteria, android.location.LocationListener, android.os.Looper);

4
location/java/android/location/Criteria.java
View File

@@ -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 {

10
location/java/android/location/Geofence.java
View File

@@ -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)

225
location/java/android/location/Location.java
View File

@@ -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.
*
* @param provider the name of the location provider that generated this
* location fix.
* <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 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
*/

798
location/java/android/location/LocationManager.java
View File

File diff suppressed because it is too large Load Diff

300
location/java/android/location/LocationRequest.java
View File

@@ -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);

1
packages/FusedLocation/src/com/android/location/fused/FusionEngine.java
View File

@@ -22,7 +22,6 @@ import java.util.HashMap;
import com.android.location.provider.ProviderRequestUnbundled;
import android.content.Context;
import android.location.Location;
import android.location.LocationListener;

13
services/java/com/android/server/LocationManagerService.java
View File

@@ -904,14 +904,17 @@ public class LocationManagerService extends ILocationManager.Stub implements Obs
request.setQuality(LocationRequest.POWER_LOW);
break;
}
// throttle fastest interval
// throttle
if (request.getInterval() < LocationFudger.FASTEST_INTERVAL_MS) {
request.setInterval(LocationFudger.FASTEST_INTERVAL_MS);
}
if (request.getFastestInterval() < LocationFudger.FASTEST_INTERVAL_MS) {
request.setFastestInterval(LocationFudger.FASTEST_INTERVAL_MS);
}
}
// throttle interval if its faster than the fastest interval
if (request.getInterval () < request.getFastestInterval()) {
request.setInterval(request.getFastestInterval());
// make getFastestInterval() the minimum of interval and fastest interval
if (request.getFastestInterval() > request.getInterval()) {
request.setFastestInterval(request.getInterval());
}
return perm;
}
@@ -1287,6 +1290,8 @@ public class LocationManagerService extends ILocationManager.Stub implements Obs
}
private void handleLocationChangedLocked(Location location, boolean passive) {
if (D) Log.d(TAG, "incoming location: " + location);
long now = SystemClock.elapsedRealtime();
String provider = (passive ? LocationManager.PASSIVE_PROVIDER : location.getProvider());
ArrayList<UpdateRecord> records = mRecordsByProvider.get(provider);