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

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

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

في ما يلي مثال على كيفية التعامل مع خطأ يمكن إصلاحه:

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

يمكن لأي طريقة في Home APIs أن تؤدي إلى ظهور 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 إلى جهاز لإطعام الحيوانات الأليفة ولكن لم يعد هناك طعام في الجهاز. قد يرجع ذلك أيضًا إلى تجاوز حصة مشروع Home APIs. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة الحصص.
SDK_INITIALIZATION_MISSING_INFO	تمت تهيئة حزمة تطوير البرامج (SDK) بدون توفير جميع المعلومات المطلوبة. على سبيل المثال، يظهر هذا الخطأ إذا حاول العميل الحصول على TraitFactory لمعرّف سمة معيّن ولكن لم يتم تضمين السمة عند إعداد حزمة تطوير البرامج (SDK). يُرجى الاطّلاع على تهيئة المنزل على Android.
UNAUTHENTICATED	لا يمكن تحديد هوية المتصل أو لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة.
UNAVAILABLE	الخدمة غير متوفّرة. على الأرجح أنّ هذه الحالة مؤقتة ويمكن تصحيحها من خلال إعادة المحاولة مع استخدام فترة انتظار. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة تنفيذ العمليات غير المتكررة.
UNIMPLEMENTED	لم يتم تنفيذ العملية المطلوبة أو إتاحتها أو تفعيلها في هذه الخدمة.
UNKNOWN	حدث خطأ غير معروف. يظهر الرمز UNKNOWN عند حدوث حالة خطأ لا يمكن تصنيفها باستخدام أي من رموز الخطأ الأخرى. على سبيل المثال، قد يظهر هذا الخطأ عندما لا تتضمّن قيمة الحالة التي تم تلقّيها من واجهة برمجة تطبيقات خارجية معلومات كافية حول السبب الأساسي.
WRITE_FAILED	تعذّر تنفيذ عملية الكتابة. يُرجى الاطّلاع على رموز الخطأ الفرعية لمزيد من التفاصيل.