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

لا تتيح لغة Kotlin استخدام الاستثناءات التي تم التحقّق منها. يؤدي ذلك إلى تبسيط عملية معالجة الأخطاء وتسهيلها، لأنّه يمكنك اختيار معالجة الاستثناءات التي يمكن استردادها فقط. وبما أنّه ليس عليك معالجة كل استثناء محتمَل بشكلٍ صريح، يصبح الرمز البرمجي أقل تشويشًا، وبالتالي يركّز بشكلٍ أكبر على غرضه الأساسي.

الأخطاء القابلة للاسترداد هي مشاكل يمكن للمطوّر حلّها من جهته. على سبيل المثال، إذا كان رقم التعريف المستخدَم في طلب غير صالح، تعرض واجهة برمجة التطبيقات HomeException مع رسالة invalid data. يمكن لمطوّر التطبيق بعد ذلك اختيار إزالة رقم التعريف هذا من ذاكرة التخزين المؤقت أو عرض رسالة للمستخدم، مثل "لم يتم العثور على البنية".

في ما يلي مثال على كيفية معالجة خطأ قابل للاسترداد:

val result =
   try {
     homeManager.requestPermissions()
   } catch (e: HomeException) {
     PermissionsResult(
       PermissionsResultStatus.ERROR,
       "Got HomeException with error: ${e.message}",
     )
   }

يمكن لأي طريقة في واجهات برمجة التطبيقات الرئيسية عرض HomeException، لذا ننصحك باستخدام كتلة try-catch لرصد HomeException في جميع الطلبات.

عند معالجة HomeException، تحقَّق من الحقلَين error.code و error.message لمعرفة المشكلة. قد تكون هناك رموز أخطاء فرعية أيضًا، لذا استدعِ الطريقة getSubErrorCodes() وتحقَّق من النتيجة.

ستؤدي أي استثناءات لم تتم معالجتها إلى تعطُّل تطبيقك.

يقدّم الجدول التالي معاني رموز HomeException التي قد تظهر لك:

الجدول: HomeException رموز

الرمز	المعنى
ABORTED	تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل فشل التحقّق من أداة التسلسل أو إلغاء المعاملة.
ALREADY_EXISTS	العنصر الذي حاول العميل إنشاءه، مثل ملف أو دليل، متوفّر مسبقًا.
API_NOT_CONNECTED	حاول العميل استدعاء طريقة من واجهة برمجة تطبيقات تعذّر الاتصال بها. يمكن أن يحدث ذلك عندما يكون الجهاز غير متصل بالإنترنت أو لا يتيح استخدام واجهة برمجة التطبيقات التي حاول العميل استدعاءها.
CANCELLED	تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل.
COMMAND_FAILED	تعذّر تنفيذ الأمر. راجِع رموز الأخطاء الفرعية لمزيد من التفاصيل.
CURSOR_WINDOW_NOT_SUPPORTED	تم استدعاء طريقة تستخدِم CursorWindow، ولكن إما أنّ CursorWindow غير مفعَّلة أو لا يمكن استخدامها في السياق الحالي.
DATA_LOSS	حدثت مشكلة في فقدان البيانات أو تلفها ويتعذّر استرجاعها.
DEADLINE_EXCEEDED	انتهت المهلة قبل أن تكتمل العملية. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح.
DECOMMISSIONING_INELIGIBLE	تعذّر إيقاف التشغيل لأنّ الجهاز غير مؤهّل لـ إيقاف التشغيل.
FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في حالة مطلوبة لتنفيذ العملية. على سبيل المثال، قد تظهر لك هذه الرسالة إذا تم استدعاء الأمر stop من OvenCavityOperationalStateTrait على فرن متوقف مسبقًا.
INTERNAL	أخطاء داخلية هذا يعني أنّه تم كسر بعض الثوابت التي يتوقّعها النظام الأساسي. رمز الخطأ هذا مخصّص للأخطاء الخطيرة.
INVALID_ARGUMENT	قدّم العميل وسيطة خارج النطاق المتوقّع لـ القيم.
INVALID_DATA_HOLDER	حامل البيانات غير صالح.
NOT_FOUND	لم يتم العثور على كيان مطلوب، مثل ملف أو دليل. إذا تم رفض طلب لفئة كاملة من المستخدمين، مثل طرح ميزة تدريجيًا أو قائمة السماح غير الموثّقة، NOT_FOUND قد يتم استخدام. إذا تم رفض طلب لبعض المستخدمين ضمن فئة من المستخدمين، مثل التحكّم في الوصول المستند إلى المستخدم، PERMISSION_DENIED يجب استخدامه.
OUT_OF_RANGE	تمت محاولة تنفيذ العملية خارج النطاق الصالح، مثل البحث أو القراءة بعد end-of-file. على عكس INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة يمكن حلّها إذا تغيّرت حالة النظام.
PERMISSION_DENIED	ليس لدى المتصل إذن لتنفيذ العملية المحدّدة. يجب عدم استخدام PERMISSION_DENIED للرفض الناتج عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED لهذه الأخطاء). يجب عدم استخدام PERMISSION_DENIED إذا تعذّر تحديد هوية المتصل (استخدِم UNAUTHENTICATED لهذه الأخطاء). لا يعني رمز الخطأ هذا أنّ الطلب صالح أو أنّ العنصر المطلوب موجود أو يستوفي الشروط المسبقة الأخرى.
RESOURCE_EXHAUSTED	تم استنفاد بعض الموارد، ربما بسبب بلوغ الحصة المخصّصة لكل مستخدم أو نفاد مساحة نظام الملفات بالكامل. على سبيل المثال، قد يتم عرض هذا الخطأ إذا تم استدعاء الأمر dispense من DispenseTrait على جهاز توزيع طعام الحيوانات الأليفة ولكن لم يتبقَّ أي طعام في الوحدة. قد يرجع ذلك أيضًا إلى تجاوز حصة مشروع في واجهات برمجة التطبيقات الرئيسية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة الحصص.
SDK_INITIALIZATION_MISSING_INFO	تمت تهيئة حزمة تطوير البرامج (SDK) بدون كل المعلومات المطلوبة. على سبيل المثال، يتم عرض هذا الخطأ إذا حاول العميل الحصول على TraitFactory لمعرّف سمة معيّن ولكن لم يتم تضمين السمة عند تهيئة حزمة تطوير البرامج (SDK). راجِع مقالة تهيئة المنزل على Android.
UNAUTHENTICATED	تعذّر تحديد هوية المتصل أو أنّ الطلب لا يتضمّن بيانات اعتماد مصادقة صالحة
UNAVAILABLE	الخدمة غير متوفّرة. من المرجّح أنّ هذه الحالة مؤقتة ويمكن تصحيحها من خلال إعادة المحاولة مع فترة تأخير. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة العمليات غير المتكرّرة.
UNIMPLEMENTED	العملية المطلوبة غير مُنفَّذة أو غير متاحة أو غير مفعَّلة في هذه الخدمة.
UNKNOWN	حدث خطأ غير معروف. UNKNOWN يظهر عند حدوث حالة خطأ لا يمكن تصنيفها باستخدام أي من رموز الأخطاء الأخرى. على سبيل المثال، قد يتم عرض هذا الخطأ عندما لا تتضمّن قيمة الحالة التي تم تلقّيها من واجهة برمجة تطبيقات خارجية معلومات كافية حول السبب الجذري.
WRITE_FAILED	تعذّر تنفيذ عملية الكتابة. راجِع رموز الأخطاء الفرعية لمزيد من التفاصيل.