diff options
| -rw-r--r-- | location/java/android/location/GnssClock.java | 4 | ||||
| -rw-r--r-- | location/java/android/location/Location.java | 31 | ||||
| -rw-r--r-- | location/java/android/location/OnNmeaMessageListener.java | 5 |
3 files changed, 21 insertions, 19 deletions
diff --git a/location/java/android/location/GnssClock.java b/location/java/android/location/GnssClock.java index ed4bf1b2d53e..62f50b57520c 100644 --- a/location/java/android/location/GnssClock.java +++ b/location/java/android/location/GnssClock.java @@ -23,9 +23,9 @@ import android.os.Parcel; import android.os.Parcelable; /** - * A class containing a GPS clock timestamp. + * A class containing a GNSS clock timestamp. * - * <p>It represents a measurement of the GPS receiver's clock. + * <p>It represents a measurement of the GNSS receiver's clock. */ public final class GnssClock implements Parcelable { // The following enumerations must be in sync with the values declared in gps.h diff --git a/location/java/android/location/Location.java b/location/java/android/location/Location.java index 1fcb194f2c6e..f1605f1ffe5d 100644 --- a/location/java/android/location/Location.java +++ b/location/java/android/location/Location.java @@ -45,8 +45,8 @@ import java.util.StringTokenizer; * timestamp, accuracy, and other information such as bearing, altitude and velocity. * * <p>All locations generated through {@link LocationManager} are guaranteed to have a valid - * latitude, longitude, timestamp (both UTC time and elapsed real-time since boot), and accuracy. - * All other parameters are optional. + * latitude, longitude, timestamp (both Unix epoch time and elapsed realtime since boot), and + * accuracy. All other parameters are optional. */ public class Location implements Parcelable { @@ -240,36 +240,39 @@ public class Location implements Parcelable { } /** - * Return the UTC time of this location fix, in milliseconds since epoch (January 1, 1970). + * Returns the Unix epoch time of this location fix, in milliseconds since the start of the Unix + * epoch (00:00:00 January 1, 1970 UTC). * * <p>There is no guarantee that different locations have times set from the same clock. * Locations derived from the {@link LocationManager#GPS_PROVIDER} are guaranteed to have their - * time set from the clock in use by the satellite constellation that provided the fix. + * time originate from the clock in use by the satellite constellation that provided the fix. * Locations derived from other providers may use any clock to set their time, though it is most - * common to use the device clock (which may be incorrect). + * common to use the device's Unix epoch time system clock (which may be incorrect). * - * <p>Note that the device clock UTC time is not monotonic; it can jump forwards or backwards - * unpredictably and may be changed at any time by the user, so this time should not be used to - * order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that purpose, as this - * clock is guaranteed to be monotonic. + * <p>Note that the device's Unix epoch time system clock is not monotonic; it can jump forwards + * or backwards unpredictably and may be changed at any time by the user, so this time should + * 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 * 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 a UTC time - * set, however remember that the device clock may have changed since the location was + * <p>All locations generated by the {@link LocationManager} are guaranteed to have this time + * set, however remember that the device's system clock may have changed since the location was * generated. * - * @return UTC time of this location + * @return the Unix epoch time of this location */ public @IntRange long getTime() { return mTimeMs; } /** - * Set the UTC time of this location, in milliseconds since epoch (January 1, 1970). + * 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). * - * @param timeMs UTC time of this location + * @param timeMs the Unix epoch time of this location + * @see #getTime for more information about times / clocks */ public void setTime(@IntRange long timeMs) { mTimeMs = timeMs; diff --git a/location/java/android/location/OnNmeaMessageListener.java b/location/java/android/location/OnNmeaMessageListener.java index 1c02ebd30d58..def688cacedc 100644 --- a/location/java/android/location/OnNmeaMessageListener.java +++ b/location/java/android/location/OnNmeaMessageListener.java @@ -31,9 +31,8 @@ public interface OnNmeaMessageListener { /** * Called when an NMEA message is received. * @param message NMEA message - * @param timestamp Date and time of the location fix, as reported by the GNSS - * chipset. The value is specified in milliseconds since 0:00 - * UTC 1 January 1970. + * @param timestamp Timestamp of the location fix, as reported by the GNSS chipset. The value + * is specified in Unix time milliseconds since 1st January 1970, 00:00:00 UTC */ void onNmeaMessage(String message, long timestamp); } |