Merge "Update Location APIs per feedback" into tm-dev am: 7017bb3cd5 (2fb3873b) · Commits · e / os / android_frameworks_base

core/api/current.txt

+27 −27

Original line number	Diff line number	Diff line
		@@ -19487,26 +19487,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();
		@@ -19528,21 +19528,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

location/java/android/location/Location.java

+77 −71

Original line number	Diff line number	Diff line
		@@ -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");