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

Update Location APIs per feedback

Browse Source 
Bug: 200730770
Test: presubmits
Change-Id: I251dcce3bae431ab3770e0610105c75e377c8d10
This commit is contained in:
Soonil Nagarkar
2022-02-24 15:04:38 -08:00
parent 6c6f6bd6d5
commit 91e3a080aa
2 changed files with 104 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
core/api/current.txt
View File

@@ -19465,26 +19465,26 @@ package android.location {
method @NonNull public static String convert(@FloatRange double, int);
method @FloatRange public static double convert(@NonNull String);
method public int describeContents();
method public static void distanceBetween(@FloatRange double, @FloatRange double, @FloatRange double, @FloatRange double, float[]);
method @FloatRange public float distanceTo(@NonNull android.location.Location);
method public void dump(@NonNull android.util.Printer, @Nullable String);
method @FloatRange public float getAccuracy();
method public static void distanceBetween(@FloatRange(from=-90.0, to=90.0) double, @FloatRange(from=-180.0, to=180.0) double, @FloatRange(from=-90.0, to=90.0) double, @FloatRange(from=-180.0, to=180.0) double, float[]);
method @FloatRange(from=0.0) public float distanceTo(@NonNull android.location.Location);
method @Deprecated public void dump(@NonNull android.util.Printer, @Nullable String);
method @FloatRange(from=0.0) public float getAccuracy();
method @FloatRange public double getAltitude();
method @FloatRange(from=0.0f, to=360.0f, toInclusive=false) public float getBearing();
method @FloatRange public float getBearingAccuracyDegrees();
method @IntRange public long getElapsedRealtimeAgeMillis();
method @IntRange public long getElapsedRealtimeAgeMillis(@IntRange long);
method @IntRange public long getElapsedRealtimeMillis();
method @IntRange public long getElapsedRealtimeNanos();
method @FloatRange public double getElapsedRealtimeUncertaintyNanos();
method @FloatRange(from=0.0, to=360.0, toInclusive=false) public float getBearing();
method @FloatRange(from=0.0) public float getBearingAccuracyDegrees();
method @IntRange(from=0) public long getElapsedRealtimeAgeMillis();
method public long getElapsedRealtimeAgeMillis(@IntRange(from=0) long);
method @IntRange(from=0) public long getElapsedRealtimeMillis();
method @IntRange(from=0) public long getElapsedRealtimeNanos();
method @FloatRange(from=0.0) public double getElapsedRealtimeUncertaintyNanos();
method @Nullable public android.os.Bundle getExtras();
method @FloatRange public double getLatitude();
method @FloatRange public double getLongitude();
method @FloatRange(from=-90.0, to=90.0) public double getLatitude();
method @FloatRange(from=-180.0, to=180.0) public double getLongitude();
method @Nullable public String getProvider();
method @FloatRange public float getSpeed();
method @FloatRange public float getSpeedAccuracyMetersPerSecond();
method @IntRange public long getTime();
method @FloatRange public float getVerticalAccuracyMeters();
method @FloatRange(from=0.0) public float getSpeed();
method @FloatRange(from=0.0) public float getSpeedAccuracyMetersPerSecond();
method @IntRange(from=0) public long getTime();
method @FloatRange(from=0.0) public float getVerticalAccuracyMeters();
method public boolean hasAccuracy();
method public boolean hasAltitude();
method public boolean hasBearing();
@@ -19506,21 +19506,21 @@ package android.location {
method public void removeVerticalAccuracy();
method public void reset();
method public void set(@NonNull android.location.Location);
method public void setAccuracy(@FloatRange float);
method public void setAccuracy(@FloatRange(from=0.0) float);
method public void setAltitude(@FloatRange double);
method public void setBearing(@FloatRange(fromInclusive=false, toInclusive=false) float);
method public void setBearingAccuracyDegrees(@FloatRange float);
method public void setElapsedRealtimeNanos(@IntRange long);
method public void setElapsedRealtimeUncertaintyNanos(@FloatRange double);
method public void setBearingAccuracyDegrees(@FloatRange(from=0.0) float);
method public void setElapsedRealtimeNanos(@IntRange(from=0) long);
method public void setElapsedRealtimeUncertaintyNanos(@FloatRange(from=0.0) double);
method public void setExtras(@Nullable android.os.Bundle);
method public void setLatitude(@FloatRange double);
method public void setLongitude(@FloatRange double);
method public void setLatitude(@FloatRange(from=-90.0, to=90.0) double);
method public void setLongitude(@FloatRange(from=-180.0, to=180.0) double);
method public void setMock(boolean);
method public void setProvider(@Nullable String);
method public void setSpeed(@FloatRange float);
method public void setSpeedAccuracyMetersPerSecond(@FloatRange float);
method public void setTime(@IntRange long);
method public void setVerticalAccuracyMeters(@FloatRange float);
method public void setSpeed(@FloatRange(from=0.0) float);
method public void setSpeedAccuracyMetersPerSecond(@FloatRange(from=0.0) float);
method public void setTime(@IntRange(from=0) long);
method public void setVerticalAccuracyMeters(@FloatRange(from=0.0) float);
method public void writeToParcel(@NonNull android.os.Parcel, int);
field @NonNull public static final android.os.Parcelable.Creator<android.location.Location> CREATOR;
field public static final int FORMAT_DEGREES = 0; // 0x0

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

@@ -132,31 +132,31 @@ public class Location implements Parcelable {
}
/**
* Construct a new Location object that is copied from an existing one.
* Constructs a new location copied from the given location.
*/
public Location(@NonNull Location l) {
set(l);
public Location(@NonNull Location location) {
set(location);
}
/**
* Turns this location into a copy of the given location.
*/
public void set(@NonNull Location l) {
mFieldsMask = l.mFieldsMask;
mProvider = l.mProvider;
mTimeMs = l.mTimeMs;
mElapsedRealtimeNs = l.mElapsedRealtimeNs;
mElapsedRealtimeUncertaintyNs = l.mElapsedRealtimeUncertaintyNs;
mLatitudeDegrees = l.mLatitudeDegrees;
mLongitudeDegrees = l.mLongitudeDegrees;
mHorizontalAccuracyMeters = l.mHorizontalAccuracyMeters;
mAltitudeMeters = l.mAltitudeMeters;
mAltitudeAccuracyMeters = l.mAltitudeAccuracyMeters;
mSpeedMetersPerSecond = l.mSpeedMetersPerSecond;
mSpeedAccuracyMetersPerSecond = l.mSpeedAccuracyMetersPerSecond;
mBearingDegrees = l.mBearingDegrees;
mBearingAccuracyDegrees = l.mBearingAccuracyDegrees;
mExtras = (l.mExtras == null) ? null : new Bundle(l.mExtras);
public void set(@NonNull Location location) {
mFieldsMask = location.mFieldsMask;
mProvider = location.mProvider;
mTimeMs = location.mTimeMs;
mElapsedRealtimeNs = location.mElapsedRealtimeNs;
mElapsedRealtimeUncertaintyNs = location.mElapsedRealtimeUncertaintyNs;
mLatitudeDegrees = location.mLatitudeDegrees;
mLongitudeDegrees = location.mLongitudeDegrees;
mHorizontalAccuracyMeters = location.mHorizontalAccuracyMeters;
mAltitudeMeters = location.mAltitudeMeters;
mAltitudeAccuracyMeters = location.mAltitudeAccuracyMeters;
mSpeedMetersPerSecond = location.mSpeedMetersPerSecond;
mSpeedAccuracyMetersPerSecond = location.mSpeedAccuracyMetersPerSecond;
mBearingDegrees = location.mBearingDegrees;
mBearingAccuracyDegrees = location.mBearingAccuracyDegrees;
mExtras = (location.mExtras == null) ? null : new Bundle(location.mExtras);
}
/**
@@ -182,14 +182,13 @@ public class Location implements Parcelable {
}
/**
* Returns the approximate distance in meters between this
* location and the given location. Distance is defined using
* the WGS84 ellipsoid.
* Returns the approximate distance in meters between this location and the given location.
* Distance is defined using the WGS84 ellipsoid.
*
* @param dest the destination location
* @return the approximate distance in meters
*/
public @FloatRange float distanceTo(@NonNull Location dest) {
public @FloatRange(from = 0.0) float distanceTo(@NonNull Location dest) {
BearingDistanceCache cache = sBearingDistanceCache.get();
// See if we already have the result
if (mLatitudeDegrees != cache.mLat1 || mLongitudeDegrees != cache.mLon1
@@ -201,11 +200,10 @@ public class Location implements Parcelable {
}
/**
* Returns the approximate initial bearing in degrees East of true
* North when traveling along the shortest path between this
* location and the given location. The shortest path is defined
* using the WGS84 ellipsoid. Locations that are (nearly)
* antipodal may produce meaningless results.
* Returns the approximate initial bearing in degrees east of true north when traveling along
* the shortest path between this location and the given location. The shortest path is defined
* using the WGS84 ellipsoid. Locations that are (nearly) antipodal may produce meaningless
* results.
*
* @param dest the destination location
* @return the initial bearing in degrees
@@ -254,7 +252,7 @@ public class Location implements Parcelable {
* not be used to order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that
* purpose, as the elapsed realtime clock is guaranteed to be monotonic.
*
* <p>On the other hand, this method may be useful for presenting a human readable time to the
* <p>On the other hand, this method may be useful for presenting a human-readable time to the
* user, or as a heuristic for comparing location fixes across reboot or across devices.
*
* <p>All locations generated by the {@link LocationManager} are guaranteed to have this time
@@ -263,25 +261,24 @@ public class Location implements Parcelable {
*
* @return the Unix epoch time of this location
*/
public @IntRange long getTime() {
public @IntRange(from = 0) long getTime() {
return mTimeMs;
}
/**
* Sets the Unix epoch time of this location fix, in milliseconds since the start of the Unix
* epoch (00:00:00 January 1, 1970 UTC).
* epoch (00:00:00 January 1 1970 UTC).
*
* @param timeMs the Unix epoch time of this location
* @see #getTime for more information about times / clocks
*/
public void setTime(@IntRange long timeMs) {
public void setTime(@IntRange(from = 0) long timeMs) {
mTimeMs = timeMs;
}
/**
* Return the time of this fix in nanoseconds of elapsed realtime since system boot.
*
* <p>This value can be compared with {@link android.os.SystemClock#elapsedRealtimeNanos}, to
* <p>This value can be compared with {@link android.os.SystemClock#elapsedRealtimeNanos} to
* reliably order or compare locations. This is reliable because elapsed realtime is guaranteed
* to be monotonic and continues to increment even when the system is in deep sleep (unlike
* {@link #getTime}). However, since elapsed realtime is with reference to system boot, it does
@@ -292,7 +289,7 @@ public class Location implements Parcelable {
*
* @return elapsed realtime of this location in nanoseconds
*/
public @IntRange long getElapsedRealtimeNanos() {
public @IntRange(from = 0) long getElapsedRealtimeNanos() {
return mElapsedRealtimeNs;
}
@@ -302,7 +299,7 @@ public class Location implements Parcelable {
* @return elapsed realtime of this location in milliseconds
* @see #getElapsedRealtimeNanos()
*/
public @IntRange long getElapsedRealtimeMillis() {
public @IntRange(from = 0) long getElapsedRealtimeMillis() {
return NANOSECONDS.toMillis(mElapsedRealtimeNs);
}
@@ -312,7 +309,7 @@ public class Location implements Parcelable {
*
* @return age of this location in milliseconds
*/
public @IntRange long getElapsedRealtimeAgeMillis() {
public @IntRange(from = 0) long getElapsedRealtimeAgeMillis() {
return getElapsedRealtimeAgeMillis(SystemClock.elapsedRealtime());
}
@@ -323,7 +320,8 @@ public class Location implements Parcelable {
* @param referenceRealtimeMs reference realtime in milliseconds
* @return age of this location in milliseconds
*/
public @IntRange long getElapsedRealtimeAgeMillis(@IntRange long referenceRealtimeMs) {
public long getElapsedRealtimeAgeMillis(
@IntRange(from = 0) long referenceRealtimeMs) {
return referenceRealtimeMs - getElapsedRealtimeMillis();
}
@@ -332,7 +330,7 @@ public class Location implements Parcelable {
*
* @param elapsedRealtimeNs elapsed realtime in nanoseconds
*/
public void setElapsedRealtimeNanos(@IntRange long elapsedRealtimeNs) {
public void setElapsedRealtimeNanos(@IntRange(from = 0) long elapsedRealtimeNs) {
mElapsedRealtimeNs = elapsedRealtimeNs;
}
@@ -346,7 +344,7 @@ public class Location implements Parcelable {
*
* @return uncertainty in nanoseconds of the elapsed realtime of this location
*/
public @FloatRange double getElapsedRealtimeUncertaintyNanos() {
public @FloatRange(from = 0.0) double getElapsedRealtimeUncertaintyNanos() {
return mElapsedRealtimeUncertaintyNs;
}
@@ -358,20 +356,20 @@ public class Location implements Parcelable {
* this location
*/
public void setElapsedRealtimeUncertaintyNanos(
@FloatRange double elapsedRealtimeUncertaintyNs) {
@FloatRange(from = 0.0) double elapsedRealtimeUncertaintyNs) {
mElapsedRealtimeUncertaintyNs = elapsedRealtimeUncertaintyNs;
mFieldsMask |= HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK;
}
/**
* True if this location has a elapsed realtime uncertainty, false otherwise.
* True if this location has an elapsed realtime uncertainty, false otherwise.
*/
public boolean hasElapsedRealtimeUncertaintyNanos() {
return (mFieldsMask & HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK) != 0;
}
/**
* Removes the elapsed realtime uncertainy from this location.
* Removes the elapsed realtime uncertainty from this location.
*/
public void removeElapsedRealtimeUncertaintyNanos() {
mFieldsMask &= ~HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK;
@@ -383,7 +381,7 @@ public class Location implements Parcelable {
*
* @return latitude of this location
*/
public @FloatRange double getLatitude() {
public @FloatRange(from = -90.0, to = 90.0) double getLatitude() {
return mLatitudeDegrees;
}
@@ -392,7 +390,7 @@ public class Location implements Parcelable {
*
* @param latitudeDegrees latitude in degrees
*/
public void setLatitude(@FloatRange double latitudeDegrees) {
public void setLatitude(@FloatRange(from = -90.0, to = 90.0) double latitudeDegrees) {
mLatitudeDegrees = latitudeDegrees;
}
@@ -402,7 +400,7 @@ public class Location implements Parcelable {
*
* @return longitude of this location
*/
public @FloatRange double getLongitude() {
public @FloatRange(from = -180.0, to = 180.0) double getLongitude() {
return mLongitudeDegrees;
}
@@ -411,7 +409,7 @@ public class Location implements Parcelable {
*
* @param longitudeDegrees longitude in degrees
*/
public void setLongitude(@FloatRange double longitudeDegrees) {
public void setLongitude(@FloatRange(from = -180.0, to = 180.0) double longitudeDegrees) {
mLongitudeDegrees = longitudeDegrees;
}
@@ -423,12 +421,12 @@ public class Location implements Parcelable {
* reported location, there is a 68% chance that the true location falls within this circle.
* This accuracy value is only valid for horizontal positioning, and not vertical positioning.
*
* <p>This is only valid if {@link #hasSpeed()} is true. All locations generated by the
* <p>This is only valid if {@link #hasAccuracy()} is true. All locations generated by the
* {@link LocationManager} include horizontal accuracy.
*
* @return horizontal accuracy of this location
*/
public @FloatRange float getAccuracy() {
public @FloatRange(from = 0.0) float getAccuracy() {
return mHorizontalAccuracyMeters;
}
@@ -437,7 +435,7 @@ public class Location implements Parcelable {
*
* @param horizontalAccuracyMeters horizontal altitude in meters
*/
public void setAccuracy(@FloatRange float horizontalAccuracyMeters) {
public void setAccuracy(@FloatRange(from = 0.0) float horizontalAccuracyMeters) {
mHorizontalAccuracyMeters = horizontalAccuracyMeters;
mFieldsMask |= HAS_HORIZONTAL_ACCURACY_MASK;
}
@@ -500,7 +498,7 @@ public class Location implements Parcelable {
*
* @return vertical accuracy of this location
*/
public @FloatRange float getVerticalAccuracyMeters() {
public @FloatRange(from = 0.0) float getVerticalAccuracyMeters() {
return mAltitudeAccuracyMeters;
}
@@ -509,7 +507,7 @@ public class Location implements Parcelable {
*
* @param altitudeAccuracyMeters altitude accuracy in meters
*/
public void setVerticalAccuracyMeters(@FloatRange float altitudeAccuracyMeters) {
public void setVerticalAccuracyMeters(@FloatRange(from = 0.0) float altitudeAccuracyMeters) {
mAltitudeAccuracyMeters = altitudeAccuracyMeters;
mFieldsMask |= HAS_ALTITUDE_ACCURACY_MASK;
}
@@ -538,17 +536,16 @@ public class Location implements Parcelable {
*
* @return speed at the time of this location
*/
public @FloatRange float getSpeed() {
public @FloatRange(from = 0.0) float getSpeed() {
return mSpeedMetersPerSecond;
}
/**
* Set the speed at the time of this location, in meters per second. Prefer not to set negative
* speeds.
* Set the speed at the time of this location, in meters per second.
*
* @param speedMetersPerSecond speed in meters per second
*/
public void setSpeed(@FloatRange float speedMetersPerSecond) {
public void setSpeed(@FloatRange(from = 0.0) float speedMetersPerSecond) {
mSpeedMetersPerSecond = speedMetersPerSecond;
mFieldsMask |= HAS_SPEED_MASK;
}
@@ -576,7 +573,7 @@ public class Location implements Parcelable {
*
* @return vertical accuracy of this location
*/
public @FloatRange float getSpeedAccuracyMetersPerSecond() {
public @FloatRange(from = 0.0) float getSpeedAccuracyMetersPerSecond() {
return mSpeedAccuracyMetersPerSecond;
}
@@ -585,7 +582,8 @@ public class Location implements Parcelable {
*
* @param speedAccuracyMeterPerSecond speed accuracy in meters per second
*/
public void setSpeedAccuracyMetersPerSecond(@FloatRange float speedAccuracyMeterPerSecond) {
public void setSpeedAccuracyMetersPerSecond(
@FloatRange(from = 0.0) float speedAccuracyMeterPerSecond) {
mSpeedAccuracyMetersPerSecond = speedAccuracyMeterPerSecond;
mFieldsMask |= HAS_SPEED_ACCURACY_MASK;
}
@@ -613,7 +611,7 @@ public class Location implements Parcelable {
*
* @return bearing at the time of this location
*/
public @FloatRange(from = 0f, to = 360f, toInclusive = false) float getBearing() {
public @FloatRange(from = 0.0, to = 360.0, toInclusive = false) float getBearing() {
return mBearingDegrees;
}
@@ -663,7 +661,7 @@ public class Location implements Parcelable {
*
* @return bearing accuracy in degrees of this location
*/
public @FloatRange float getBearingAccuracyDegrees() {
public @FloatRange(from = 0.0) float getBearingAccuracyDegrees() {
return mBearingAccuracyDegrees;
}
@@ -672,7 +670,7 @@ public class Location implements Parcelable {
*
* @param bearingAccuracyDegrees bearing accuracy in degrees
*/
public void setBearingAccuracyDegrees(@FloatRange float bearingAccuracyDegrees) {
public void setBearingAccuracyDegrees(@FloatRange(from = 0.0) float bearingAccuracyDegrees) {
mBearingAccuracyDegrees = bearingAccuracyDegrees;
mFieldsMask |= HAS_BEARING_ACCURACY_MASK;
}
@@ -692,9 +690,11 @@ public class Location implements Parcelable {
}
/**
* Returns true if the Location came from a mock provider.
* Returns true if this is a mock location. If this location comes from the Android framework,
* this indicates that the location was provided by a test location provider, and thus may not
* be related to the actual location of the device.
*
* @return true if this Location came from a mock provider, false otherwise
* @return true if this location came from a mock provider, false otherwise
* @deprecated Prefer {@link #isMock()} instead.
*/
@Deprecated
@@ -703,9 +703,9 @@ public class Location implements Parcelable {
}
/**
* Flag this Location as having come from a mock provider or not.
* Flag this location as having come from a mock provider or not.
*
* @param isFromMockProvider true if this Location came from a mock provider, false otherwise
* @param isFromMockProvider true if this location came from a mock provider, false otherwise
* @deprecated Prefer {@link #setMock(boolean)} instead.
* @hide
*/
@@ -745,7 +745,7 @@ public class Location implements Parcelable {
* will be present for any location.
*
* <ul>
* <li> satellites - the number of satellites used to derive the GNSS fix
* <li> satellites - the number of satellites used to derive a GNSS fix
* </ul>
*/
public @Nullable Bundle getExtras() {
@@ -899,7 +899,13 @@ public class Location implements Parcelable {
return s.toString();
}
/** Dumps location. */
/**
* Dumps location information to the given Printer.
*
* @deprecated Prefer to use {@link #toString()} along with whatever custom formatting is
* required instead of this method. It is not this class's job to manage print representations.
*/
@Deprecated
public void dump(@NonNull Printer pw, @Nullable String prefix) {
pw.println(prefix + this);
}
@@ -1209,10 +1215,10 @@ public class Location implements Parcelable {
* @throws IllegalArgumentException if results is null or has length < 1
*/
public static void distanceBetween(
@FloatRange double startLatitude,
@FloatRange double startLongitude,
@FloatRange double endLatitude,
@FloatRange double endLongitude,
@FloatRange(from = -90.0, to = 90.0) double startLatitude,
@FloatRange(from = -180.0, to = 180.0) double startLongitude,
@FloatRange(from = -90.0, to = 90.0) double endLatitude,
@FloatRange(from = -180.0, to = 180.0) double endLongitude,
float[] results) {
if (results == null || results.length < 1) {
throw new IllegalArgumentException("results is null or has length < 1");