Update GpsMeasurements APIs to reflect changes in GPS HAL.

b/19938206

All new introduced APIs are hidden.

GpsMeasurement#isPseudorangeRateCorrected() is need to properly identify different types
of data provided by different partners. Given the nature of each GPS engine, this change is
required to accomodate the data that can be provided by many partners.
GpsNavigationMessage#getStatus() is required to ensure that the Location process is aware
if the state of the messages, and can act depending on it.

Change-Id: Ie34b1e69bf26a1bde86931ce61168421429bf8f8

2 files changed, 116 insertions, 3 deletions

diff --git a/location/java/android/location/GpsMeasurement.java b/location/java/android/location/GpsMeasurement.java
index 05bcf79..df128c9 100644
--- a/location/java/android/location/GpsMeasurement.java
+++ b/location/java/android/location/GpsMeasurement.java
@@ -80,6 +80,8 @@ public class GpsMeasurement implements Parcelable {
     private static final int HAS_TIME_FROM_LAST_BIT = (1<<14);
     private static final int HAS_DOPPLER_SHIFT = (1<<15);
     private static final int HAS_DOPPLER_SHIFT_UNCERTAINTY = (1<<16);
+    private static final int HAS_USED_IN_FIX = (1<<17);
+    private static final int GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE = (1<<18);
 
     /**
      * The indicator is not available or it is unknown.
@@ -137,10 +139,17 @@ public class GpsMeasurement implements Parcelable {
     public static final short STATE_TOW_DECODED = (1<<3);
 
     /**
+     * The state of the GPS receiver contains millisecond ambiguity.
+     *
+     * @hide
+     */
+    public static final short STATE_MSEC_AMBIGUOUS = (1<<4);
+
+    /**
      * All the GPS receiver state flags.
      */
-    private static final short STATE_ALL =
-            STATE_CODE_LOCK | STATE_BIT_SYNC | STATE_SUBFRAME_SYNC | STATE_TOW_DECODED;
+    private static final short STATE_ALL = STATE_CODE_LOCK | STATE_BIT_SYNC | STATE_SUBFRAME_SYNC
+            | STATE_TOW_DECODED | STATE_MSEC_AMBIGUOUS;
 
     /**
      * The state of the 'Accumulated Delta Range' is invalid or unknown.
@@ -295,6 +304,9 @@ public class GpsMeasurement implements Parcelable {
         if ((mState & STATE_TOW_DECODED) == STATE_TOW_DECODED) {
             builder.append("TowDecoded|");
         }
+        if ((mState & STATE_MSEC_AMBIGUOUS) == STATE_MSEC_AMBIGUOUS) {
+            builder.append("MsecAmbiguous");
+        }
         int remainingStates = mState & ~STATE_ALL;
         if (remainingStates > 0) {
             builder.append("Other(");
@@ -361,6 +373,15 @@ public class GpsMeasurement implements Parcelable {
     /**
      * Gets the Pseudorange rate at the timestamp in m/s.
      * The reported value includes {@link #getPseudorangeRateUncertaintyInMetersPerSec()}.
+     *
+     * The correction of a given Pseudorange Rate value includes corrections from receiver and
+     * satellite clock frequency errors.
+     * {@link #isPseudorangeRateCorrected()} identifies the type of value reported.
+     *
+     * A positive 'uncorrected' value indicates that the SV is moving away from the receiver.
+     * The sign of the 'uncorrected' Pseudorange Rate and its relation to the sign of
+     * {@link #getDopplerShiftInHz()} is given by the equation:
+     *      pseudorange rate = -k * doppler shift   (where k is a constant)
      */
     public double getPseudorangeRateInMetersPerSec() {
         return mPseudorangeRateInMetersPerSec;
@@ -374,6 +395,18 @@ public class GpsMeasurement implements Parcelable {
     }
 
     /**
+     * See {@link #getPseudorangeRateInMetersPerSec()} for more details.
+     *
+     * @return {@code true} if {@link #getPseudorangeRateInMetersPerSec()} contains a corrected
+     *         value, {@code false} if it contains an uncorrected value.
+     *
+     * @hide
+     */
+    public boolean isPseudorangeRateCorrected() {
+        return !isFlagSet(GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE);
+    }
+
+    /**
      * Gets the pseudorange's rate uncertainty (1-Sigma) in m/s.
      * The uncertainty is represented as an absolute (single sided) value.
      */
@@ -437,6 +470,11 @@ public class GpsMeasurement implements Parcelable {
      * The reported value includes {@link #getAccumulatedDeltaRangeUncertaintyInMeters()}.
      *
      * The availability of the value is represented by {@link #getAccumulatedDeltaRangeState()}.
+     *
+     * A positive value indicates that the SV is moving away from the receiver.
+     * The sign of {@link #getAccumulatedDeltaRangeInMeters()} and its relation to the sign of
+     * {@link #getCarrierPhase()} is given by the equation:
+     *          accumulated delta range = -k * carrier phase    (where k is a constant)
      */
     public double getAccumulatedDeltaRangeInMeters() {
         return mAccumulatedDeltaRangeInMeters;
@@ -452,6 +490,8 @@ public class GpsMeasurement implements Parcelable {
     /**
      * Gets the accumulated delta range's uncertainty (1-Sigma) in meters.
      * The uncertainty is represented as an absolute (single sided) value.
+     *
+     * The status of the value is represented by {@link #getAccumulatedDeltaRangeState()}.
      */
     public double getAccumulatedDeltaRangeUncertaintyInMeters() {
         return mAccumulatedDeltaRangeUncertaintyInMeters;
@@ -460,7 +500,7 @@ public class GpsMeasurement implements Parcelable {
     /**
      * Sets the accumulated delta range's uncertainty (1-sigma) in meters.
      *
-     * The availability of the value is represented by {@link #getAccumulatedDeltaRangeState()}.
+     * The status of the value is represented by {@link #getAccumulatedDeltaRangeState()}.
      */
     public void setAccumulatedDeltaRangeUncertaintyInMeters(double value) {
         mAccumulatedDeltaRangeUncertaintyInMeters = value;
@@ -1235,6 +1275,10 @@ public class GpsMeasurement implements Parcelable {
                 mPseudorangeRateInMetersPerSec,
                 "PseudorangeRateUncertaintyInMetersPerSec",
                 mPseudorangeRateUncertaintyInMetersPerSec));
+        builder.append(String.format(
+                format,
+                "PseudorangeRateIsCorrected",
+                isPseudorangeRateCorrected()));
 
         builder.append(String.format(
                 format,
diff --git a/location/java/android/location/GpsNavigationMessage.java b/location/java/android/location/GpsNavigationMessage.java
index b893f3f..5b12a61 100644
--- a/location/java/android/location/GpsNavigationMessage.java
+++ b/location/java/android/location/GpsNavigationMessage.java
@@ -60,6 +60,28 @@ public class GpsNavigationMessage implements Parcelable {
      */
     public static final byte TYPE_CNAV2 = 4;
 
+    /**
+     * The Navigation Message Status is 'unknown'.
+     *
+     * @hide
+     */
+    public static final short STATUS_UNKNOWN = 0;
+
+    /**
+     * The Navigation Message was received without any parity error in its navigation words.
+     *
+     * @hide
+     */
+    public static final short STATUS_PARITY_PASSED = (1<<0);
+
+    /**
+     * The Navigation Message was received with words that failed parity check, but the receiver was
+     * able to correct those words.
+     *
+     * @hide
+     */
+    public static final short STATUS_PARITY_REBUILT = (1<<1);
+
     // End enumerations in sync with gps.h
 
     private byte mType;
@@ -67,6 +89,7 @@ public class GpsNavigationMessage implements Parcelable {
     private short mMessageId;
     private short mSubmessageId;
     private byte[] mData;
+    private short mStatus;
 
     GpsNavigationMessage() {
         initialize();
@@ -81,6 +104,7 @@ public class GpsNavigationMessage implements Parcelable {
         mMessageId = navigationMessage.mMessageId;
         mSubmessageId = navigationMessage.mSubmessageId;
         mData = navigationMessage.mData;
+        mStatus = navigationMessage.mStatus;
     }
 
     /**
@@ -194,6 +218,41 @@ public class GpsNavigationMessage implements Parcelable {
         mData = value;
     }
 
+    /**
+     * Gets the Status of the navigation message contained in the object.
+     *
+     * @hide
+     */
+    public short getStatus() {
+        return mStatus;
+    }
+
+    /**
+     * Sets the status of the navigation message.
+     *
+     * @hide
+     */
+    public void setStatus(short value) {
+        mStatus = value;
+    }
+
+    /**
+     * Gets a string representation of the 'status'.
+     * For internal and logging use only.
+     */
+    private String getStatusString() {
+        switch (mStatus) {
+            case STATUS_UNKNOWN:
+                return "Unknown";
+            case STATUS_PARITY_PASSED:
+                return "ParityPassed";
+            case STATUS_PARITY_REBUILT:
+                return "ParityRebuilt";
+            default:
+                return "<Invalid:" + mStatus + ">";
+        }
+    }
+
     public static final Creator<GpsNavigationMessage> CREATOR =
             new Creator<GpsNavigationMessage>() {
         @Override
@@ -210,6 +269,13 @@ public class GpsNavigationMessage implements Parcelable {
             parcel.readByteArray(data);
             navigationMessage.setData(data);
 
+            if (parcel.dataAvail() >= Integer.SIZE) {
+                int status = parcel.readInt();
+                navigationMessage.setStatus((short) status);
+            } else {
+                navigationMessage.setStatus(STATUS_UNKNOWN);
+            }
+
             return navigationMessage;
         }
 
@@ -226,6 +292,7 @@ public class GpsNavigationMessage implements Parcelable {
         parcel.writeInt(mSubmessageId);
         parcel.writeInt(mData.length);
         parcel.writeByteArray(mData);
+        parcel.writeInt(mStatus);
     }
 
     @Override
@@ -240,6 +307,7 @@ public class GpsNavigationMessage implements Parcelable {
 
         builder.append(String.format(format, "Type", getTypeString()));
         builder.append(String.format(format, "Prn", mPrn));
+        builder.append(String.format(format, "Status", getStatusString()));
         builder.append(String.format(format, "MessageId", mMessageId));
         builder.append(String.format(format, "SubmessageId", mSubmessageId));
 
@@ -261,5 +329,6 @@ public class GpsNavigationMessage implements Parcelable {
         mMessageId = -1;
         mSubmessageId = -1;
         mData = EMPTY_ARRAY;
+        mStatus = STATUS_UNKNOWN;
     }
 }