eUICC API提供錯誤代碼,以協助應用程式和使用者解決與下載、啟用、停用和刪除 eSIM 設定檔相關的問題。
處理錯誤
當呼叫 eUICC API 時發生錯誤時,會提供待處理的 Intent 回調,並使用EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE
作為取得詳細錯誤代碼的鍵。從 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[2.ason.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[2.ason.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) 的主題代碼 [5.2.6.1] 和原因代碼 [5.2.6.2]。例如,SubjectCode 為8.1.1 ,ReasonCode 為3.8 表示 EID 已綁定到另一個裝置。 |