مدیریت خطا در Android

Kotlin از استثناهای بررسی‌شده پشتیبانی نمی‌کند. این کار رسیدگی به خطا را ساده و کارآمد می‌کند، زیرا می‌توانید انتخاب کنید که فقط به آن دسته از استثناهایی رسیدگی کنید که به‌طور بالقوه قابل‌بازیابی هستند. و چون لازم نیست هر استثنای احتمالی را به‌طور صریح مدیریت کنید، کد شما کمتر به‌هم‌ریخته است و درنتیجه، بیشتر روی هدف اصلی خود متمرکز می‌ماند.

خطاهای قابل‌بازیابی مشکلاتی هستند که توسعه‌دهنده می‌تواند ازطرف خود به آن‌ها رسیدگی کند. برای مثال، اگر شناسه استفاده‌شده در تماس معتبر نباشد، API یک 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	کارخواه تلاش کرد روشی را از میانای برنامه‌سازی کاربردی فراخوانی کند که نتوانست متصل شود. این اتفاق زمانی می‌افتد که دستگاه آفلاین باشد یا از API که کارخواه تلاش کرده است فراخوانی کند پشتیبانی نکند.
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	کیت توسعه نرم‌افزار بدون همه اطلاعات لازم مقداردهی اولیه شده است. برای مثال، اگر کلاینت تلاش کند TraitFactory را برای شناسه ویژگی مشخصی دریافت کند اما این ویژگی هنگام مقداردهی اولیه کیت توسعه نرم‌افزار گنجانده نشده باشد، این خطا ایجاد می‌شود. راه‌اندازی خانه در Android را ببینید.
UNAUTHENTICATED	فراخواننده شناسایی نمی‌شود یا درخواست اعتبارنامه اصالت‌سنجی معتبر ندارد.
UNAVAILABLE	سرویس دردسترس نیست. این احتمالاً یک وضعیت گذرا است که می‌توان آن را با امتحان مجدد با تأخیر تصحیح کرد. توجه داشته باشید که امتحان مجدد عملیات غیریکسان‌توان همیشه ایمن نیست.
UNIMPLEMENTED	عملیات درخواستی در این سرویس پیاده‌سازی، پشتیبانی، یا فعال نشده است.
UNKNOWN	خطای ناشناس. UNKNOWN زمانی ظاهر می‌شود که شرایط خطایی رخ دهد که بااستفاده از هیچ‌کدام از کدهای خطای دیگر قابل‌طبقه‌بندی نباشد. برای مثال، این خطا ممکن است زمانی برگردانده شود که مقدار وضعیت دریافتی از یک API خارجی اطلاعات کافی درباره علت ریشه‌ای نداشته باشد.
WRITE_FAILED	نوشتن اجرا نشد. برای جزئیات بیشتر، کدهای خطای فرعی را بررسی کنید.