Merge "More cleanup prior to unhiding" into lmp-dev

2 files changed, 202 insertions, 113 deletions

diff --git a/telephony/java/android/telephony/SubInfoRecord.java b/telephony/java/android/telephony/SubInfoRecord.java
index 3a47269..805f787 100644
--- a/telephony/java/android/telephony/SubInfoRecord.java
+++ b/telephony/java/android/telephony/SubInfoRecord.java
@@ -1,18 +1,18 @@
 /*
-* Copyright (C) 2011-2014 MediaTek Inc.
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-*      http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 
 package android.telephony;
 
@@ -20,58 +20,96 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- *  A parcelable holder class of byte[] for ISms aidl implementation
- *  @hide
+ * A Parcelable class for Subscription Information.
+ * @hide - to be unhidden
  */
-
 public class SubInfoRecord implements Parcelable {
 
-    public long mSubId;
-    public String mIccId;
-    public int mSlotId;
-    public String mDisplayName;
-    public int mNameSource;
-    public int mColor;
-    public String mNumber;
-    public int mDisplayNumberFormat;
-    public int mDataRoaming;
-    public int[] mSimIconRes;
-    public int mMcc;
-    public int mMnc;
+    /**
+     * Subscription Identifier, this is a device unique number
+     * and not an index into an array
+     */
+    public long subId;
+    /** The GID for a SIM that maybe associated with this subscription, empty if unknown */
+    public String iccId;
+    /**
+     * The slot identifier for that currently contains the subscription
+     * and not necessarily unique and maybe INVALID_SLOT_ID if unknown
+     */
+    public int slotId;
+    /**
+     * The string displayed to the user that identifies this subscription
+     */
+    public String displayName;
+    /**
+     * The source of the name, NAME_SOURCE_UNDEFINED, NAME_SOURCE_DEFAULT_SOURCE,
+     * NAME_SOURCE_SIM_SOURCE or NAME_SOURCE_USER_INPUT.
+     */
+    public int nameSource;
+    /**
+     * The color to be used for when displaying to the user
+     */
+    public int color;
+    /**
+     * A number presented to the user identify this subscription
+     */
+    public String number;
+    /**
+     * How to display the phone number, DISPLAY_NUMBER_NONE, DISPLAY_NUMBER_FIRST,
+     * DISPLAY_NUMBER_LAST
+     */
+    public int displayNumberFormat;
+    /**
+     * Data roaming state, DATA_RAOMING_ENABLE, DATA_RAOMING_DISABLE
+     */
+    public int dataRoaming;
+    /**
+     * SIM Icon resource identifiers. FIXME: Check with MTK what it really is
+     */
+    public int[] simIconRes;
+    /**
+     * Mobile Country Code
+     */
+    public int mcc;
+    /**
+     * Mobile Network Code
+     */
+    public int mnc;
 
     public SubInfoRecord() {
-        this.mSubId = SubscriptionManager.INVALID_SUB_ID;
-        this.mIccId = "";
-        this.mSlotId = SubscriptionManager.INVALID_SLOT_ID;
-        this.mDisplayName = "";
-        this.mNameSource = 0;
-        this.mColor = 0;
-        this.mNumber = "";
-        this.mDisplayNumberFormat = 0;
-        this.mDataRoaming = 0;
-        this.mSimIconRes = new int[2];
-        this.mMcc = 0;
-        this.mMnc = 0;
+        this.subId = SubscriptionManager.INVALID_SUB_ID;
+        this.iccId = "";
+        this.slotId = SubscriptionManager.INVALID_SLOT_ID;
+        this.displayName = "";
+        this.nameSource = 0;
+        this.color = 0;
+        this.number = "";
+        this.displayNumberFormat = 0;
+        this.dataRoaming = 0;
+        this.simIconRes = new int[2];
+        this.mcc = 0;
+        this.mnc = 0;
     }
 
     public SubInfoRecord(long subId, String iccId, int slotId, String displayName, int nameSource,
             int color, String number, int displayFormat, int roaming, int[] iconRes,
             int mcc, int mnc) {
-        this.mSubId = subId;
-        this.mIccId = iccId;
-        this.mSlotId = slotId;
-        this.mDisplayName = displayName;
-        this.mNameSource = nameSource;
-        this.mColor = color;
-        this.mNumber = number;
-        this.mDisplayNumberFormat = displayFormat;
-        this.mDataRoaming = roaming;
-        this.mSimIconRes = iconRes;
-        this.mMcc = mcc;
-        this.mMnc = mnc;
+        this.subId = subId;
+        this.iccId = iccId;
+        this.slotId = slotId;
+        this.displayName = displayName;
+        this.nameSource = nameSource;
+        this.color = color;
+        this.number = number;
+        this.displayNumberFormat = displayFormat;
+        this.dataRoaming = roaming;
+        this.simIconRes = iconRes;
+        this.mcc = mcc;
+        this.mnc = mnc;
     }
 
     public static final Parcelable.Creator<SubInfoRecord> CREATOR = new Parcelable.Creator<SubInfoRecord>() {
+        @Override
         public SubInfoRecord createFromParcel(Parcel source) {
             long subId = source.readLong();
             String iccId = source.readString();
@@ -91,35 +129,39 @@ public class SubInfoRecord implements Parcelable {
                 displayNumberFormat, dataRoaming, iconRes, mcc, mnc);
         }
 
+        @Override
         public SubInfoRecord[] newArray(int size) {
             return new SubInfoRecord[size];
         }
     };
 
+    @Override
     public void writeToParcel(Parcel dest, int flags) {
-        dest.writeLong(mSubId);
-        dest.writeString(mIccId);
-        dest.writeInt(mSlotId);
-        dest.writeString(mDisplayName);
-        dest.writeInt(mNameSource);
-        dest.writeInt(mColor);
-        dest.writeString(mNumber);
-        dest.writeInt(mDisplayNumberFormat);
-        dest.writeInt(mDataRoaming);
-        dest.writeIntArray(mSimIconRes);
-        dest.writeInt(mMcc);
-        dest.writeInt(mMnc);
+        dest.writeLong(subId);
+        dest.writeString(iccId);
+        dest.writeInt(slotId);
+        dest.writeString(displayName);
+        dest.writeInt(nameSource);
+        dest.writeInt(color);
+        dest.writeString(number);
+        dest.writeInt(displayNumberFormat);
+        dest.writeInt(dataRoaming);
+        dest.writeIntArray(simIconRes);
+        dest.writeInt(mcc);
+        dest.writeInt(mnc);
     }
 
+    @Override
     public int describeContents() {
         return 0;
     }
 
+    @Override
     public String toString() {
-        return "{mSubId=" + mSubId + ", mIccId=" + mIccId + " mSlotId=" + mSlotId
-                + " mDisplayName=" + mDisplayName + " mNameSource=" + mNameSource
-                + " mColor=" + mColor + " mNumber=" + mNumber
-                + " mDisplayNumberFormat=" + mDisplayNumberFormat + " mDataRoaming=" + mDataRoaming
-                + " mSimIconRes=" + mSimIconRes + " mMcc " + mMcc + " mMnc " + mMnc + "}";
+        return "{mSubId=" + subId + ", mIccId=" + iccId + " mSlotId=" + slotId
+                + " mDisplayName=" + displayName + " mNameSource=" + nameSource
+                + " mColor=" + color + " mNumber=" + number
+                + " mDisplayNumberFormat=" + displayNumberFormat + " mDataRoaming=" + dataRoaming
+                + " mSimIconRes=" + simIconRes + " mMcc " + mcc + " mMnc " + mnc + "}";
     }
 }
diff --git a/telephony/java/android/telephony/SubscriptionManager.java b/telephony/java/android/telephony/SubscriptionManager.java
index b5f8847..58d30f1 100644
--- a/telephony/java/android/telephony/SubscriptionManager.java
+++ b/telephony/java/android/telephony/SubscriptionManager.java
@@ -28,45 +28,48 @@ import android.os.RemoteException;
 import com.android.internal.telephony.ISub;
 import com.android.internal.telephony.PhoneConstants;
 
+import java.util.ArrayList;
 import java.util.List;
 
 /**
  * SubscriptionManager is the application interface to SubscriptionController
  * and provides information about the current Telephony Subscriptions.
  *
- * @hide
+ * The android.Manifest.permission.READ_PHONE_STATE to retrieve the information, except
+ * getActiveSubIdList and getActiveSubIdCount for which no permission is needed.
+ *
+ * @hide - to be unhidden
  */
 public class SubscriptionManager implements BaseColumns {
     private static final String LOG_TAG = "SUB";
     private static final boolean DBG = true;
     private static final boolean VDBG = false;
 
-    // An invalid phone identifier
-    /** @hide */
+    /** An invalid phone identifier */
+    /** @hide - to be unhidden */
     public static final int INVALID_PHONE_ID = -1000;
 
-    // Indicates the caller wants the default phone id.
-    /** @hide */
+    /** Indicates the caller wants the default phone id. */
+    /** @hide - to be unhidden */
     public static final int DEFAULT_PHONE_ID = Integer.MAX_VALUE;
 
-    // An invalid slot identifier
-    /** @hide */
+    /** An invalid slot identifier */
+    /** @hide - to be unhidden */
     public static final int INVALID_SLOT_ID = -1000;
 
-    // Indicates the caller wants the default slot id.
+    /** Indicates the caller wants the default slot id. */
     /** @hide */
     public static final int DEFAULT_SLOT_ID = Integer.MAX_VALUE;
 
-    // An invalid subscription identifier
-    /** @hide */
-    public static final long INVALID_SUB_ID = -1000;
-
-    // Indicates the user should be asked which sub to use.
+    /** Indicates the user should be asked which sub to use. */
     /** @hide */
     public static final long ASK_USER_SUB_ID = -1001;
 
-    // Indicates the caller wants the default sub id.
-    /** @hide */
+    /** An invalid subscription identifier */
+    public static final long INVALID_SUB_ID = -1000;
+
+    /** Indicates the caller wants the default sub id. */
+    /** @hide - to be unhidden */
     public static final long DEFAULT_SUB_ID = Long.MAX_VALUE;
 
     /** @hide */
@@ -109,40 +112,58 @@ public class SubscriptionManager implements BaseColumns {
      */
     /** @hide */
     public static final String SIM_ID = "sim_id";
-    /** @hide */
+
+    /** SIM is not inserted */
+    /** @hide - to be unhidden */
     public static final int SIM_NOT_INSERTED = -1;
 
     /**
-     * The display name of a SIM.
+     * TelephonyProvider column name for user displayed name.
      * <P>Type: TEXT (String)</P>
      */
     /** @hide */
     public static final String DISPLAY_NAME = "display_name";
 
-    /** @hide */
+    /**
+     * Default name resource
+     * @hide
+     */
     public static final int DEFAULT_NAME_RES = com.android.internal.R.string.unknownName;
 
     /**
-     * The display name source of a SIM.
-     * <P>Type: INT (int)</P>
+     * TelephonyProvider column name for source of the user displayed name.
+     * <P>Type: INT (int)</P> with one of the NAME_SOURCE_XXXX values below
+     *
+     * @hide
      */
-    /** @hide */
     public static final String NAME_SOURCE = "name_source";
 
-    /** @hide */
+    /**
+     * The name_source is undefined
+     * @hide
+     */
     public static final int NAME_SOURCE_UNDEFINDED = -1;
 
-    /** @hide */
+    /**
+     * The name_source is the default
+     * @hide
+     */
     public static final int NAME_SOURCE_DEFAULT_SOURCE = 0;
 
-    /** @hide */
+    /**
+     * The name_source is from the SIM
+     * @hide
+     */
     public static final int NAME_SOURCE_SIM_SOURCE = 1;
 
-    /** @hide */
+    /**
+     * The name_source is from the user
+     * @hide
+     */
     public static final int NAME_SOURCE_USER_INPUT = 2;
 
     /**
-     * The color of a SIM.
+     * TelephonyProvider column name for the color of a SIM.
      * <P>Type: INTEGER (int)</P>
      */
     /** @hide */
@@ -164,14 +185,14 @@ public class SubscriptionManager implements BaseColumns {
     public static final int COLOR_DEFAULT = COLOR_1;
 
     /**
-     * The phone number of a SIM.
+     * TelephonyProvider column name for the phone number of a SIM.
      * <P>Type: TEXT (String)</P>
      */
     /** @hide */
     public static final String NUMBER = "number";
 
     /**
-     * The number display format of a SIM.
+     * TelephonyProvider column name for the number display format of a SIM.
      * <P>Type: INTEGER (int)</P>
      */
     /** @hide */
@@ -190,7 +211,7 @@ public class SubscriptionManager implements BaseColumns {
     public static final int DISLPAY_NUMBER_DEFAULT = DISPLAY_NUMBER_FIRST;
 
     /**
-     * Permission for data roaming of a SIM.
+     * TelephonyProvider column name for permission for data roaming of a SIM.
      * <P>Type: INTEGER (int)</P>
      */
     /** @hide */
@@ -206,13 +227,13 @@ public class SubscriptionManager implements BaseColumns {
     public static final int DATA_ROAMING_DEFAULT = DATA_ROAMING_DISABLE;
 
     /**
-     * The MCC associated with a SIM.
+     * TelephonyProvider column name for the MCC associated with a SIM.
      * <P>Type: INTEGER (int)</P>
      */
     public static final String MCC = "mcc";
 
     /**
-     * The MNC associated with a SIM.
+     * TelephonyProvider column name for the MNC associated with a SIM.
      * <P>Type: INTEGER (int)</P>
      */
     public static final String MNC = "mnc";
@@ -239,10 +260,10 @@ public class SubscriptionManager implements BaseColumns {
     }
 
     /**
-     * Get the SubInfoRecord according to an index
+     * Get the SubInfoRecord associated with the subId
      * @param subId The unique SubInfoRecord index in database
      * @return SubInfoRecord, maybe null
-     * @hide
+     * @hide - to be unhidden
      */
     public static SubInfoRecord getSubInfoUsingSubId(long subId) {
         if (!isValidSubId(subId)) {
@@ -268,7 +289,7 @@ public class SubscriptionManager implements BaseColumns {
     /**
      * Get the SubInfoRecord according to an IccId
      * @param iccId the IccId of SIM card
-     * @return SubInfoRecord, maybe null
+     * @return SubInfoRecord List, maybe empty but not null
      * @hide
      */
     public static List<SubInfoRecord> getSubInfoUsingIccId(String iccId) {
@@ -289,14 +310,18 @@ public class SubscriptionManager implements BaseColumns {
             // ignore it
         }
 
+
+        if (result == null) {
+            result = new ArrayList<SubInfoRecord>();
+        }
         return result;
     }
 
     /**
      * Get the SubInfoRecord according to slotId
      * @param slotId the slot which the SIM is inserted
-     * @return SubInfoRecord, maybe null
-     * @hide
+     * @return SubInfoRecord list, maybe empty but not null
+     * @hide - to be unhidden
      */
     public static List<SubInfoRecord> getSubInfoUsingSlotId(int slotId) {
         // FIXME: Consider never returning null
@@ -316,12 +341,17 @@ public class SubscriptionManager implements BaseColumns {
             // ignore it
         }
 
+
+        if (result == null) {
+            result = new ArrayList<SubInfoRecord>();
+        }
         return result;
     }
 
     /**
-     * Get all the SubInfoRecord(s) in subinfo database
-     * @return Array list of all SubInfoRecords in database, include thsoe that were inserted before
+     * Get all the SubInfoRecord(s) in subInfo database
+     * @return List of all SubInfoRecords in database, include those that were inserted before
+     * maybe empty but not null.
      * @hide
      */
     public static List<SubInfoRecord> getAllSubInfoList() {
@@ -338,13 +368,16 @@ public class SubscriptionManager implements BaseColumns {
             // ignore it
         }
 
+        if (result == null) {
+            result = new ArrayList<SubInfoRecord>();
+        }
         return result;
     }
 
     /**
      * Get the SubInfoRecord(s) of the currently inserted SIM(s)
-     * @return Array list of currently inserted SubInfoRecord(s)
-     * @hide
+     * @return Array list of currently inserted SubInfoRecord(s) maybe empty but not null
+     * @hide - to be unhidden
      */
     public static List<SubInfoRecord> getActiveSubInfoList() {
         List<SubInfoRecord> result = null;
@@ -358,6 +391,9 @@ public class SubscriptionManager implements BaseColumns {
             // ignore it
         }
 
+        if (result == null) {
+            result = new ArrayList<SubInfoRecord>();
+        }
         return result;
     }
 
@@ -594,7 +630,12 @@ public class SubscriptionManager implements BaseColumns {
         return result;
     }
 
-    /** @hide */
+    /**
+     * Get slotId associated with the subscription.
+     * @return slotId as a positive integer or a negative value if an error either
+     * SIM_NOT_INSERTED or INVALID_SLOT_ID.
+     * @hide - to be unhidden
+     */
     public static int getSlotId(long subId) {
         if (!isValidSubId(subId)) {
             logd("[getSlotId]- fail");
@@ -750,7 +791,10 @@ public class SubscriptionManager implements BaseColumns {
         return getPhoneId(getDefaultVoiceSubId());
     }
 
-    /** @hide */
+    /**
+     * @return subId of the DefaultSms subscription or the value INVALID_SUB_ID if an error.
+     * @hide - to be unhidden
+     */
     public static long getDefaultSmsSubId() {
         long subId = INVALID_SUB_ID;
 
@@ -876,7 +920,10 @@ public class SubscriptionManager implements BaseColumns {
         }
     }
 
-    /** @hide */
+    /**
+     * @return true if a valid subId else false
+     * @hide - to be unhidden
+     */
     public static boolean isValidSubId(long subId) {
         return subId > INVALID_SUB_ID ;
     }