معالجة أخطاء eUICC API

توفر واجهات برمجة تطبيقات eUICC رموز خطأ لمساعدة التطبيقات والمستخدمين على استكشاف المشكلات المتعلقة بتنزيل ملفات تعريف eSIM وتمكينها وتعطيلها وحذفها.

التعامل مع الأخطاء

عند حدوث خطأ أثناء استدعاء eUICC API، يتم توفير رد اتصال للهدف المعلق ويتم استخدام EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE كمفتاح للحصول على رمز الخطأ التفصيلي. بدءًا من Android 11، يتم تضمين المفاتيح والقيم الأربعة التالية في الهدف الناتج:

  • 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 ، اللذين يوفران معًا رمز الموضوع[5.2.6.1] ورمز السبب[5.2.6.2] من GSMA (SGP.22 v2.2). يتم ملء هذا الحقل فقط عندما يكون رمز العملية هو OPERATION_SMDX_SUBJECT_REASON_CODE .

  • EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE : يُستخدم مع EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE ، اللذين يوفران معًا رمز الموضوع[5.2.6.1] ورمز السبب[5.2.6.2] من GSMA (SGP.22 v2.2). يتم ملء هذا الحقل فقط عندما يكون رمز العملية هو OPERATION_SMDX_SUBJECT_REASON_CODE .

تسمح هذه القيم الأربع لمتصل واجهة برمجة تطبيقات 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 غير قابل للتطبيق حدث خطأ داخلي أثناء تنفيذ عملية فتحة 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 حدث خطأ في Keystore أو الشهادة عند استخدامه في اتصال 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 . رمز الموضوع[5.2.6.1] ورمز السبب[5.2.6.2] من GSMA (SGP.22 v2.2). على سبيل المثال، رمز الموضوع 8.1.1 ورمز السبب 3.8 يعني أن معرف EID مرتبط بجهاز آخر.