Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d2639b90 authored by Rambo Wang's avatar Rambo Wang
Browse files

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 </p> tag which is not allowed by
Android API Guidelines (go/android-api-guidelines).

Bug: 204712404
Test: m offline-sdk-docs
Change-Id: I7da035937a0472194a8c8cbc5ef99481351f6d36
parent aac94b26

core/api/current.txt

+4 −4
Original line number Diff line number Diff line
@@ -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

























telephony/java/android/telephony/CarrierConfigManager.java



+32
−24






























Original line number
Diff line number
Diff line








@@ -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.















     *















     * <p>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.















     *















     * <p>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.













     * <p>













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













     *













     * <p>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}.













     * </p>













     * <p>













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













     *













     * <p>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.













     * </p>















     *















     * @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.













     * <p>













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













     *













     * <p>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.













     * </p>













     * <p>Requires that the calling app has carrier privileges.













     * <p>













     * This method returns before the reload has completed, and













     * {@link android.service.carrier.CarrierService#onLoadConfig} will be called from an













     * arbitrary thread.













     * </p>













     * @see TelephonyManager#hasCarrierPrivileges













     *













     * <p>Requires Permission:













     * {@link android.Manifest.permission#MODIFY_PHONE_STATE MODIFY_PHONE_STATE}, or the calling app













     * has carrier privileges (see {@link TelephonyManager#hasCarrierPrivileges()}).













     *













     * <p>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.













     * <p>













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













     * by SubscriptionInfoUpdater.













     * </p>













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













     *













     * <p>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.















     *















     * <p>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);