Address API Council Feedback for NetworkServiceState APIs

This changes:
(1) Updates getOperatorName to getNetworkOperatorName. This is in line
with both the HFP specs wording and the related TelephonyManager API.
(2) Adds an IntRange annotation to the getSignalStrength. This
annotation was chosen because the spec doesn't have definitive wording
on how the 0 to 5 numbers are derived, despite the fact that we
generally treat them as (None/Unknown, Very Poor, Poor, Moderate, Good,
Great). IntRange adds some clarity around the domain of values without
making any claims about the exact meanings.

Tag: #refactor
Bug: 219820175
Ignore-AOSP-First: Mainline related API Council Feedback change
Test: atest BluetoothInstrumentationTests
Change-Id: I5974bc4ee39113a3ebbffaacd28c0d5af70483ad

2 files changed, 19 insertions, 8 deletions

diff --git a/framework/api/system-current.txt b/framework/api/system-current.txt
index 28d8f6c4a9..37bef7169c 100644
--- a/framework/api/system-current.txt
+++ b/framework/api/system-current.txt
@@ -341,8 +341,8 @@ package android.bluetooth {
 
   public static final class BluetoothHeadsetClient.NetworkServiceState implements android.os.Parcelable {
     method @NonNull public android.bluetooth.BluetoothDevice getDevice();
-    method @Nullable public String getOperatorName();
-    method public int getSignalStrength();
+    method @Nullable public String getNetworkOperatorName();
+    method @IntRange(from=0, to=5) public int getSignalStrength();
     method public boolean isRoaming();
     method public boolean isServiceAvailable();
     field @NonNull public static final android.os.Parcelable.Creator<android.bluetooth.BluetoothHeadsetClient.NetworkServiceState> CREATOR;
diff --git a/framework/java/android/bluetooth/BluetoothHeadsetClient.java b/framework/java/android/bluetooth/BluetoothHeadsetClient.java
index 33049c49a7..7cfca9e204 100644
--- a/framework/java/android/bluetooth/BluetoothHeadsetClient.java
+++ b/framework/java/android/bluetooth/BluetoothHeadsetClient.java
@@ -17,6 +17,7 @@ package android.bluetooth;
 
 import static android.bluetooth.BluetoothUtils.getSyncTimeout;
 
+import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
@@ -1746,8 +1747,19 @@ public final class BluetoothHeadsetClient implements BluetoothProfile, AutoClose
         private final String mOperatorName;
 
         /**
-         * The general signal strength
-         * (0 - Unknown, 1 - Poor, 2 - Fair, 3 - Good, 4 - Great, 5 - Excellent)
+         * The general signal strength, from 0 to 5.
+         *
+         * Bluetooth HFP v1.8 specifies that the signal strength of a device can be [0, 5]. It does
+         * place any requirements on how a device derives those values. While they're typically
+         * derived from signal quality/RSSI buckets, there's way to be certain on the exact meaning.
+         *
+         * That said, you can "generally" interpret the values relative to each other as follows:
+         *   - Level 0: None/Unknown
+         *   - Level 1: Very Poor
+         *   - Level 2: Poor
+         *   - Level 3: Fair
+         *   - Level 4: Good
+         *   - Level 5: Great
          */
         private final int mSignalStrength;
 
@@ -1808,20 +1820,19 @@ public final class BluetoothHeadsetClient implements BluetoothProfile, AutoClose
          * @hide
          */
         @SystemApi
-        public @Nullable String getOperatorName() {
+        public @Nullable String getNetworkOperatorName() {
             return mOperatorName;
         }
 
         /**
          * Get the network's general signal strength
          *
-         * @return The general signal strength (0 - None, 1 - Poor, 2 - Fair, 3 - Good,
-         *         4 - Great, 5 - Excellent)
+         * @return The general signal strength, range [0, 5]
          *
          * @hide
          */
         @SystemApi
-        public int getSignalStrength() {
+        public @IntRange(from = 0, to = 5) int getSignalStrength() {
             return mSignalStrength;
         }