From d2639b906bbde4348fed1daf3e04315f3407209f Mon Sep 17 00:00:00 2001 From: Rambo Wang Date: Tue, 2 Nov 2021 07:23:49 -0700 Subject: [PATCH] Update javadoc of CarrierConfigManager The implementation in CarrierConfigLoader allows system privileged app to access the API CarrierConfigManager#notifyConfigChangedForSubId, starting from N release. Several features has been built on it. It is better to explicitly specify the behavior in javadoc to avoid misunderstanding. For the similar reason, the javadoc of methods below are also updated: - getConfigForSubId - getConfig - getConfigByComponentForSubId The cl also removes the closing

tag which is not allowed by Android API Guidelines (go/android-api-guidelines). Bug: 204712404 Test: m offline-sdk-docs Change-Id: I7da035937a0472194a8c8cbc5ef99481351f6d36 --- core/api/current.txt | 8 +-- .../telephony/CarrierConfigManager.java | 56 +++++++++++-------- 2 files changed, 36 insertions(+), 28 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index 1c0144546239f..6a701ece5b3d8 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -40728,11 +40728,11 @@ package android.telephony { } public class CarrierConfigManager { - method @Nullable public android.os.PersistableBundle getConfig(); - method @Nullable public android.os.PersistableBundle getConfigByComponentForSubId(@NonNull String, int); - method @Nullable public android.os.PersistableBundle getConfigForSubId(int); + method @Nullable @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public android.os.PersistableBundle getConfig(); + method @Nullable @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public android.os.PersistableBundle getConfigByComponentForSubId(@NonNull String, int); + method @Nullable @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public android.os.PersistableBundle getConfigForSubId(int); method public static boolean isConfigForIdentifiedCarrier(android.os.PersistableBundle); - method public void notifyConfigChangedForSubId(int); + method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void notifyConfigChangedForSubId(int); field public static final String ACTION_CARRIER_CONFIG_CHANGED = "android.telephony.action.CARRIER_CONFIG_CHANGED"; field public static final int CARRIER_NR_AVAILABILITY_NSA = 1; // 0x1 field public static final int CARRIER_NR_AVAILABILITY_SA = 2; // 0x2 diff --git a/telephony/java/android/telephony/CarrierConfigManager.java b/telephony/java/android/telephony/CarrierConfigManager.java index d11c66702d995..7bfa1c71b795e 100644 --- a/telephony/java/android/telephony/CarrierConfigManager.java +++ b/telephony/java/android/telephony/CarrierConfigManager.java @@ -21,6 +21,7 @@ import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; import android.annotation.RequiresPermission; +import android.annotation.SuppressAutoDoc; import android.annotation.SuppressLint; import android.annotation.SystemApi; import android.annotation.SystemService; @@ -5874,12 +5875,15 @@ public class CarrierConfigManager { * any carrier specific configuration has been applied. * *

Requires Permission: - * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} + * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}, or the calling app + * has carrier privileges (see {@link TelephonyManager#hasCarrierPrivileges()}). * * @param subId the subscription ID, normally obtained from {@link SubscriptionManager}. * @return A {@link PersistableBundle} containing the config for the given subId, or default * values for an invalid subId. */ + @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges + @RequiresPermission(Manifest.permission.READ_PHONE_STATE) @Nullable public PersistableBundle getConfigForSubId(int subId) { try { @@ -5968,10 +5972,13 @@ public class CarrierConfigManager { * called to confirm whether any carrier specific configuration has been applied. * *

Requires Permission: - * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} + * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}, or the calling app + * has carrier privileges (see {@link TelephonyManager#hasCarrierPrivileges()}). * * @see #getConfigForSubId */ + @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges + @RequiresPermission(Manifest.permission.READ_PHONE_STATE) @Nullable public PersistableBundle getConfig() { return getConfigForSubId(SubscriptionManager.getDefaultSubscriptionId()); @@ -5980,8 +5987,8 @@ public class CarrierConfigManager { /** * Determines whether a configuration {@link PersistableBundle} obtained from * {@link #getConfig()} or {@link #getConfigForSubId(int)} corresponds to an identified carrier. - *

- * When an app receives the {@link CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED} + * + *

When an app receives the {@link CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED} * broadcast which informs it that the carrier configuration has changed, it is possible * that another reload of the carrier configuration has begun since the intent was sent. * In this case, the carrier configuration the app fetches (e.g. via {@link #getConfig()}) @@ -5990,14 +5997,12 @@ public class CarrierConfigManager { * return true because it may belong to another previous identified carrier. Users should * always call {@link #getConfig()} or {@link #getConfigForSubId(int)} after receiving the * broadcast {@link #ACTION_CARRIER_CONFIG_CHANGED}. - *

- *

- * After using {@link #getConfig()} or {@link #getConfigForSubId(int)} an app should always + * + *

After using {@link #getConfig()} or {@link #getConfigForSubId(int)} an app should always * use this method to confirm whether any carrier specific configuration has been applied. * Especially when an app misses the broadcast {@link #ACTION_CARRIER_CONFIG_CHANGED} but it * still needs to get the current configuration, it must use this method to verify whether the * configuration is default or carrier overridden. - *

* * @param bundle the configuration bundle to be checked. * @return boolean true if any carrier specific configuration bundle has been applied, false @@ -6009,19 +6014,20 @@ public class CarrierConfigManager { /** * Calling this method triggers telephony services to fetch the current carrier configuration. - *

- * Normally this does not need to be called because the platform reloads config on its own. + * + *

Normally this does not need to be called because the platform reloads config on its own. * This should be called by a carrier service app if it wants to update config at an arbitrary * moment. - *

- *

Requires that the calling app has carrier privileges. - *

- * This method returns before the reload has completed, and - * {@link android.service.carrier.CarrierService#onLoadConfig} will be called from an - * arbitrary thread. - *

- * @see TelephonyManager#hasCarrierPrivileges + * + *

Requires Permission: + * {@link android.Manifest.permission#MODIFY_PHONE_STATE MODIFY_PHONE_STATE}, or the calling app + * has carrier privileges (see {@link TelephonyManager#hasCarrierPrivileges()}). + * + *

This method returns before the reload has completed, and {@link + * android.service.carrier.CarrierService#onLoadConfig} will be called from an arbitrary thread. */ + @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges + @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void notifyConfigChangedForSubId(int subId) { try { ICarrierConfigLoader loader = getICarrierConfigLoader(); @@ -6037,11 +6043,10 @@ public class CarrierConfigManager { } /** - * Request the carrier config loader to update the cofig for phoneId. - *

- * Depending on simState, the config may be cleared or loaded from config app. This is only used - * by SubscriptionInfoUpdater. - *

+ * Request the carrier config loader to update the config for phoneId. + * + *

Depending on simState, the config may be cleared or loaded from config app. This is only + * used by SubscriptionInfoUpdater. * * @hide */ @@ -6112,13 +6117,16 @@ public class CarrierConfigManager { * Gets the configuration values for a component using its prefix. * *

Requires Permission: - * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} + * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}, or the calling app + * has carrier privileges (see {@link TelephonyManager#hasCarrierPrivileges()}). * * @param prefix prefix of the component. * @param subId the subscription ID, normally obtained from {@link SubscriptionManager}. * * @see #getConfigForSubId */ + @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges + @RequiresPermission(Manifest.permission.READ_PHONE_STATE) @Nullable public PersistableBundle getConfigByComponentForSubId(@NonNull String prefix, int subId) { PersistableBundle configs = getConfigForSubId(subId);