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

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

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

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

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

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

عند التعامل مع HomeException، تحقّق من الحقلين code وmessage لمعرفة سبب الخطأ.

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

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

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

الرمز	المعنى
ABORTED	تم إلغاء العملية. يظهر هذا الخطأ عادةً عند حدوث مشكلة في المعالجة المتزامنة، مثل تعذُّر التحقّق من التسلسل أو إجهاض المعاملة.
ALREADY_EXISTS	المورد أو الكيان الذي تحاول إنشاؤه موجودان من قبل. يمكن أن يكون ذلك، على سبيل المثال، جدولاً زمنيًا مُسمّى لجهاز ترموستات.
API_NOT_CONNECTED	حاول العميل استدعاء طريقة من واجهة برمجة تطبيقات تعذّر الاتصال بها. يمكن أن يحدث ذلك عندما يكون الجهاز غير متصل بالإنترنت أو لا يتوافق مع واجهة برمجة التطبيقات التي تحاول الاتصال بها.
CANCELLED	تم إلغاء العملية، عادةً من قِبل المتصل.
DATA_LOSS	فقدان البيانات أو تلفها بشكل لا يمكن استعادته
DEADLINE_EXCEEDED	انتهت المهلة قبل اكتمال العملية. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح.
FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذ العملية. على سبيل المثال، قد تظهر لك هذه الرسالة إذا اتصلت برقم stop على فرن سبق أن توقّف.
INTERNAL	الأخطاء الداخلية وهذا يعني أنّه تمّ انتهاك بعض الشروط الثابتة التي يتوقعها النظام الأساسي. تم حجز رمز الخطأ هذا لحالات الأخطاء الخطيرة.
INVALID_ARGUMENT	لقد قدّمت مَعلمة خارج النطاق المتوقّع للقيم.
NOT_FOUND	حدّدت كيانًا أو موردًا لا يمكن العثور عليه. على سبيل المثال، تحديد معرّف مقطع صوتي غير متوفّر عند استدعاء activateAudioTrack على جهاز مشغّل وسائط
OUT_OF_RANGE	تجاوزت إحدى المَعلمات النطاق الصالح، استنادًا إلى حالة النظام الحالية. تظهر هذه الرسالة عندما تكون القيمة ضمن نطاق القيم التي يمكن أن تقبلها طلب البيانات من واجهة برمجة التطبيقات، ولكنّها لا تُمثّل معنىً في السياق الحالي.
PERMISSION_DENIED	ليس لديك الإذن بتنفيذ العملية المحدّدة. يجب عدم تفسير رمز الخطأ هذا على أنّه يعني أنّ الطلب صالح بخلاف ذلك.
RESOURCE_EXHAUSTED	تم استنفاد بعض الموارد. على سبيل المثال، يمكن أن يتم طرح هذا الحدث عندما يتصل أحد الأشخاص dispense على جهاز إطعام الحيوانات الأليفة ولا يتوفّر المزيد من الطعام في الوحدة.
SDK_INITIALIZATION_MISSING_INFO	لم يتم إعداد حزمة تطوير البرامج (SDK) بالكامل. على سبيل المثال، ستظهر لك هذه الرسالة إذا حاولت الحصول على TraitFactory لسمة لم يتم تسجيلها. اطّلِع على الإعداد.
UNAUTHENTICATED	لا يمكن تحديد هوية المتصل أو لا يتضمّن الطلب بيانات اعتماد مصادقة válida.
UNAVAILABLE	الخدمة غير متاحة. من المرجّح أن يكون هذا ناتجًا عن حالة عابرة يمكن تصحيحها من خلال إعادة المحاولة مع الانتظار. يُرجى العِلم أنّه قد لا يكون من الآمن دائمًا إعادة محاولة العمليات غير الثابتة.
UNIMPLEMENTED	لم يتم تنفيذ العملية المطلوبة أو تفعيلها أو إتاحتها في هذه الخدمة.
UNKNOWN	حدث خطأ غير معروف. بشكل عام، يظهر الرمز UNKNOWN عند حدوث خطأ لا يمكن تصنيفه باستخدام أي من رموز الخطأ الأخرى. على سبيل المثال، قد يتم عرض هذا الخطأ عند تلقّي قيمة حالة من واجهة برمجة تطبيقات خارجية لا تتضمّن معلومات كافية عن السبب الأساسي.