EuiccManager

ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS

static val ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS: String

Intent action to launch the embedded SIM (eUICC) management settings screen.

This screen shows a list of embedded profiles and offers the user the ability to switch between them, download new profiles, and delete unused profiles.

The activity will immediately finish with android.app.Activity#RESULT_CANCELED if isEnabled is false. This is ued by non-LPA app to bring up LUI.

Value: "android.telephony.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS"

ACTION_NOTIFY_CARRIER_SETUP_INCOMPLETE

static val ACTION_NOTIFY_CARRIER_SETUP_INCOMPLETE: String

Broadcast Action: The action sent to carrier app so it knows the carrier setup is not completed.

Value: "android.telephony.euicc.action.NOTIFY_CARRIER_SETUP_INCOMPLETE"

ACTION_START_EUICC_ACTIVATION

static val ACTION_START_EUICC_ACTIVATION: String

Intent action sent by a carrier app to launch the eSIM activation flow provided by the LPA UI (LUI). The carrier app must send this intent with one of the following:

EXTRA_USE_QR_SCANNER not set or set to false: The LPA should try to get an activation code from the carrier app by binding to the carrier app service implementing android.service.euicc.EuiccService#ACTION_BIND_CARRIER_PROVISIONING_SERVICE.

EXTRA_USE_QR_SCANNER set to true: The LPA should launch a QR scanner for the user to scan an eSIM profile QR code.

Upon completion, the LPA should return one of the following results to the carrier app:

Activity.RESULT_OK: The LPA has succeeded in downloading the new eSIM profile.

Activity.RESULT_CANCELED: The carrier app should treat this as if the user pressed the back button.

Anything else: The carrier app should treat this as an error.

LPA needs to check if caller's package name is allowed to perform this action.

Value: "android.telephony.euicc.action.START_EUICC_ACTIVATION"

EMBEDDED_SUBSCRIPTION_RESULT_ERROR

static val EMBEDDED_SUBSCRIPTION_RESULT_ERROR: Int

Result code for an operation indicating that an unresolvable error occurred. EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE will be populated with a detailed error code for logging/debugging purposes only.

Value: 2

EMBEDDED_SUBSCRIPTION_RESULT_OK

static val EMBEDDED_SUBSCRIPTION_RESULT_OK: Int

Result code for an operation indicating that the operation succeeded.

Value: 0

EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR

static val EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR: Int

Result code for an operation indicating that the user must take some action before the operation can continue.

Value: 1

ERROR_ADDRESS_MISSING

static val ERROR_ADDRESS_MISSING: Int

Address is missing e.g SMDS/SMDP address is missing.

Value: 10011

ERROR_CARRIER_LOCKED

static val ERROR_CARRIER_LOCKED: Int

Operation such as downloading/switching to another profile failed due to device being carrier locked.

Value: 10000

ERROR_CERTIFICATE_ERROR

static val ERROR_CERTIFICATE_ERROR: Int

Certificate needed for authentication is not valid or missing. E.g SMDP/SMDS authentication failed.

Value: 10012

ERROR_CONNECTION_ERROR

static val ERROR_CONNECTION_ERROR: Int

Failure to create a connection.

Value: 10014

ERROR_DISALLOWED_BY_PPR

static val ERROR_DISALLOWED_BY_PPR: Int

Failed to load profile onto eUICC due to Profile Policy Rules.

Value: 10010

ERROR_EUICC_INSUFFICIENT_MEMORY

static val ERROR_EUICC_INSUFFICIENT_MEMORY: Int

There is no more space available on the eUICC for new profiles.

Value: 10004

ERROR_EUICC_MISSING

static val ERROR_EUICC_MISSING: Int

eUICC is missing or defective on the device.

Value: 10006

ERROR_INCOMPATIBLE_CARRIER

static val ERROR_INCOMPATIBLE_CARRIER: Int

The profile's carrier is incompatible with the LPA.

Value: 10003

ERROR_INSTALL_PROFILE

static val ERROR_INSTALL_PROFILE: Int

Failure to load the profile onto the eUICC card. e.g 1. iccid of the profile already exists on the eUICC. 2. GSMA(.22 v2.2) Profile Install Result - installFailedDueToDataMismatch 3. operation was interrupted 4. SIMalliance error in PEStatus(SGP.22 v2.2 section 2.5.6.1)

Value: 10009

ERROR_INVALID_ACTIVATION_CODE

static val ERROR_INVALID_ACTIVATION_CODE: Int

The activation code(SGP.22 v2.2 section[4.1]) is invalid.

Value: 10001

ERROR_INVALID_CONFIRMATION_CODE

static val ERROR_INVALID_CONFIRMATION_CODE: Int

The confirmation code(SGP.22 v2.2 section[4.7]) is invalid.

Value: 10002

ERROR_INVALID_PORT

static val ERROR_INVALID_PORT: Int

Failure due to target port is not supported.

Value: 10017

ERROR_INVALID_RESPONSE

static val ERROR_INVALID_RESPONSE: Int

Response format is invalid. e.g SMDP/SMDS response contains invalid json, header or/and ASN1.

Value: 10015

ERROR_NO_PROFILES_AVAILABLE

static val ERROR_NO_PROFILES_AVAILABLE: Int

No profiles available.

Value: 10013

ERROR_OPERATION_BUSY

static val ERROR_OPERATION_BUSY: Int

The operation is currently busy, try again later.

Value: 10016

ERROR_SIM_MISSING

static val ERROR_SIM_MISSING: Int

No SIM card is available in the device.

Value: 10008

ERROR_TIME_OUT

static val ERROR_TIME_OUT: Int

Timed out while waiting for an operation to complete. i.e restart, disable, switch reset etc.

Value: 10005

ERROR_UNSUPPORTED_VERSION

static val ERROR_UNSUPPORTED_VERSION: Int

The eUICC card(hardware) version is incompatible with the software

Value: 10007

EUICC_MEMORY_FIELD_UNAVAILABLE

static val EUICC_MEMORY_FIELD_UNAVAILABLE: Long

Temporary failure to retrieve available memory because eUICC is not ready.

Value: -1L

EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE

static val EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE: String

Key for an extra set on PendingIntent result callbacks providing a detailed result code.

The value of this key is an integer and contains two portions. The first byte is OperationCode and the reaming three bytes is the ErrorCode. OperationCode is the first byte of the result code and is a categorization which defines what type of operation took place when an error occurred. e.g OPERATION_DOWNLOAD means the error is related to download.Since the OperationCode only uses at most one byte, the maximum allowed quantity is 255(0xFF). ErrorCode is the remaining three bytes of the result code, and it denotes what happened. e.g a combination of OPERATION_DOWNLOAD and ERROR_TIME_OUT will suggest the download operation has timed out. The only exception here is OPERATION_SMDX_SUBJECT_REASON_CODE, where instead of ErrorCode, SubjectCode[5.2.6.1 from GSMA (SGP.22 v2.2) and ReasonCode[5.2.6.2] from GSMA (SGP.22 v2.2) are encoded. @see EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE and EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE In the case where ErrorCode contains a value of 0, it means it's an unknown error. E.g Intent only contains OPERATION_DOWNLOAD and ErrorCode is 0 implies this is an unknown Download error.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_DETAILED_CODE"

EXTRA_EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION

static val EXTRA_EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION: String

Key for an extra set on getDownloadableSubscriptionMetadata PendingIntent result callbacks providing the downloadable subscription metadata.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION"

EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE

static val EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE: String

Key for an extra set on PendingIntent result callbacks providing a ErrorCode of EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, value will be an int.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_ERROR_CODE"

EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE

static val EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE: String

Key for an extra set on PendingIntent result callbacks providing a OperationCode of EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, value will be an int.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_OPERATION_CODE"

EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE

static val EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE: String

Key for an extra set on PendingIntent result callbacks providing a ReasonCode[5.2.6.2] from GSMA (SGP.22 v2.2) decoded from EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE. The value of this extra will be a String.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE"

EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE

static val EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE: String

Key for an extra set on PendingIntent result callbacks providing a SubjectCode[5.2.6.1] from GSMA (SGP.22 v2.2) decoded from EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE. The value of this extra will be a String.

Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE"

EXTRA_USE_QR_SCANNER

static val EXTRA_USE_QR_SCANNER: String

Key for an extra set on actions ACTION_START_EUICC_ACTIVATION providing a boolean value of whether to start eSIM activation with QR scanner.

Expected type of the extra data: boolean

Value: "android.telephony.euicc.extra.USE_QR_SCANNER"

META_DATA_CARRIER_ICON

static val META_DATA_CARRIER_ICON: String

Optional meta-data attribute for a carrier app providing an icon to use to represent the carrier. If not provided, the app's launcher icon will be used as a fallback.

Value: "android.telephony.euicc.carriericon"

OPERATION_APDU

static val OPERATION_APDU: Int

The exception of failing to execute an APDU command. It can be caused by an error happening on opening the basic or logical channel, or the response of the APDU command is not success (0x9000).

Value: 8

OPERATION_DOWNLOAD

static val OPERATION_DOWNLOAD: Int

Download profile error.

Value: 5

OPERATION_EUICC_CARD

static val OPERATION_EUICC_CARD: Int

eUICC card error.

Value: 3

OPERATION_EUICC_GSMA

static val OPERATION_EUICC_GSMA: Int

eUICC returned an error defined in GSMA (SGP.22 v2.2) while running one of the ES10x functions.

Value: 7

OPERATION_HTTP

static val OPERATION_HTTP: Int

HTTP error

Value: 11

OPERATION_METADATA

static val OPERATION_METADATA: Int

Subscription's metadata error

Value: 6

OPERATION_SIM_SLOT

static val OPERATION_SIM_SLOT: Int

SIM slot error. Failed to switch slot, failed to access the physical slot etc.

Value: 2

OPERATION_SMDX

static val OPERATION_SMDX: Int

SMDX(SMDP/SMDS) error

Value: 9

OPERATION_SMDX_SUBJECT_REASON_CODE

static val OPERATION_SMDX_SUBJECT_REASON_CODE: Int

SubjectCode[5.2.6.1] and ReasonCode[5.2.6.2] error from GSMA (SGP.22 v2.2) When OPERATION_SMDX_SUBJECT_REASON_CODE is used as the EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, the remaining three bytes of the integer result from EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE will be used to stored the SubjectCode and ReasonCode from the GSMA spec and NOT ErrorCode. The encoding will follow the format of: 1. The first byte of the result will be 255(0xFF). 2. Remaining three bytes(24 bits) will be split into six sections, 4 bits in each section. 3. A SubjectCode/ReasonCode will take 12 bits each. 4. The maximum number can be represented per section is 15, as that is the maximum number allowed to be stored into 4 bits 5. Maximum supported nested category from GSMA is three layers. E.g 8.11.1.2 is not supported. E.g given SubjectCode(8.11.1) and ReasonCode(5.1) Base10: 0 10 8 11 1 0 5 1 Base2: 0000 1010 1000 1011 0001 0000 0101 0001 Base16: 0 A 8 B 1 0 5 1 Thus the integer stored in EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE is 0xA8B1051(176885841)

Value: 10

OPERATION_SWITCH

static val OPERATION_SWITCH: Int

Generic switching profile error

Value: 4

OPERATION_SYSTEM

static val OPERATION_SYSTEM: Int

Internal system error.

Value: 1

createForCardId

open fun createForCardId(cardId: Int): EuiccManager

Create a new EuiccManager object pinned to the given card ID.

deleteSubscription

open fun deleteSubscription(
    subscriptionId: Int, 
    callbackIntent: PendingIntent!
): Unit

Deletes the given subscription.

If this subscription is currently active, the device will first switch away from it onto an "empty" subscription.

Requires that the calling app has carrier privileges according to the metadata of the profile to be deleted, or the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission. Starting from Android android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM, if the caller is a device owner, profile owner, or holds the android.Manifest.permission#MANAGE_DEVICE_POLICY_MANAGED_SUBSCRIPTIONS permission, then the caller can delete a subscription that was downloaded by that caller. If such a caller tries to delete any other subscription then the operation will fail with EMBEDDED_SUBSCRIPTION_RESULT_ERROR.
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS or android.Manifest.permission#MANAGE_DEVICE_POLICY_MANAGED_SUBSCRIPTIONS

downloadSubscription

open fun downloadSubscription(
    subscription: DownloadableSubscription!, 
    switchAfterDownload: Boolean, 
    callbackIntent: PendingIntent!
): Unit

Attempt to download the given DownloadableSubscription.

Requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS or the calling app must be authorized to manage both the currently-active subscription on the current eUICC and the subscription to be downloaded according to the subscription metadata. Without the former, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download.

Starting from Android android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM, if the caller has the android.Manifest.permission#MANAGE_DEVICE_POLICY_MANAGED_SUBSCRIPTIONS permission or is a profile owner or device owner, then the downloaded subscription will be managed by that caller. In case the caller is device owner or profile owner of an organization-owned device, switchAfterDownload can be set to true to automatically enable the subscription after download. If the caller is a profile owner on non organization owned device switchAfterDownload should be false otherwise the operation will fail with EMBEDDED_SUBSCRIPTION_RESULT_ERROR.

On a multi-active SIM device, requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or a calling app only if the targeted eUICC does not currently have an active subscription or the calling app is authorized to manage the active subscription on the target eUICC, and the calling app is authorized to manage any active subscription on any SIM. Without it, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download. The caller should also be authorized to manage the subscription to be downloaded.

If device support PackageManager#FEATURE_TELEPHONY_EUICC_MEP and switchAfterDownload is true, the subscription will be enabled on an esim port based on the following selection rules:

• In SS(Single SIM) mode, if the embedded slot already has an active port, then download and enable the subscription on this port.
• 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.
• In DSDS mode, find first available port to download and enable the subscription. (see isSimPortAvailable(int))

getAvailableMemoryInBytes

open fun getAvailableMemoryInBytes(): Long

Returns the available memory in bytes of the eUICC.
Requires android.Manifest.permission#READ_PHONE_STATE or android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE or carrier privileges

getEid

open fun getEid(): String?

Returns the EID identifying the eUICC hardware.

Requires that the calling app has carrier privileges on the active subscription on the current eUICC. A calling app with carrier privileges for one eUICC may not necessarily have access to the EID of another eUICC.

getEuiccInfo

open fun getEuiccInfo(): EuiccInfo?

Returns information about the eUICC chip/device.

isEnabled

open fun isEnabled(): Boolean

Whether embedded subscriptions are currently enabled.

Even on devices with the PackageManager#FEATURE_TELEPHONY_EUICC feature, embedded subscriptions may be turned off, e.g. because of a carrier restriction from an inserted physical SIM. Therefore, this runtime check should be used before accessing embedded subscription APIs.

isSimPortAvailable

open fun isSimPortAvailable(portIndex: Int): Boolean

Returns whether the passing portIndex is available. 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.

From Android U, a port is available if it is active without an enabled profile on it or calling app can activate a new profile on the selected port without any user interaction. Always returns false if the cardId is a physical card.

startResolutionActivity

open fun startResolutionActivity(
    activity: Activity!, 
    requestCode: Int, 
    resultIntent: Intent!, 
    callbackIntent: PendingIntent!
): Unit

Start an activity to resolve a user-resolvable error.

If an operation returns EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR, this method may be called to prompt the user to resolve the issue.

This method may only be called once for a particular error.

switchToSubscription

open fun switchToSubscription(
    subscriptionId: Int, 
    callbackIntent: PendingIntent!
): Unit

Switch to (enable) the given subscription.

Requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or the calling app must be authorized to manage both the currently-active subscription and the subscription to be enabled according to the subscription metadata. Without the former, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download.

On a multi-active SIM device, requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or a calling app only if the targeted eUICC does not currently have an active subscription or the calling app is authorized to manage the active subscription on the target eUICC, and the calling app is authorized to manage any active subscription on any SIM. Without it, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download. The caller should also be authorized to manage the subscription to be enabled.

From Android T, devices might support PackageManager#FEATURE_TELEPHONY_EUICC_MEP, the subscription can be installed on different port from the eUICC. Calling apps with carrier privilege (see TelephonyManager#hasCarrierPrivileges) over the currently active subscriptions can use switchToSubscription(int,int,android.app.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:

• always use the default port 0 is eUICC does not support MEP or the apps are not targeting on Android T.
• In SS(Single SIM) mode, if the embedded slot already has an active port, then enable the subscription on this port.
• In SS mode, if the embedded slot is not active, then try to enable the subscription on the default port 0 of eUICC.
• In DSDS mode, find first available port to enable the subscription. (see isSimPortAvailable(int))

switchToSubscription

open fun switchToSubscription(
    subscriptionId: Int, 
    portIndex: Int, 
    callbackIntent: PendingIntent
): Unit

Switch to (enable) the given subscription.

Requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or the caller must be having both the carrier privileges (see TelephonyManager#hasCarrierPrivileges) over any currently active subscriptions and the subscription to be enabled according to the subscription metadata. Without the former permissions, an SecurityException is thrown.

If the caller is passing invalid port index, an EMBEDDED_SUBSCRIPTION_RESULT_ERROR with detailed error code ERROR_INVALID_PORT will be returned. The port index is invalid if one of the following requirements is met:

• index is beyond the range of UiccCardInfo#getPorts().
• In SS(Single SIM) mode, the embedded slot already has an active port with different port index.
• In DSDS mode, if the psim slot is active and the embedded slot already has an active empty port with different port index.

Depending on the target port and permission check, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR might be returned to the callback intent to prompt the user to authorize before the switch.
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS

updateSubscriptionNickname

open fun updateSubscriptionNickname(
    subscriptionId: Int, 
    nickname: String?, 
    callbackIntent: PendingIntent
): Unit

Update the nickname for the given subscription.

Requires that the calling app has carrier privileges according to the metadata of the profile to be updated, or the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission.
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS