From 0bcdd6cbd4e6d609007e3acb0a550964ee83e5a2 Mon Sep 17 00:00:00 2001 From: sqian Date: Tue, 30 Oct 2018 13:55:23 -0700 Subject: [PATCH] Explain the difference of isValid, isActive, isUsable Bug: 118675257 Test: compile Change-Id: Ibec1bf7929991ca0e2910684f5216ab8372d4e95 --- .../telephony/SubscriptionManager.java | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/telephony/java/android/telephony/SubscriptionManager.java b/telephony/java/android/telephony/SubscriptionManager.java index 1662d6e33cf70..f06a8929d36df 100644 --- a/telephony/java/android/telephony/SubscriptionManager.java +++ b/telephony/java/android/telephony/SubscriptionManager.java @@ -2008,21 +2008,27 @@ public class SubscriptionManager { } /** - * Checks if the supplied subscription ID is valid. - * Note: a valid subscription ID does not necessarily correspond to an active subscription. + * Check if the supplied subscription ID is valid. + * + *

A valid subscription ID is not necessarily an active subscription ID + * (see {@link #isActiveSubscriptionId(int)}) or an usable subscription ID + * (see {@link #isUsableSubscriptionId(int)}). Unless specifically noted, subscription + * APIs work with a valid subscription ID. * * @param subscriptionId The subscription ID. - * @return true if the supplied subscriptionId is valid; false otherwise. + * @return {@code true} if the supplied subscriptionId is valid; {@code false} otherwise. */ public static boolean isValidSubscriptionId(int subscriptionId) { return subscriptionId > INVALID_SUBSCRIPTION_ID; } /** - * Check if the subscription ID is usable. + * Check if the supplied subscription ID is usable. * - * A usable subscription ID has a valid value except some special values such as - * {@link #DEFAULT_SUBSCRIPTION_ID}. It can be used for subscription functions. + *

A usable subscription ID is a valid subscription ID, but not necessarily an active + * subscription ID (see {@link #isActiveSubscriptionId(int)}). Some subscription APIs + * require a usable subscription ID, and this is noted in their documentation; otherwise, a + * subscription ID does not need to be usable for subscription functions, only valid. * * @param subscriptionId the subscription ID * @return {@code true} if the subscription ID is usable; {@code false} otherwise. @@ -2280,7 +2286,8 @@ public class SubscriptionManager { } /** - * Checks if the supplied subscription ID corresponds to an active subscription. + * Checks if the supplied subscription ID corresponds to a subscription which is actively in + * use on the device. An active subscription ID is a valid and usable subscription ID. * * @param subscriptionId the subscription ID. * @return {@code true} if the supplied subscription ID corresponds to an active subscription;