From ace5c08674dbf34422e94e7d6b1bf49b1f81460d Mon Sep 17 00:00:00 2001 From: Sal Savage Date: Fri, 4 Mar 2022 15:12:40 -0800 Subject: 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 --- .../android/bluetooth/BluetoothHeadsetClient.java | 23 ++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'framework/java/android/bluetooth/BluetoothHeadsetClient.java') 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; } -- cgit v1.2.3