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

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

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

عند حدوث خطأ أثناء الاتصال بواجهة برمجة التطبيقات eUICC API، يتم تقديم callback للطلب في انتظار المراجعة و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.22 v2.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.22 v2.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 لا يُسمح بإجراء أي إجراء آخر قد يؤدي إلى تغيير حالة ملف التعريف.
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). على سبيل المثال، يعني رمز الموضوع 8.1.1 ورمز السبب 3.8 أنّ معرّف شريحة SIM المضمّنة (EID) مرتبط بجهاز آخر.