Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 490d480a authored by Neil Fuller's avatar Neil Fuller
Browse files

Switch "UTC time" to "Unix epoch time" (Location) 

This is more correct. Android devices, even under ideal conditions,
don't track UTC (which contains leap seconds and uses the SI definition
of a second) but use a clock based on Unix epoch time (no leap seconds,
but clocks may skip/stop or smear around leap seconds to ensure a fixed
number of second increments per calendar day when leap seconds are
applied to UTC).

Bug: 218802673
Test: Compile only
Change-Id: If87023af06ba9933f96029e52df9cb3841bca0cb
parent 115132db

location/java/android/location/GnssClock.java

+2 −2
Original line number Diff line number Diff line
@@ -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

location/java/android/location/Location.java

+17 −14
Original line number Diff line number Diff line
@@ -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;

location/java/android/location/OnNmeaMessageListener.java

+2 −3
Original line number Diff line number Diff line
@@ -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);

}