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

Commit 2fbe1540 authored by Chen Xu's avatar Chen Xu
Browse files

improve euiccManager API doc 

Bug: 220079752
Test: build
Change-Id: I99f6669c8e6620821c5d1bd0b867ac35ac54a1c7
parent 8d3ba55d

telephony/java/android/telephony/TelephonyManager.java

+4 −3
Original line number Diff line number Diff line
@@ -4189,7 +4189,8 @@ public class TelephonyManager { 
     * {@link UiccSlotMapping} which consist of both physical slot index and port index.

     * Logical slot is the slot that is seen by modem. Physical slot is the actual physical slot.

     * Port index is the index (enumerated value) for the associated port available on the SIM.

     * Each physical slot can have multiple ports if multi-enabled profile(MEP) is supported.

     * Each physical slot can have multiple ports if

     * {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP} is supported.

     *

     * Example: no. of logical slots 1 and physical slots 2 do not support MEP, each physical slot

     * has one port:
@@ -4285,11 +4286,11 @@ public class TelephonyManager { 
    /**

     * Get the mapping from logical slots to physical sim slots and port indexes. Initially the

     * logical slot index was mapped to physical slot index, but with support for multi-enabled

     * profile(MEP) logical slot is now mapped to port index.

     * profile(MEP){@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP},logical slot is now mapped to

     * port index.

     *

     * @return a collection of {@link UiccSlotMapping} which indicates the mapping from logical

     *         slots to ports and physical slots.

     *

     * @hide

     */

    @SystemApi

telephony/java/android/telephony/UiccCardInfo.java

+10 −5
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ package android.telephony; 


import android.annotation.NonNull;

import android.annotation.Nullable;

import android.content.pm.PackageManager;

import android.os.Parcel;

import android.os.Parcelable;
@@ -147,9 +148,10 @@ public final class UiccCardInfo implements Parcelable { 
     * Note that this field may be omitted if the caller does not have the correct permissions

     * (see {@link TelephonyManager#getUiccCardsInfo()}).

     *

     * @deprecated with support for MEP(multiple enabled profile), a SIM card can have more than one

     * @deprecated with support for MEP(multiple enabled profile)

     * {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP}, a SIM card can have more than one

     * ICCID active at the same time. Instead use {@link UiccPortInfo#getIccId()} to retrieve ICCID.

     * To find {@link UiccPortInfo} use {@link UiccCardInfo#getPorts()}

     * To find {@link UiccPortInfo} use {@link UiccCardInfo#getPorts()}.

     *

     * @throws UnsupportedOperationException if the calling app's target SDK is T and beyond.

     */
@@ -192,11 +194,11 @@ public final class UiccCardInfo implements Parcelable { 
    }



    /*

     * Whether the UICC card supports multiple enable profile(MEP)

     * Whether the UICC card supports multiple enabled profile(MEP)

     * UICCs are generally MEP disabled, there can be only one active profile on the physical

     * sim card.

     *

     * @return {@code true} if the eUICC is supporting multiple enabled profile(MEP).

     * @return {@code true} if the UICC is supporting multiple enabled profile(MEP).

     */

    public boolean isMultipleEnabledProfilesSupported() {

        return mIsMultipleEnabledProfilesSupported;
@@ -205,6 +207,9 @@ public final class UiccCardInfo implements Parcelable { 
    /**

     * Get information regarding port, ICCID and its active status.

     *

     * For device which support {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP}, it should return

     * more than one {@link UiccPortInfo} object if the card is eUICC.

     *

     * @return Collection of {@link UiccPortInfo}

     */

    public @NonNull Collection<UiccPortInfo> getPorts() {

telephony/java/android/telephony/UiccPortInfo.java

+3 −1
Original line number Diff line number Diff line
@@ -29,7 +29,9 @@ import java.util.Objects; 
 * Per GSMA SGP.22 V3.0, a port is a logical entity to which an active UICC profile can be bound on

 * a UICC card. If UICC supports 2 ports, then the port index is numbered 0,1.

 * Each port index is unique within an UICC, but not necessarily unique across UICC’s.

 * For UICC's does not support MEP(Multi-enabled profile), just return the default port index 0.

 * For UICC's does not support MEP(Multi-enabled profile)

 * {@link android.content.pm.PackageManager#FEATURE_TELEPHONY_EUICC_MEP}, just return the default

 * port index 0.

 */

public final class UiccPortInfo implements Parcelable{

    private final String mIccId;

telephony/java/android/telephony/UiccSlotInfo.java

+4 −0
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ import android.annotation.IntDef; 
import android.annotation.NonNull;

import android.annotation.Nullable;

import android.annotation.SystemApi;

import android.content.pm.PackageManager;

import android.os.Parcel;

import android.os.Parcelable;
@@ -225,6 +226,9 @@ public class UiccSlotInfo implements Parcelable { 
    /**

     * Get Information regarding port, iccid and its active status.

     *

     * For device which support {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP}, it should return

     * more than one {@link UiccPortInfo} object if the card is eUICC.

     *

     * @return Collection of {@link UiccPortInfo}

     */

    public @NonNull Collection<UiccPortInfo> getPorts() {

telephony/java/android/telephony/euicc/EuiccManager.java

+46 −11
Original line number Diff line number Diff line
@@ -37,6 +37,7 @@ import android.os.RemoteException; 
import android.telephony.SubscriptionInfo;

import android.telephony.TelephonyFrameworkInitializer;

import android.telephony.TelephonyManager;

import android.telephony.UiccCardInfo;

import android.telephony.euicc.EuiccCardManager.ResetOption;

import android.util.Log;
@@ -931,6 +932,21 @@ public class EuiccManager { 
     * intent to prompt the user to accept the download. The caller should also be authorized to

     * manage the subscription to be downloaded.

     *

     * <p>If device support {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP} and

     * switchAfterDownload is {@code true}, the subscription will be enabled on an esim port based

     * on the following selection rules:

     * <ul>

     *    <li>In SS(Single SIM) mode, if the embedded slot already has an active port, then download

     *    and enable the subscription on this port.

     *    <li>In SS mode, if the embedded slot is not active, then try to download and enable the

     *    subscription on the default port 0 of eUICC.

     *    <li>In DSDS mode, find first available port to download and enable the subscription.

     *    (see {@link #isSimPortAvailable(int)})

     *</ul>

     * If there is no available port, an {@link #EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR}

     * will be returned in the callback intent to prompt the user to disable an already-active

     * subscription.

     *

     * @param subscription the subscription to download.

     * @param switchAfterDownload if true, the profile will be activated upon successful download.

     * @param callbackIntent a PendingIntent to launch when the operation completes.
@@ -1141,14 +1157,25 @@ public class EuiccManager { 
     * intent to prompt the user to accept the download. The caller should also be authorized to

     * manage the subscription to be enabled.

     *

     * <p> From Android T, devices might support MEP(Multiple Enabled Profiles), the subscription

     * can be installed on different port from the eUICC. Calling apps with carrier privilege

     * (see {@link TelephonyManager#hasCarrierPrivileges}) over the currently active subscriptions

     * can use {@link #switchToSubscription(int, int, PendingIntent)} to specify which port to

     * enable the subscription. Otherwise, use this API to enable the subscription on the eUICC

     * and the platform will internally resolve a port. If there is no available port,

     * an {@link #EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR} might be returned in the callback

     * intent to prompt the user to disable an already-active subscription.

     * <p> From Android T, devices might support {@link PackageManager#FEATURE_TELEPHONY_EUICC_MEP},

     * the subscription can be installed on different port from the eUICC. Calling apps with

     * carrier privilege (see {@link TelephonyManager#hasCarrierPrivileges}) over the currently

     * active subscriptions can use {@link #switchToSubscription(int, int, PendingIntent)} to

     * specify which port to enable the subscription. Otherwise, use this API to enable the

     * subscription on the eUICC and the platform will internally resolve a port based on following

     * rules:

     * <ul>

     *    <li>always use the default port 0 is eUICC does not support MEP.

     *    <li>In SS(Single SIM) mode, if the embedded slot already has an active port, then enable

     *    the subscription on this port.

     *    <li>In SS mode, if the embedded slot is not active, then try to enable the subscription on

     *    the default port 0 of eUICC.

     *    <li>In DSDS mode, find first available port to enable the subscription.

     *    (see {@link #isSimPortAvailable(int)})

     *</ul>

     * If there is no available port, an {@link #EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR}

     * will be returned in the callback intent to prompt the user to disable an already-active

     * subscription.

     *

     * @param subscriptionId the ID of the subscription to enable. May be

     *     {@link android.telephony.SubscriptionManager#INVALID_SUBSCRIPTION_ID} to deactivate the
@@ -1197,7 +1224,15 @@ public class EuiccManager { 
     *

     * <p> If the caller is passing invalid port index,

     * an {@link #EMBEDDED_SUBSCRIPTION_RESULT_ERROR} with detailed error code

     * {@link #ERROR_INVALID_PORT} will be returned.

     * {@link #ERROR_INVALID_PORT} will be returned. The port index is invalid if one of the

     * following requirements is met:

     * <ul>

     *     <li>index is beyond the range of {@link UiccCardInfo#getPorts()}.

     *     <li>In SS(Single SIM) mode, the embedded slot already has an active port with different

     *     port index.

     *     <li>In DSDS mode, if the psim slot is active and the embedded slot already has an active

     *     empty port with different port index.

     * </ul>

     *

     * <p> Depending on the target port and permission check,

     * an {@link #EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR} might be returned to the callback
@@ -1522,8 +1557,8 @@ public class EuiccManager { 


    /**

     * Returns whether the passing portIndex is available.

     * A port is available if it has no profiles enabled on it or calling app has carrier privilege

     * over the profile installed on the selected port.

     * A port is available if it is active without enabled profile on it or

     * calling app has carrier privilege over the profile installed on the selected port.

     * Always returns false if the cardId is a physical card.

     *

     * @param portIndex is an enumeration of the ports available on the UICC.