An LPA consists of two separate components (which may both be implemented in the same APK): * the LPA backend, and the LPA UI or LUI. * *
To implement the LPA backend, you must extend this class and declare this service in your * manifest file. The service must require the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission and include an intent filter * with the {@link #EUICC_SERVICE_INTERFACE} action. It's suggested that the priority of the intent * filter to be set to a non-zero value in case multiple implementations are present on the device. * See the below example. Note that there will be problem if two LPAs are present and they have the * same priority. * Example: * *
{@code
*
*
*
*
* }
*
* To implement the LUI, you must provide an activity for the following actions: * *
As with the service, each activity must require the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission. Each should have an intent * filter with the appropriate action, the {@link #CATEGORY_EUICC_UI} category, and a non-zero * priority. * *
Old implementations of EuiccService may support passing in slot IDs equal to * {@link android.telephony.SubscriptionManager#INVALID_SIM_SLOT_INDEX}, which allows the LPA to * decide which eUICC to target when there are multiple eUICCs. This behavior is not supported in * Android Q or later. * * @hide */ @SystemApi public abstract class EuiccService extends Service { private static final String TAG = "EuiccService"; /** Action which must be included in this service's intent filter. */ public static final String EUICC_SERVICE_INTERFACE = "android.service.euicc.EuiccService"; /** Category which must be defined to all UI actions, for efficient lookup. */ public static final String CATEGORY_EUICC_UI = "android.service.euicc.category.EUICC_UI"; // LUI actions. These are passthroughs of the corresponding EuiccManager actions. /** * Action used to bind the carrier app and get the activation code from the carrier app. This * activation code will be used to download the eSIM profile during eSIM activation flow. */ public static final String ACTION_BIND_CARRIER_PROVISIONING_SERVICE = "android.service.euicc.action.BIND_CARRIER_PROVISIONING_SERVICE"; /** * Intent action sent by the LPA to launch a carrier app Activity for eSIM activation, e.g. a * carrier login screen. Carrier apps wishing to support this activation method must implement * an Activity that responds to this intent action. Upon completion, the Activity must return * one of the following results to the LPA: * *
{@code Activity.RESULT_CANCELED}: The LPA should treat this as an back button and abort * the activation flow. *
{@code Activity.RESULT_OK}: The LPA should try to get an activation code from the carrier * app by binding to the carrier app service implementing * {@link #ACTION_BIND_CARRIER_PROVISIONING_SERVICE}. *
{@code Activity.RESULT_OK} with * {@link android.telephony.euicc.EuiccManager#EXTRA_USE_QR_SCANNER} set to true: The LPA should * start a QR scanner for the user to scan an eSIM profile QR code. *
For other results: The LPA should treat this as an error. **/ @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_START_CARRIER_ACTIVATION = "android.service.euicc.action.START_CARRIER_ACTIVATION"; /** * @see android.telephony.euicc.EuiccManager#ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS * The difference is this one is used by system to bring up the LUI. */ @RequiresPermission(Manifest.permission.BIND_EUICC_SERVICE) public static final String ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS = "android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS"; /** @see android.telephony.euicc.EuiccManager#ACTION_PROVISION_EMBEDDED_SUBSCRIPTION */ @RequiresPermission(Manifest.permission.BIND_EUICC_SERVICE) public static final String ACTION_PROVISION_EMBEDDED_SUBSCRIPTION = "android.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION"; /** @see android.telephony.euicc.EuiccManager#ACTION_TRANSFER_EMBEDDED_SUBSCRIPTIONS */ @RequiresPermission(Manifest.permission.BIND_EUICC_SERVICE) public static final String ACTION_TRANSFER_EMBEDDED_SUBSCRIPTIONS = "android.service.euicc.action.TRANSFER_EMBEDDED_SUBSCRIPTIONS"; /** @see android.telephony.euicc.EuiccManager#ACTION_CONVERT_TO_EMBEDDED_SUBSCRIPTION */ @RequiresPermission(Manifest.permission.BIND_EUICC_SERVICE) public static final String ACTION_CONVERT_TO_EMBEDDED_SUBSCRIPTION = "android.service.euicc.action.CONVERT_TO_EMBEDDED_SUBSCRIPTION"; /** * @see android.telephony.euicc.EuiccManager#ACTION_TOGGLE_SUBSCRIPTION_PRIVILEGED. This is * a protected intent that can only be sent by the system, and requires the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission. */ public static final String ACTION_TOGGLE_SUBSCRIPTION_PRIVILEGED = "android.service.euicc.action.TOGGLE_SUBSCRIPTION_PRIVILEGED"; /** * @see android.telephony.euicc.EuiccManager#ACTION_DELETE_SUBSCRIPTION_PRIVILEGED. This is * a protected intent that can only be sent by the system, and requires the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission. */ public static final String ACTION_DELETE_SUBSCRIPTION_PRIVILEGED = "android.service.euicc.action.DELETE_SUBSCRIPTION_PRIVILEGED"; /** * @see android.telephony.euicc.EuiccManager#ACTION_RENAME_SUBSCRIPTION_PRIVILEGED. This is * a protected intent that can only be sent by the system, and requires the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission. */ public static final String ACTION_RENAME_SUBSCRIPTION_PRIVILEGED = "android.service.euicc.action.RENAME_SUBSCRIPTION_PRIVILEGED"; /** * @see android.telephony.euicc.EuiccManager#ACTION_START_EUICC_ACTIVATION. This is * a protected intent that can only be sent by the system, and requires the * {@link android.Manifest.permission#BIND_EUICC_SERVICE} permission. */ @SdkConstant(SdkConstant.SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_START_EUICC_ACTIVATION = "android.service.euicc.action.START_EUICC_ACTIVATION"; // LUI resolution actions. These are called by the platform to resolve errors in situations that // require user interaction. // TODO(b/33075886): Define extras for any input parameters to these dialogs once they are // more scoped out. /** * Alert the user that this action will result in an active SIM being deactivated. * To implement the LUI triggered by the system, you need to define this in AndroidManifest.xml. */ public static final String ACTION_RESOLVE_DEACTIVATE_SIM = "android.service.euicc.action.RESOLVE_DEACTIVATE_SIM"; /** * Alert the user about a download/switch being done for an app that doesn't currently have * carrier privileges. */ public static final String ACTION_RESOLVE_NO_PRIVILEGES = "android.service.euicc.action.RESOLVE_NO_PRIVILEGES"; /** * Ask the user to input carrier confirmation code. * * @deprecated From Q, the resolvable errors happened in the download step are presented as * bit map in {@link #EXTRA_RESOLVABLE_ERRORS}. The corresponding action would be * {@link #ACTION_RESOLVE_RESOLVABLE_ERRORS}. */ @Deprecated public static final String ACTION_RESOLVE_CONFIRMATION_CODE = "android.service.euicc.action.RESOLVE_CONFIRMATION_CODE"; /** Ask the user to resolve all the resolvable errors. */ public static final String ACTION_RESOLVE_RESOLVABLE_ERRORS = "android.service.euicc.action.RESOLVE_RESOLVABLE_ERRORS"; /** @hide */ @Retention(RetentionPolicy.SOURCE) @IntDef(flag = true, prefix = { "RESOLVABLE_ERROR_" }, value = { RESOLVABLE_ERROR_CONFIRMATION_CODE, RESOLVABLE_ERROR_POLICY_RULES, }) public @interface ResolvableError {} /** * Possible value for the bit map of resolvable errors indicating the download process needs * the user to input confirmation code. */ public static final int RESOLVABLE_ERROR_CONFIRMATION_CODE = 1 << 0; /** * Possible value for the bit map of resolvable errors indicating the download process needs * the user's consent to allow profile policy rules. */ public static final int RESOLVABLE_ERROR_POLICY_RULES = 1 << 1; /** * Intent extra set for resolution requests containing the package name of the calling app. * This is used by the above actions including ACTION_RESOLVE_DEACTIVATE_SIM, * ACTION_RESOLVE_NO_PRIVILEGES and ACTION_RESOLVE_RESOLVABLE_ERRORS. */ public static final String EXTRA_RESOLUTION_CALLING_PACKAGE = "android.service.euicc.extra.RESOLUTION_CALLING_PACKAGE"; /** * Intent extra set for resolution requests containing the list of resolvable errors to be * resolved. Each resolvable error is an integer. Its possible values include: *
If the subscription is currently active, it should be deactivated first (equivalent to a * physical SIM being ejected). * * @param slotId ID of the SIM slot to use for the operation. * @param iccid the ICCID of the subscription to delete. * @return the result of the delete operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#deleteSubscription */ public abstract @Result int onDeleteSubscription(int slotId, String iccid); /** * Switch to the given subscription. * * @param slotId ID of the SIM slot to use for the operation. * @param iccid the ICCID of the subscription to enable. May be null, in which case the current * profile should be deactivated and no profile should be activated to replace it - this is * equivalent to a physical SIM being ejected. * @param forceDeactivateSim If true, and if an active SIM must be deactivated to access the * eUICC, perform this action automatically. Otherwise, {@link #RESULT_MUST_DEACTIVATE_SIM} * should be returned to allow the user to consent to this operation first. * @return the result of the switch operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#switchToSubscription * * @deprecated prefer {@link #onSwitchToSubscriptionWithPort(int, int, String, boolean)} */ @Deprecated public abstract @Result int onSwitchToSubscription(int slotId, @Nullable String iccid, boolean forceDeactivateSim); /** * Switch to the given subscription. * * @param slotId ID of the SIM slot to use for the operation. * @param portIndex which port on the eUICC to use * @param iccid the ICCID of the subscription to enable. May be null, in which case the current * profile should be deactivated and no profile should be activated to replace it - this is * equivalent to a physical SIM being ejected. * @param forceDeactivateSim If true, and if an active SIM must be deactivated to access the * eUICC, perform this action automatically. Otherwise, {@link #RESULT_MUST_DEACTIVATE_SIM} * should be returned to allow the user to consent to this operation first. * @return the result of the switch operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#switchToSubscription */ public @Result int onSwitchToSubscriptionWithPort(int slotId, int portIndex, @Nullable String iccid, boolean forceDeactivateSim) { // stub implementation, LPA needs to implement this throw new UnsupportedOperationException("LPA must override onSwitchToSubscriptionWithPort"); } /** * Update the nickname of the given subscription. * * @param slotId ID of the SIM slot to use for the operation. * @param iccid the ICCID of the subscription to update. * @param nickname the new nickname to apply. * @return the result of the update operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#updateSubscriptionNickname */ public abstract int onUpdateSubscriptionNickname(int slotId, String iccid, String nickname); /** * Erase all operational subscriptions on the device. * *
This is intended to be used for device resets. As such, the reset should be performed even * if an active SIM must be deactivated in order to access the eUICC. * * @param slotId ID of the SIM slot to use for the operation. * @return the result of the erase operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#eraseSubscriptions * * @deprecated From R, callers should specify a flag for specific set of subscriptions to erase * and use {@link #onEraseSubscriptions(int, int)} instead */ @Deprecated public abstract int onEraseSubscriptions(int slotId); /** * Erase specific subscriptions on the device. * *
This is intended to be used for device resets. As such, the reset should be performed even * if an active SIM must be deactivated in order to access the eUICC. * * @param slotIndex index of the SIM slot to use for the operation. * @param options flag for specific group of subscriptions to erase * @return the result of the erase operation. May be one of the predefined {@code RESULT_} * constants or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. * @see android.telephony.euicc.EuiccManager#eraseSubscriptionsWithOptions */ public int onEraseSubscriptions(int slotIndex, @ResetOption int options) { throw new UnsupportedOperationException( "This method must be overridden to enable the ResetOption parameter"); } /** * Ensure that subscriptions will be retained on the next factory reset. * *
Called directly before a factory reset. Assumes that a normal factory reset will lead to * profiles being erased on first boot (to cover fastboot/recovery wipes), so the implementation * should persist some bit that will remain accessible after the factory reset to bypass this * flow when this method is called. * * @param slotId ID of the SIM slot to use for the operation. * @return the result of the operation. May be one of the predefined {@code RESULT_} constants * or any implementation-specific code starting with {@link #RESULT_FIRST_USER}. */ public abstract int onRetainSubscriptionsForFactoryReset(int slotId); /** * Dump to a provided printWriter. */ public void dump(@NonNull PrintWriter printWriter) { printWriter.println("The connected LPA does not implement EuiccService#dump()"); } /** * Result code to string * * @param result The result code. * @return The result code in string format. * * @hide */ public static String resultToString(@Result int result) { switch (result) { case RESULT_OK: return "OK"; case RESULT_MUST_DEACTIVATE_SIM : return "MUST_DEACTIVATE_SIM"; case RESULT_RESOLVABLE_ERRORS: return "RESOLVABLE_ERRORS"; case RESULT_FIRST_USER: return "FIRST_USER"; default: return "UNKNOWN(" + result + ")"; } } /** * Wrapper around IEuiccService that forwards calls to implementations of {@link EuiccService}. */ private class IEuiccServiceWrapper extends IEuiccService.Stub { @Override public void downloadSubscription(int slotId, int portIndex, DownloadableSubscription subscription, boolean switchAfterDownload, boolean forceDeactivateSim, Bundle resolvedBundle, IDownloadSubscriptionCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { DownloadSubscriptionResult result; try { result = EuiccService.this.onDownloadSubscription( slotId, portIndex, subscription, switchAfterDownload, forceDeactivateSim, resolvedBundle); } catch (UnsupportedOperationException | AbstractMethodError e) { Log.w(TAG, "The new onDownloadSubscription(int, int, " + "DownloadableSubscription, boolean, boolean, Bundle) is not " + "implemented. Fall back to the old one.", e); result = EuiccService.this.onDownloadSubscription( slotId, subscription, switchAfterDownload, forceDeactivateSim, resolvedBundle); } try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void getEid(int slotId, IGetEidCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { String eid = EuiccService.this.onGetEid(slotId); try { callback.onSuccess(eid); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void startOtaIfNecessary( int slotId, IOtaStatusChangedCallback statusChangedCallback) { mExecutor.execute(new Runnable() { @Override public void run() { EuiccService.this.onStartOtaIfNecessary(slotId, new OtaStatusChangedCallback() { @Override public void onOtaStatusChanged(int status) { try { statusChangedCallback.onOtaStatusChanged(status); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } }); } @Override public void getOtaStatus(int slotId, IGetOtaStatusCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int status = EuiccService.this.onGetOtaStatus(slotId); try { callback.onSuccess(status); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void getDownloadableSubscriptionMetadata(int slotId, int portIndex, DownloadableSubscription subscription, boolean switchAfterDownload, boolean forceDeactivateSim, IGetDownloadableSubscriptionMetadataCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { GetDownloadableSubscriptionMetadataResult result; if (switchAfterDownload) { try { result = EuiccService.this.onGetDownloadableSubscriptionMetadata( slotId, portIndex, subscription, forceDeactivateSim); } catch (UnsupportedOperationException | AbstractMethodError e) { Log.w(TAG, "The new onGetDownloadableSubscriptionMetadata(int, int, " + "DownloadableSubscription, boolean) is not implemented." + " Fall back to the old one.", e); result = EuiccService.this.onGetDownloadableSubscriptionMetadata( slotId, subscription, forceDeactivateSim); } } else { // When switchAfterDownload is false, this operation is port agnostic. // Call API without portIndex. result = EuiccService.this.onGetDownloadableSubscriptionMetadata( slotId, subscription, forceDeactivateSim); } try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void getDefaultDownloadableSubscriptionList(int slotId, boolean forceDeactivateSim, IGetDefaultDownloadableSubscriptionListCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { GetDefaultDownloadableSubscriptionListResult result = EuiccService.this.onGetDefaultDownloadableSubscriptionList( slotId, forceDeactivateSim); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void getEuiccProfileInfoList(int slotId, IGetEuiccProfileInfoListCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { GetEuiccProfileInfoListResult result = EuiccService.this.onGetEuiccProfileInfoList(slotId); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void getEuiccInfo(int slotId, IGetEuiccInfoCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { EuiccInfo euiccInfo = EuiccService.this.onGetEuiccInfo(slotId); try { callback.onSuccess(euiccInfo); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void deleteSubscription(int slotId, String iccid, IDeleteSubscriptionCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int result = EuiccService.this.onDeleteSubscription(slotId, iccid); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void switchToSubscription(int slotId, int portIndex, String iccid, boolean forceDeactivateSim, ISwitchToSubscriptionCallback callback, boolean usePortIndex) { mExecutor.execute(new Runnable() { @Override public void run() { int result = 0; if (usePortIndex) { result = EuiccService.this.onSwitchToSubscriptionWithPort( slotId, portIndex, iccid, forceDeactivateSim); } else { result = EuiccService.this.onSwitchToSubscription( slotId, iccid, forceDeactivateSim); } try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void updateSubscriptionNickname(int slotId, String iccid, String nickname, IUpdateSubscriptionNicknameCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int result = EuiccService.this.onUpdateSubscriptionNickname(slotId, iccid, nickname); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void eraseSubscriptions(int slotId, IEraseSubscriptionsCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int result = EuiccService.this.onEraseSubscriptions(slotId); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void eraseSubscriptionsWithOptions( int slotIndex, @ResetOption int options, IEraseSubscriptionsCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int result = EuiccService.this.onEraseSubscriptions(slotIndex, options); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void retainSubscriptionsForFactoryReset(int slotId, IRetainSubscriptionsForFactoryResetCallback callback) { mExecutor.execute(new Runnable() { @Override public void run() { int result = EuiccService.this.onRetainSubscriptionsForFactoryReset(slotId); try { callback.onComplete(result); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } @Override public void dump(IEuiccServiceDumpResultCallback callback) throws RemoteException { mExecutor.execute(new Runnable() { @Override public void run() { try { final StringWriter sw = new StringWriter(); final PrintWriter pw = new PrintWriter(sw); EuiccService.this.dump(pw); callback.onComplete(sw.toString()); } catch (RemoteException e) { // Can't communicate with the phone process; ignore. } } }); } } }