From b36dcb00e4646cc2d3f94a53ee31ede9e91530dc Mon Sep 17 00:00:00 2001
From: Nathan Harold <nharold@google.com>
Date: Fri, 25 Mar 2022 13:51:55 -0700
Subject: [PATCH] Add Applicability Language to Usage Settings

In order to ensure that the API contract is clear, move some
language from proposed CDD language onto the actual API surface
itself to clarify when various usage settings need to be supported.

Bug: 225950273
Test: make offline-sdk-docs (docstring only changes)
Change-Id: Idee297aaf7ac3af7f5fb86d85d806da13011c036
---
 .../java/android/telephony/CarrierConfigManager.java      | 4 ++++
 telephony/java/android/telephony/SubscriptionManager.java | 8 ++++++++
 2 files changed, 12 insertions(+)

diff --git a/telephony/java/android/telephony/CarrierConfigManager.java b/telephony/java/android/telephony/CarrierConfigManager.java
index 3691fb06abdb..8880bc492de7 100644
--- a/telephony/java/android/telephony/CarrierConfigManager.java
+++ b/telephony/java/android/telephony/CarrierConfigManager.java
@@ -4754,10 +4754,14 @@ public class CarrierConfigManager {
      * Either omit this key or pass a value of
      * {@link SubscriptionManager#USAGE_SETTING_UNKNOWN unknown} to preserve the current setting.
      *
+     * <p>Devices that support configuration of the cellular usage setting, including devices
+     * with HAL capability to set the cellular usage setting, must honor this setting accordingly.
+     *
      * {@link SubscriptionManager#USAGE_SETTING_DEFAULT default},
      * {@link SubscriptionManager#USAGE_SETTING_VOICE_CENTRIC voice-centric},
      * or {@link SubscriptionManager#USAGE_SETTING_DATA_CENTRIC data-centric}.
      * {@see SubscriptionInfo#getUsageSetting}
+     *
      */
     public static final String KEY_CELLULAR_USAGE_SETTING_INT =
             "cellular_usage_setting_int";
diff --git a/telephony/java/android/telephony/SubscriptionManager.java b/telephony/java/android/telephony/SubscriptionManager.java
index b6cacaf9f289..fc9acb81d408 100644
--- a/telephony/java/android/telephony/SubscriptionManager.java
+++ b/telephony/java/android/telephony/SubscriptionManager.java
@@ -1085,6 +1085,10 @@ public class SubscriptionManager {
      * <p>Refer to voice-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3.
      * Also refer to "UE's usage setting" as defined in 3gpp 24.301 section 3.1 and 3gpp 23.221
      * Annex A.
+     *
+     * <p>Devices that support {@link PackageManager#FEATURE_TELEPHONY_CALLING} and support usage
+     * setting configuration must support setting this value via
+     * {@link CarrierConfigManager#KEY_CELLULAR_USAGE_SETTING_INT}.
      */
     public static final int USAGE_SETTING_VOICE_CENTRIC = 1;
 
@@ -1094,6 +1098,10 @@ public class SubscriptionManager {
      * <p>Refer to data-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3.
      * Also refer to "UE's usage setting" as defined in 3gpp 24.301 section 3.1 and 3gpp 23.221
      * Annex A.
+     *
+     * <p>Devices that support {@link PackageManager#FEATURE_TELEPHONY_DATA} and support usage
+     * setting configuration must support setting this value via.
+     * {@link CarrierConfigManager#KEY_CELLULAR_USAGE_SETTING_INT}.
      */
     public static final int USAGE_SETTING_DATA_CENTRIC = 2;