Merge changes from topics "rtt_error_codes", "rtt_use_mm"

* changes:
  [RTT2] Error code reconfiguration
  [RTT2] Ranging results CM -> MM

5 files changed, 120 insertions, 79 deletions

diff --git a/wifi/java/android/net/wifi/rtt/IRttCallback.aidl b/wifi/java/android/net/wifi/rtt/IRttCallback.aidl
index fb1636f87297..578dd1e94997 100644
--- a/wifi/java/android/net/wifi/rtt/IRttCallback.aidl
+++ b/wifi/java/android/net/wifi/rtt/IRttCallback.aidl
@@ -26,7 +26,12 @@ import android.net.wifi.rtt.RangingResult;
 oneway interface IRttCallback
 {
     /**
-     * Service to manager callback providing RTT status and results.
+     * Service to manager callback indicating failure.
      */
-    void onRangingResults(int status, in List<RangingResult> results);
+    void onRangingFailure(int status);
+
+    /**
+     * Service to manager callback indicating success and providing results.
+     */
+    void onRangingResults(in List<RangingResult> results);
 }
diff --git a/wifi/java/android/net/wifi/rtt/RangingResult.java b/wifi/java/android/net/wifi/rtt/RangingResult.java
index 26903dd9d1b8..93e52aeb1273 100644
--- a/wifi/java/android/net/wifi/rtt/RangingResult.java
+++ b/wifi/java/android/net/wifi/rtt/RangingResult.java
@@ -16,14 +16,16 @@
 
 package android.net.wifi.rtt;
 
+import android.annotation.IntDef;
 import android.net.wifi.aware.PeerHandle;
 import android.os.Handler;
 import android.os.Parcel;
 import android.os.Parcelable;
-import android.util.Log;
 
 import libcore.util.HexEncoding;
 
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
@@ -41,42 +43,61 @@ import java.util.Objects;
 public final class RangingResult implements Parcelable {
     private static final String TAG = "RangingResult";
 
+    /** @hide */
+    @IntDef({STATUS_SUCCESS, STATUS_FAIL})
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface RangeResultStatus {
+    }
+
+    /**
+     * Individual range request status, {@link #getStatus()}. Indicates ranging operation was
+     * successful and distance value is valid.
+     */
+    public static final int STATUS_SUCCESS = 0;
+
+    /**
+     * Individual range request status, {@link #getStatus()}. Indicates ranging operation failed
+     * and the distance value is invalid.
+     */
+    public static final int STATUS_FAIL = 1;
+
     private final int mStatus;
     private final byte[] mMac;
     private final PeerHandle mPeerHandle;
-    private final int mDistanceCm;
-    private final int mDistanceStdDevCm;
+    private final int mDistanceMm;
+    private final int mDistanceStdDevMm;
     private final int mRssi;
     private final long mTimestamp;
 
     /** @hide */
-    public RangingResult(int status, byte[] mac, int distanceCm, int distanceStdDevCm, int rssi,
-            long timestamp) {
+    public RangingResult(@RangeResultStatus int status, byte[] mac, int distanceMm,
+            int distanceStdDevMm, int rssi, long timestamp) {
         mStatus = status;
         mMac = mac;
         mPeerHandle = null;
-        mDistanceCm = distanceCm;
-        mDistanceStdDevCm = distanceStdDevCm;
+        mDistanceMm = distanceMm;
+        mDistanceStdDevMm = distanceStdDevMm;
         mRssi = rssi;
         mTimestamp = timestamp;
     }
 
     /** @hide */
-    public RangingResult(int status, PeerHandle peerHandle, int distanceCm, int distanceStdDevCm,
-            int rssi, long timestamp) {
+    public RangingResult(@RangeResultStatus int status, PeerHandle peerHandle, int distanceMm,
+            int distanceStdDevMm, int rssi, long timestamp) {
         mStatus = status;
         mMac = null;
         mPeerHandle = peerHandle;
-        mDistanceCm = distanceCm;
-        mDistanceStdDevCm = distanceStdDevCm;
+        mDistanceMm = distanceMm;
+        mDistanceStdDevMm = distanceStdDevMm;
         mRssi = rssi;
         mTimestamp = timestamp;
     }
 
     /**
-     * @return The status of ranging measurement: {@link RangingResultCallback#STATUS_SUCCESS} in
-     * case of success, and {@link RangingResultCallback#STATUS_FAIL} in case of failure.
+     * @return The status of ranging measurement: {@link #STATUS_SUCCESS} in case of success, and
+     * {@link #STATUS_FAIL} in case of failure.
      */
+    @RangeResultStatus
     public int getStatus() {
         return mStatus;
     }
@@ -87,8 +108,6 @@ public final class RangingResult implements Parcelable {
      * <p>
      * Will return a {@code null} for results corresponding to requests issued using a {@code
      * PeerHandle}, i.e. using the {@link RangingRequest.Builder#addWifiAwarePeer(PeerHandle)} API.
-     * <p>
-     * Valid whether {@link #getStatus()} is SUCCESS or FAIL.
      */
     public byte[] getMacAddress() {
         return mMac;
@@ -100,49 +119,52 @@ public final class RangingResult implements Parcelable {
      * {@link RangingRequest.Builder#addWifiAwarePeer(PeerHandle)}.
      * <p>
      * Will return a {@code null} for results corresponding to requests issued using a MAC address.
-     * <p>
-     *
-     * Valid whether {@link #getStatus()} is SUCCESS or FAIL.
      */
     public PeerHandle getPeerHandle() {
         return mPeerHandle;
     }
 
     /**
-     * @return The distance (in cm) to the device specified by {@link #getMacAddress()}.
+     * @return The distance (in mm) to the device specified by {@link #getMacAddress()} or
+     * {@link #getPeerHandle()}.
      * <p>
-     * Only valid if {@link #getStatus()} returns {@link RangingResultCallback#STATUS_SUCCESS}.
+     * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
+     * exception.
      */
-    public int getDistanceCm() {
-        if (mStatus != RangingResultCallback.STATUS_SUCCESS) {
-            Log.e(TAG, "getDistanceCm(): invalid value retrieved");
+    public int getDistanceMm() {
+        if (mStatus != STATUS_SUCCESS) {
+            throw new IllegalStateException(
+                    "getDistanceMm(): invoked on an invalid result: getStatus()=" + mStatus);
         }
-        return mDistanceCm;
+        return mDistanceMm;
     }
 
     /**
-     * @return The standard deviation of the measured distance (in cm) to the device specified by
-     * {@link #getMacAddress()}. The standard deviation is calculated over the measurements
-     * executed in a single RTT burst.
+     * @return The standard deviation of the measured distance (in mm) to the device specified by
+     * {@link #getMacAddress()} or {@link #getPeerHandle()}. The standard deviation is calculated
+     * over the measurements executed in a single RTT burst.
      * <p>
-     * Only valid if {@link #getStatus()} returns {@link RangingResultCallback#STATUS_SUCCESS}.
+     * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
+     * exception.
      */
-    public int getDistanceStdDevCm() {
-        if (mStatus != RangingResultCallback.STATUS_SUCCESS) {
-            Log.e(TAG, "getDistanceStdDevCm(): invalid value retrieved");
+    public int getDistanceStdDevMm() {
+        if (mStatus != STATUS_SUCCESS) {
+            throw new IllegalStateException(
+                    "getDistanceStdDevMm(): invoked on an invalid result: getStatus()=" + mStatus);
         }
-        return mDistanceStdDevCm;
+        return mDistanceStdDevMm;
     }
 
     /**
      * @return The average RSSI (in units of -0.5dB) observed during the RTT measurement.
      * <p>
-     * Only valid if {@link #getStatus()} returns {@link RangingResultCallback#STATUS_SUCCESS}.
+     * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
+     * exception.
      */
     public int getRssi() {
-        if (mStatus != RangingResultCallback.STATUS_SUCCESS) {
-            // TODO: should this be an exception?
-            Log.e(TAG, "getRssi(): invalid value retrieved");
+        if (mStatus != STATUS_SUCCESS) {
+            throw new IllegalStateException(
+                    "getRssi(): invoked on an invalid result: getStatus()=" + mStatus);
         }
         return mRssi;
     }
@@ -150,9 +172,14 @@ public final class RangingResult implements Parcelable {
     /**
      * @return The timestamp, in us since boot, at which the ranging operation was performed.
      * <p>
-     * Only valid if {@link #getStatus()} returns {@link RangingResultCallback#STATUS_SUCCESS}.
+     * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
+     * exception.
      */
     public long getRangingTimestampUs() {
+        if (mStatus != STATUS_SUCCESS) {
+            throw new IllegalStateException(
+                    "getRangingTimestamp(): invoked on an invalid result: getStatus()=" + mStatus);
+        }
         return mTimestamp;
     }
 
@@ -173,8 +200,8 @@ public final class RangingResult implements Parcelable {
             dest.writeBoolean(true);
             dest.writeInt(mPeerHandle.peerId);
         }
-        dest.writeInt(mDistanceCm);
-        dest.writeInt(mDistanceStdDevCm);
+        dest.writeInt(mDistanceMm);
+        dest.writeInt(mDistanceStdDevMm);
         dest.writeInt(mRssi);
         dest.writeLong(mTimestamp);
     }
@@ -195,15 +222,15 @@ public final class RangingResult implements Parcelable {
             if (peerHandlePresent) {
                 peerHandle = new PeerHandle(in.readInt());
             }
-            int distanceCm = in.readInt();
-            int distanceStdDevCm = in.readInt();
+            int distanceMm = in.readInt();
+            int distanceStdDevMm = in.readInt();
             int rssi = in.readInt();
             long timestamp = in.readLong();
             if (peerHandlePresent) {
-                return new RangingResult(status, peerHandle, distanceCm, distanceStdDevCm, rssi,
+                return new RangingResult(status, peerHandle, distanceMm, distanceStdDevMm, rssi,
                         timestamp);
             } else {
-                return new RangingResult(status, mac, distanceCm, distanceStdDevCm, rssi,
+                return new RangingResult(status, mac, distanceMm, distanceStdDevMm, rssi,
                         timestamp);
             }
         }
@@ -215,8 +242,8 @@ public final class RangingResult implements Parcelable {
         return new StringBuilder("RangingResult: [status=").append(mStatus).append(", mac=").append(
                 mMac == null ? "<null>" : new String(HexEncoding.encodeToString(mMac))).append(
                 ", peerHandle=").append(mPeerHandle == null ? "<null>" : mPeerHandle.peerId).append(
-                ", distanceCm=").append(mDistanceCm).append(", distanceStdDevCm=").append(
-                mDistanceStdDevCm).append(", rssi=").append(mRssi).append(", timestamp=").append(
+                ", distanceMm=").append(mDistanceMm).append(", distanceStdDevMm=").append(
+                mDistanceStdDevMm).append(", rssi=").append(mRssi).append(", timestamp=").append(
                 mTimestamp).append("]").toString();
     }
 
@@ -233,14 +260,14 @@ public final class RangingResult implements Parcelable {
         RangingResult lhs = (RangingResult) o;
 
         return mStatus == lhs.mStatus && Arrays.equals(mMac, lhs.mMac) && Objects.equals(
-                mPeerHandle, lhs.mPeerHandle) && mDistanceCm == lhs.mDistanceCm
-                && mDistanceStdDevCm == lhs.mDistanceStdDevCm && mRssi == lhs.mRssi
+                mPeerHandle, lhs.mPeerHandle) && mDistanceMm == lhs.mDistanceMm
+                && mDistanceStdDevMm == lhs.mDistanceStdDevMm && mRssi == lhs.mRssi
                 && mTimestamp == lhs.mTimestamp;
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mStatus, mMac, mPeerHandle, mDistanceCm, mDistanceStdDevCm, mRssi,
+        return Objects.hash(mStatus, mMac, mPeerHandle, mDistanceMm, mDistanceStdDevMm, mRssi,
                 mTimestamp);
     }
-}
\ No newline at end of file
+}
diff --git a/wifi/java/android/net/wifi/rtt/RangingResultCallback.java b/wifi/java/android/net/wifi/rtt/RangingResultCallback.java
index d7270ad29a84..7405e82e2f5c 100644
--- a/wifi/java/android/net/wifi/rtt/RangingResultCallback.java
+++ b/wifi/java/android/net/wifi/rtt/RangingResultCallback.java
@@ -16,35 +16,43 @@
 
 package android.net.wifi.rtt;
 
+import android.annotation.IntDef;
 import android.os.Handler;
 
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.util.List;
 
 /**
  * Base class for ranging result callbacks. Should be extended by applications and set when calling
- * {@link WifiRttManager#startRanging(RangingRequest, RangingResultCallback, Handler)}. A single
- * result from a range request will be called in this object.
+ * {@link WifiRttManager#startRanging(RangingRequest, RangingResultCallback, Handler)}. If the
+ * ranging operation fails in whole (not attempted) then {@link #onRangingFailure(int)} will be
+ * called with a failure code. If the ranging operation is performed for each of the requested
+ * peers then the {@link #onRangingResults(List)} will be called with the set of results (@link
+ * {@link RangingResult}, each of which has its own success/failure code
+ * {@link RangingResult#getStatus()}.
  *
  * @hide RTT_API
  */
 public abstract class RangingResultCallback {
-    /**
-     * Individual range request status, {@link RangingResult#getStatus()}. Indicates ranging
-     * operation was successful and distance value is valid.
-     */
-    public static final int STATUS_SUCCESS = 0;
+    /** @hide */
+    @IntDef({STATUS_CODE_FAIL})
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface RangingOperationStatus {
+    }
 
     /**
-     * Individual range request status, {@link RangingResult#getStatus()}. Indicates ranging
-     * operation failed and the distance value is invalid.
+     * A failure code for the whole ranging request operation. Indicates a failure.
      */
-    public static final int STATUS_FAIL = 1;
+    public static final int STATUS_CODE_FAIL = 1;
 
     /**
      * Called when a ranging operation failed in whole - i.e. no ranging operation to any of the
      * devices specified in the request was attempted.
+     *
+     * @param code A status code indicating the type of failure.
      */
-    public abstract void onRangingFailure();
+    public abstract void onRangingFailure(@RangingOperationStatus int code);
 
     /**
      * Called when a ranging operation was executed. The list of results corresponds to devices
diff --git a/wifi/java/android/net/wifi/rtt/WifiRttManager.java b/wifi/java/android/net/wifi/rtt/WifiRttManager.java
index a085de17c035..435bb377043a 100644
--- a/wifi/java/android/net/wifi/rtt/WifiRttManager.java
+++ b/wifi/java/android/net/wifi/rtt/WifiRttManager.java
@@ -83,17 +83,18 @@ public class WifiRttManager {
         }
 
         @Override
-        public void onRangingResults(int status, List<RangingResult> results) throws RemoteException {
-            if (VDBG) {
-                Log.v(TAG, "RttCallbackProxy: onRanginResults: status=" + status + ", results="
-                        + results);
-            }
+        public void onRangingFailure(int status) throws RemoteException {
+            if (VDBG) Log.v(TAG, "RttCallbackProxy: onRangingFailure: status=" + status);
             mHandler.post(() -> {
-               if (status == RangingResultCallback.STATUS_SUCCESS) {
-                   mCallback.onRangingResults(results);
-               } else {
-                   mCallback.onRangingFailure();
-               }
+               mCallback.onRangingFailure(status);
+            });
+        }
+
+        @Override
+        public void onRangingResults(List<RangingResult> results) throws RemoteException {
+            if (VDBG) Log.v(TAG, "RttCallbackProxy: onRanginResults: results=" + results);
+            mHandler.post(() -> {
+               mCallback.onRangingResults(results);
             });
         }
     }
diff --git a/wifi/tests/src/android/net/wifi/rtt/WifiRttManagerTest.java b/wifi/tests/src/android/net/wifi/rtt/WifiRttManagerTest.java
index ea55a9dcfc63..33bd9828fb1b 100644
--- a/wifi/tests/src/android/net/wifi/rtt/WifiRttManagerTest.java
+++ b/wifi/tests/src/android/net/wifi/rtt/WifiRttManagerTest.java
@@ -79,9 +79,7 @@ public class WifiRttManagerTest {
     public void testRangeSuccess() throws Exception {
         RangingRequest request = new RangingRequest.Builder().build();
         List<RangingResult> results = new ArrayList<>();
-        results.add(
-                new RangingResult(RangingResultCallback.STATUS_SUCCESS, (byte[]) null, 15, 5, 10,
-                        666));
+        results.add(new RangingResult(RangingResult.STATUS_SUCCESS, (byte[]) null, 15, 5, 10, 666));
         RangingResultCallback callbackMock = mock(RangingResultCallback.class);
         ArgumentCaptor<IRttCallback> callbackCaptor = ArgumentCaptor.forClass(IRttCallback.class);
 
@@ -91,7 +89,7 @@ public class WifiRttManagerTest {
                 callbackCaptor.capture());
 
         // service calls back with success
-        callbackCaptor.getValue().onRangingResults(RangingResultCallback.STATUS_SUCCESS, results);
+        callbackCaptor.getValue().onRangingResults(results);
         mMockLooper.dispatchAll();
         verify(callbackMock).onRangingResults(results);
 
@@ -103,6 +101,8 @@ public class WifiRttManagerTest {
      */
     @Test
     public void testRangeFail() throws Exception {
+        int failureCode = RangingResultCallback.STATUS_CODE_FAIL;
+
         RangingRequest request = new RangingRequest.Builder().build();
         RangingResultCallback callbackMock = mock(RangingResultCallback.class);
         ArgumentCaptor<IRttCallback> callbackCaptor = ArgumentCaptor.forClass(IRttCallback.class);
@@ -113,9 +113,9 @@ public class WifiRttManagerTest {
                 callbackCaptor.capture());
 
         // service calls back with failure code
-        callbackCaptor.getValue().onRangingResults(RangingResultCallback.STATUS_FAIL, null);
+        callbackCaptor.getValue().onRangingFailure(failureCode);
         mMockLooper.dispatchAll();
-        verify(callbackMock).onRangingFailure();
+        verify(callbackMock).onRangingFailure(failureCode);
 
         verifyNoMoreInteractions(mockRttService, callbackMock);
     }
@@ -227,7 +227,7 @@ public class WifiRttManagerTest {
     @Test
     public void testRangingResultsParcel() {
         // Note: not validating parcel code of ScanResult (assumed to work)
-        int status = RangingResultCallback.STATUS_SUCCESS;
+        int status = RangingResult.STATUS_SUCCESS;
         final byte[] mac = HexEncoding.decode("000102030405".toCharArray(), false);
         PeerHandle peerHandle = new PeerHandle(10);
         int distanceCm = 105;