From 699e4549eeffd8f1445ead26db39c9951bd35d6d Mon Sep 17 00:00:00 2001
From: Yu-Han Yang <yuhany@google.com>
Date: Mon, 27 Jan 2020 14:22:06 -0800
Subject: Add comments to messageId, subMessageId and data

Bug: 147768625

Test: doc only and builds
Change-Id: I4b62e00e6b3c051342b41ade6254aef2d7560b07
---
 .../android/location/GnssNavigationMessage.java    | 43 ++++++++++++++++++++--
 1 file changed, 39 insertions(+), 4 deletions(-)

(limited to 'location/java')

diff --git a/location/java/android/location/GnssNavigationMessage.java b/location/java/android/location/GnssNavigationMessage.java
index ca0bfb1added..aade5ac63317 100644
--- a/location/java/android/location/GnssNavigationMessage.java
+++ b/location/java/android/location/GnssNavigationMessage.java
@@ -17,6 +17,7 @@
 package android.location;
 
 import android.annotation.IntDef;
+import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.TestApi;
 import android.os.Parcel;
@@ -76,6 +77,14 @@ public final class GnssNavigationMessage implements Parcelable {
     /** IRNSS L5 C/A message contained in the structure. */
     public static final int TYPE_IRN_L5CA = 0x0701;
 
+    /**
+     * The status of the GNSS Navigation Message
+     * @hide
+     */
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef({STATUS_UNKNOWN, STATUS_PARITY_PASSED, STATUS_PARITY_REBUILT})
+    public @interface GnssNavigationMessageStatus {}
+
     /**
      * The Navigation Message Status is 'unknown'.
      */
@@ -240,6 +249,7 @@ public final class GnssNavigationMessage implements Parcelable {
      *
      * <p>Range varies by constellation.  See definition at {@code GnssStatus#getSvid(int)}
      */
+    @IntRange(from = 1, to = 200)
     public int getSvid() {
         return mSvid;
     }
@@ -249,7 +259,7 @@ public final class GnssNavigationMessage implements Parcelable {
      * @hide
      */
     @TestApi
-    public void setSvid(int value) {
+    public void setSvid(@IntRange(from = 1, to = 200) int value) {
         mSvid = value;
     }
 
@@ -272,8 +282,17 @@ public final class GnssNavigationMessage implements Parcelable {
      * range of 1-12</li>
      * <li> For Galileo I/NAV nominal frame structure, this refers to the subframe number in the
      * range of 1-24</li>
+     * <li> For SBAS and Beidou CNAV2, this is unused and can be set to -1.</li>
+     * <li> For QZSS L1 C/A subframe 4 and 5, this value corresponds to the 'frame id' of the
+     * navigation message, in the range of 1-25 (Subframe 1, 2, 3 does not contain a 'frame id' and
+     * this value can be set to -1.)</li>
+     * <li> For Beidou CNAV1 this refers to the page type number in the range of 1-63.</li>
+     * <li> For IRNSS L5 C/A subframe 3 and 4, this value corresponds to the Message Id of the
+     * navigation message, in the range of 1-63. (Subframe 1 and 2 does not contain a message type
+     * id and this value can be set to -1.)</li>
      * </ul>
      */
+    @IntRange(from = -1, to = 120)
     public int getMessageId() {
         return mMessageId;
     }
@@ -283,7 +302,7 @@ public final class GnssNavigationMessage implements Parcelable {
      * @hide
      */
     @TestApi
-    public void setMessageId(int value) {
+    public void setMessageId(@IntRange(from = -1, to = 120) int value) {
         mMessageId = value;
     }
 
@@ -299,8 +318,16 @@ public final class GnssNavigationMessage implements Parcelable {
      * <li>For Galileo in particular, the type information embedded within the data bits may be even
      * more useful in interpretation, than the nominal page and word types provided in this
      * field.</li>
+     * <li> For SBAS, the submessage id corresponds to the message type, in the range 1-63.</li>
+     * <li> For Beidou CNAV1, the submessage id corresponds to the subframe number of the
+     * navigation message, in the range of 1-3.</li>
+     * <li> For Beidou CNAV2, the submessage id corresponds to the message type, in the range
+     * 1-63.</li>
+     * <li> For IRNSS L5 C/A, the submessage id corresponds to the subframe number of the
+     * navigation message, in the range of 1-4.</li>
      * </ul>
      */
+    @IntRange(from = 1)
     public int getSubmessageId() {
         return mSubmessageId;
     }
@@ -310,7 +337,7 @@ public final class GnssNavigationMessage implements Parcelable {
      * @hide
      */
     @TestApi
-    public void setSubmessageId(int value) {
+    public void setSubmessageId(@IntRange(from = 1) int value) {
         mSubmessageId = value;
     }
 
@@ -333,6 +360,13 @@ public final class GnssNavigationMessage implements Parcelable {
      * <li>For Galileo I/NAV, each page contains 2 page parts, even and odd, with a total of 2x114 =
      * 228 bits, (sync &amp; tail excluded) that should be fit into 29 bytes, with MSB first (skip
      * B229-B232).</li>
+     * <li>For SBAS, each block consists of 250 data bits, that should be fit into 32 bytes.  MSB
+     * first (skip B251-B256).</li>
+     * <li>For Beidou CNAV1, subframe #1 consists of 14 data bits, that should be fit into 2
+     * bytes. MSB first (skip B15-B16).  subframe #2 consists of 600 bits that should be fit into
+     * 75 bytes. subframe #3 consists of 264 data bits that should be fit into 33 bytes.</li>
+     * <li>For Beidou CNAV2, each subframe consists of 288 data bits, that should be fit into 36
+     * bytes.</li>
      * </ul>
      */
     @NonNull
@@ -356,6 +390,7 @@ public final class GnssNavigationMessage implements Parcelable {
     /**
      * Gets the Status of the navigation message contained in the object.
      */
+    @GnssNavigationMessageStatus
     public int getStatus() {
         return mStatus;
     }
@@ -365,7 +400,7 @@ public final class GnssNavigationMessage implements Parcelable {
      * @hide
      */
     @TestApi
-    public void setStatus(int value) {
+    public void setStatus(@GnssNavigationMessageStatus int value) {
         mStatus = value;
     }
 
-- 
cgit v1.2.3-59-g8ed1b