رسیدگی به خطاهای eUICC API

APIهای eUICC کدهای خطا را برای کمک به برنامه‌ها و کاربران در رفع مشکلات مربوط به دانلود، فعال کردن، غیرفعال کردن و حذف نمایه‌های eSIM ارائه می‌کنند.

رسیدگی به خطاها

هنگامی که هنگام فراخوانی API eUICC خطایی رخ می دهد، یک تماس با هدف معلق ارائه می شود و EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE به عنوان کلید برای دریافت کد خطای دقیق استفاده می شود. با شروع از Android 11، چهار کلید و مقدار زیر در هدف حاصل گنجانده شده است:

  • EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE : اطلاعاتی را در مورد اشتباهی ارائه می دهد. به عنوان مثال، دانلود یا حذف یک نمایه eSIM. این فیلد هرگز خالی نیست.

  • EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE : اطلاعاتی در مورد دلیل رخ دادن خطا. به عنوان مثال، زمان درخواست به پایان رسیده است یا دستگاه شرکت مخابراتی قفل شده است. این فیلد در موارد زیر پر نمی شود:

  • EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE : با EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE استفاده می شود که با هم SubjectCode[5.2.6.1] و ReasonCode[5.2.6.2] از GSMA (SGP.2.2) را ارائه می دهند. این فیلد فقط زمانی پر می شود که کد عملیات OPERATION_SMDX_SUBJECT_REASON_CODE باشد.

  • EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE : با EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE استفاده می شود که با هم SubjectCode[5.2.6.1] و ReasonCode[5.2.6.2] از GSMA (SGP.2.2) را ارائه می کنند. این فیلد فقط زمانی پر می شود که کد عملیات OPERATION_SMDX_SUBJECT_REASON_CODE باشد.

این چهار مقدار به تماس گیرنده API eUICC اجازه می دهد تا خطاهای خاص را به صورت جداگانه مدیریت کند. در زیر مثالی از نحوه رسیدگی به این خطاها آورده شده است.

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 قابل اجرا نیست یک خطای داخلی در حین انجام عملیات اسلات سیم کارت رخ داد.
ERROR_TIME_OUT در حین تلاش برای انجام عملیات شیار سیم کارت، زمان تمام شد.
ERROR_EUICC_MISSING هیچ eUICC در دستگاه موجود یا فعال نیست.
OPERATION_EUICC_CARD قابل اجرا نیست هنگام انجام عملیات eUICC یک خطای داخلی روی داد.
ERROR_UNSUPPORTED_VERSION نسخه eUICC (تراشه) و نسخه EuiccCard (نرم افزار) سازگار نیستند.
ERROR_EUICC_MISSING سیم کارتی در دستگاه موجود نیست. به عنوان مثال، LPA نمی تواند سیم کارت را تشخیص دهد.
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 تغییر نمایه مجاز نیست زیرا دستگاه شرکت مخابراتی قفل است (سیم کارت قفل شده است).
OPERATION_DOWNLOAD قابل اجرا نیست هنگام انجام عملیات دانلود، یک خطای داخلی روی داد.
ERROR_DISALLOWED_BY_PPR جدول مجوز قوانین در eUICC خالی است یا بارگیری توسط قانون خط مشی نمایه مجاز نیست.
ERROR_INVALID_ACTIVATION_CODE هنگام تجزیه کد فعال‌سازی (قالب نامعتبر) یا تلاش برای دانلود بدون کد فعال‌سازی، خطایی روی داد.
ERROR_CARRIER_LOCKED دانلود مجاز نیست زیرا دستگاه شرکت مخابراتی قفل است (سیم کارت قفل شده است).
ERROR_INCOMPATIBLE_CARRIER شرکت مخابراتی در لیست سیاه است و LPA نمی‌تواند نمایه‌ای را از SM-DP+/SM-DS بارگیری کند.
ERROR_OPERATION_BUSY دانلود نمایه در حال انجام است و هیچ اقدام دیگری که می تواند باعث تغییر وضعیت سیم کارت شود مجاز نیست.
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 . SubjectCode[5.2.6.1] و ReasonCode[5.2.6.2] از GSMA (SGP.22 v2.2). به عنوان مثال، SubjectCode 8.1.1 و ReasonCode 3.8 به این معنی است که EID به دستگاه دیگری متصل است.