eUICC API提供错误代码以帮助应用和用户解决与下载、启用、禁用和删除 eSIM 配置文件相关的问题。
处理错误
当调用 eUICC API 发生错误时,会提供一个挂起的 Intent 回调,并使用EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE
作为获取详细错误码的 key。从 Android 11 开始,生成的 Intent 中包含以下四个键和值:
-
EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE
:提供有关出现问题的信息。例如,下载或删除 eSIM 配置文件。此字段永远不会为空。 EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE
:有关错误发生原因的信息。例如,请求超时或设备被运营商锁定。在以下情况下不会填充此字段:- 操作码是
OPERATION_SMDX_SUBJECT_REASON_CODE
。 - 该错误是低级错误,例如
IOException
或InterruptedException
。
- 操作码是
EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE
:与EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE
一起使用,它们一起提供来自 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。仅当操作代码为OPERATION_SMDX_SUBJECT_REASON_CODE
时才会填充此字段。EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE
:与EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE
一起使用,它们一起提供来自 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。仅当操作代码为OPERATION_SMDX_SUBJECT_REASON_CODE
时才会填充此字段。
这四个值允许 eUICC API 的调用者单独处理特定错误。以下是如何处理这些错误的示例。
int operationCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE)
int errorCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE)
String smdxSubjectCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE)
String smdxReasonCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE)
if (operationCode == OPERATION_DOWNLOAD && errorCode == ERROR_CARRIER_LOCKED) {
// handle specific error i.e tries to download but the device is carrier locked
} else if (operationCode == OPERATION_SMDX) {
// handle all SM-DP+/SM-DS errors
} else if (errorCode == ERROR_TIME_OUT) {
// handle all types of time out issues, regardless of operation.
} else if ("8.1".equals(smdxSubjectCode) && "3.1".equals(smdxReasonCode)) {
// handle specific subject code and reason code: 8.1 and 4.1 means insufficient memory.
}
支持的操作和错误代码组合
下表描述了从本地配置文件助手 (LPA) 返回的受支持的操作和错误代码组合。
操作和错误代码组合 | |||
---|---|---|---|
操作码 | 错误代码 | 描述 | |
OPERATION_SYSTEM | 不适用 | 发生了内部错误。例如,线程被中断或发生IOException 错误。 | |
OPERATION_SIM_SLOT | 不适用 | 执行 SIM 插槽操作时发生内部错误。 | |
ERROR_TIME_OUT | 尝试执行 SIM 插槽操作时超时。 | ||
ERROR_EUICC_MISSING | 设备上没有 eUICC 可用或处于活动状态。 | ||
OPERATION_EUICC_CARD | 不适用 | 执行 eUICC 操作时发生内部错误。 | |
ERROR_UNSUPPORTED_VERSION | eUICC(芯片)版本和EuiccCard(软件)版本不兼容。 | ||
ERROR_EUICC_MISSING | 设备中没有可用的 SIM 卡。例如,LPA 无法检测到 SIM 卡。 | ||
OPERATION_SMDX | 不适用 | 执行 SM-DP+/SM-DS 操作时发生内部错误。 | |
ERROR_ADDRESS_MISSING | 没有用于下载配置文件的 SM-DP+ 地址。 | ||
ERROR_INVALID_CONFIRMATION_CODE | 解析激活码时出错(格式无效)。 | ||
ERROR_CERTIFICATE_ERROR | 用于 TLS 连接进行验证时出现密钥库或证书错误。 | ||
ERROR_NO_PROFILES_AVAILABLE | SM-DP+ 没有可用的配置文件。 | ||
ERROR_CONNECTION_ERROR | 无法创建与服务器的连接。 | ||
ERROR_INVALID_RESPONSE | 来自 SM-DP+/SM-DS 服务器的无效响应。 | ||
OPERATION_SWITCH | 不适用 | 执行开关操作时发生内部错误。 | |
ERROR_CARRIER_LOCKED | 不允许切换配置文件,因为设备已被运营商锁定(SIM 卡锁定)。 | ||
OPERATION_DOWNLOAD | 不适用 | 执行下载操作时发生内部错误。 | |
ERROR_DISALLOWED_BY_PPR | eUICC 上的规则授权表为空或配置文件策略规则不允许下载。 | ||
ERROR_INVALID_ACTIVATION_CODE | 解析激活码(格式无效)或尝试在没有激活码的情况下下载时出错。 | ||
ERROR_CARRIER_LOCKED | 不允许下载,因为该设备已被运营商锁定(SIM 卡锁定)。 | ||
ERROR_INCOMPATIBLE_CARRIER | 运营商在黑名单中,LPA 无法从 SM-DP+/SM-DS 下载配置文件。 | ||
ERROR_OPERATION_BUSY | 配置文件下载正在进行中,不允许任何其他可能触发 SIM 状态更改的操作。 | ||
OPERATION_METADATA | 不适用 | 执行元数据操作时发生内部错误。 | |
ERROR_INVALID_ACTIVATION_CODE | 订阅元数据为空或订阅元数据中的激活码为空或无效。 | ||
ERROR_INCOMPATIBLE_CARRIER | 运营商在黑名单中,LPA 无法从 SM-DP+/SM-DS 下载该运营商的配置文件。 | ||
OPERATION_EUICC_GSMA | 不适用 | 执行 eUICC GSMA 操作时发生内部错误。 | |
ERROR_INSTALL_PROFILE | 尝试安装配置文件时出现 eUICC 错误。例如,配置文件已存在或 ICCID 不匹配。 | ||
ERROR_EUICC_INSUFFICIENT_MEMORY | 尝试安装配置文件时出现 eUICC 错误。 eUICC 内存不足。 | ||
ERROR_DISALLOWED_BY_PPR | 尝试安装配置文件时出现 eUICC 错误。配置文件策略规则不允许。 | ||
OPERATION_APDU | 不适用 | 执行 APDU 操作时发生内部错误。 | |
OPERATION_HTTP | 1-999 | 错误代码是 HTTP 错误值。 | |
操作码 | 主题代码 | 原因码 | 描述 |
OPERATION_SMDX_SUBJECT_REASON_CODE | 字符串包含由点分隔的 3 位数字,没有前导零。例如, 8.1.1 。 | 字符串包含由点分隔的 3 位数字,没有前导零。例如, 3.8 。 | 来自 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。例如,SubjectCode 为8.1.1 和 ReasonCode 为3.8 表示 EID 绑定到另一个设备。 |