التعامل مع أخطاء واجهة برمجة التطبيقات eUICC

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

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

عند حدوث خطأ أثناء طلب بيانات من واجهة برمجة تطبيقات eUICC، يتم تقديم معاودة الاتصال بـ PendingIntent ويتم استخدام 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، وهما معًا توفّران SubjectCode[5.2.6.1] وReasonCode[5.2.6.2] من GSMA (SGP.22 الإصدار 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.22 الإصدار 2.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.