محیط زیست 

interface EnvironmentClient

کلاینت برای دسترسی به API های مرتبط با محیط.

برای ایجاد یک نمونه از EnvironmentClientFactory استفاده کنید.

خلاصه

کارکردهای عمومی

suspend Environment

Environment برمی‌گرداند.

ListenableFuture < Environment >

Environment برمی‌گرداند.

suspend PrepareEnvironmentResponse
prepareEnvironment (
request: PrepareEnvironmentRequest ,
notificationServiceComponentName: ComponentName ?
)

با اطمینان از نصب و آماده بودن برنامه Android Device Policy، دستگاه را آماده می‌کند.

ListenableFuture < PrepareEnvironmentResponse >
prepareEnvironmentAsync (
request: PrepareEnvironmentRequest ,
notificationServiceComponentName: ComponentName ?
)

با اطمینان از نصب و آماده بودن برنامه Android Device Policy، دستگاه را آماده می‌کند.

کارکردهای عمومی

محیط زیست را دریافت کنید 

suspend fun getEnvironment(request: GetEnvironmentRequest): Environment

Environment برمی‌گرداند. به فراخواننده کمک می‌کند تا بداند آیا محیط آماده است یا خیر.

پرتاب‌ها
com.google.android.managementapi.common.exceptions.InvalidArgumentException

اگر نقش‌های درخواستی معتبر نباشند.

com.google.android.managementapi.common.exceptions.InternalException

اگر تماس به دلیل خطای داخلی ناموفق بود.

com.google.android.managementapi.common.exceptions.ApiLevelException

اگر سطح API SDK دستگاه برای برخی از نقش‌های درخواستی کافی نباشد (این ممکن است علاوه بر حداقل سطح API مورد نیاز برای خود فراخوانی باشد). {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} به API سطح ۲۳ یا بالاتر نیاز دارد. سایر نقش‌ها به API سطح ۲۸ یا بالاتر نیاز دارند.

دریافت محیط بدون همگام‌سازی 

fun getEnvironmentAsync(request: GetEnvironmentRequest): ListenableFuture<Environment>

Environment برمی‌گرداند. به فراخواننده کمک می‌کند تا بداند آیا محیط آماده است یا خیر.

بازگشت‌ها
ListenableFuture < Environment >

یک ListenableFuture که نتیجه را در بر می‌گیرد. این می‌تواند به صورت زیر باشد:

  • در صورت موفقیت، آینده‌ای موفق که یک Environment را در بر می‌گیرد.

  • یک خطای آینده ناموفق که در صورت معتبر نبودن نقش‌های درخواستی، یک InvalidArgumentException را پوشش می‌دهد.

  • یک تابع آینده ناموفق که یک InternalException را در بر می‌گیرد، اگر فراخوانی به دلیل خطای داخلی ناموفق باشد.

پرتاب‌ها
com.google.android.managementapi.common.exceptions.ApiLevelException

اگر سطح API SDK دستگاه برای برخی از نقش‌های درخواستی کافی نباشد (این ممکن است علاوه بر حداقل سطح API مورد نیاز برای خود فراخوانی باشد). {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} به API سطح ۲۳ یا بالاتر نیاز دارد. سایر نقش‌ها به API سطح ۲۸ یا بالاتر نیاز دارند.

آماده‌سازی محیط 

suspend fun prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): PrepareEnvironmentResponse

با اطمینان از نصب و آماده بودن برنامه Android Device Policy، دستگاه را آماده می‌کند.

رفتار به زمینه بستگی دارد:

  • جریان اعتماد دستگاه : اگر برنامه سیاست دستگاه اندروید نصب نشده باشد، از کاربر درخواست نصب می‌کند. اگر برنامه از قبل نصب شده باشد، به‌طور مخفیانه به‌روزرسانی می‌شود.

  • روند ثبت‌نام دستگاه: اگر برنامه‌ی سیاست دستگاه اندروید از قبل نصب نشده باشد، به‌طور مخفیانه آن را نصب می‌کند و بدون تعامل کاربر، از آماده بودن آن برای استفاده اطمینان حاصل می‌کند.

پارامترها
notificationServiceComponentName: ComponentName ?

ComponentName سرویسی که NotificationReceiverService گسترش می‌دهد. در صورت ارائه، باید یک کامپوننت معتبر متعلق به برنامه فراخوانی شده باشد و در مانیفست صادر شود. برای اطلاع از رویدادهای آماده‌سازی محیط، باید:

  1. رابط EnvironmentListener را در برنامه خود پیاده‌سازی کنید.

  2. یک پیاده‌سازی برای نحوه مدیریت رویدادهای دریافتی ارائه دهید.

  3. سرویس NotificationReceiverService را بسط داده و یک نمونه EnvironmentListener ارائه دهید.

  4. کلاس توسعه‌یافته‌ی NotificationReceiverService را به AndroidManifest.xml خود اضافه کنید و مطمئن شوید که خروجی گرفته شده است.

برای مثال:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
بازگشت‌ها
PrepareEnvironmentResponse

PrepareEnvironmentResponse حاوی جزئیاتی در مورد وضعیت نهایی آماده‌سازی محیط.

پرتاب‌ها
com.google.android.managementapi.common.exceptions.InvalidArgumentException

اگر:

  • ‎[notificationServiceComponentName] یک کامپوننت معتبر متعلق به برنامه فراخوانی کننده نیست یا در مانیفست صادر نشده است.
  • نقش‌های درخواستی شامل {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} می‌شود و {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} ارائه نشده یا از {@code android.app.admin.DeviceAdminReceiver} ارث‌بری نمی‌کند.
  • نقش‌های درخواستی معتبر نیستند.
java.lang.SecurityException

اگر تماس گیرنده مجاز به فراخوانی این API نباشد.

com.google.android.managementapi.environment.GooglePlayServicesAppNotUpdatedException

اگر سرویس‌های گوگل پلی به‌روز نباشند.

com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateUnrecoverableException

اگر نصب یا به‌روزرسانی Android Device Policy با شکست مواجه شود و خطا غیرقابل بازیابی باشد.

com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateRecoverableException

اگر برنامه Android Device Policy نصب یا به‌روزرسانی نشود و خطا قابل بازیابی باشد (مثلاً درخواست به دلیل مشکلات گذرای شبکه ناموفق بود)، می‌توان درخواست را دوباره امتحان کرد.

com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDeclinedException

اگر کاربر از نصب برنامه Android Device Policy خودداری کند.

com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDismissedException

اگر کاربر صفحه رضایت نصب را رد کند.

com.google.android.managementapi.common.exceptions.InternalException

اگر تماس به دلیل خطای داخلی ناموفق بود.

com.google.android.managementapi.environment.PlayStoreUpdateUnrecoverableException

اگر به‌روزرسانی فروشگاه پلی‌استور ناموفق بود.

com.google.android.managementapi.common.exceptions.ApiLevelException

اگر سطح API SDK دستگاه برای برخی از نقش‌های درخواستی کافی نباشد (این ممکن است علاوه بر حداقل سطح API مورد نیاز برای خود فراخوانی باشد). {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} به API سطح ۲۳ یا بالاتر نیاز دارد. سایر نقش‌ها به API سطح ۲۸ یا بالاتر نیاز دارند.

آماده‌سازی محیط‌زیست‌همگام‌سازی 

fun prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): ListenableFuture<PrepareEnvironmentResponse>

با اطمینان از نصب و آماده بودن برنامه Android Device Policy، دستگاه را آماده می‌کند.

رفتار به زمینه بستگی دارد:

  • جریان اعتماد دستگاه : اگر برنامه سیاست دستگاه اندروید نصب نشده باشد، از کاربر درخواست نصب می‌کند. اگر برنامه از قبل نصب شده باشد، به‌طور مخفیانه به‌روزرسانی می‌شود.

  • روند ثبت‌نام دستگاه: اگر برنامه‌ی سیاست دستگاه اندروید از قبل نصب نشده باشد، به‌طور مخفیانه آن را نصب می‌کند و بدون تعامل کاربر، از آماده بودن آن برای استفاده اطمینان حاصل می‌کند.

پارامترها
notificationServiceComponentName: ComponentName ?

ComponentName سرویسی که NotificationReceiverService گسترش می‌دهد. در صورت ارائه، باید یک کامپوننت معتبر متعلق به برنامه فراخوانی شده باشد و در مانیفست صادر شود. برای اطلاع از رویدادهای آماده‌سازی محیط، باید:

  1. رابط EnvironmentListener را در برنامه خود پیاده‌سازی کنید.

  2. یک پیاده‌سازی برای نحوه مدیریت رویدادهای دریافتی ارائه دهید.

  3. سرویس NotificationReceiverService را بسط داده و یک نمونه EnvironmentListener ارائه دهید.

  4. کلاس توسعه‌یافته‌ی NotificationReceiverService را به AndroidManifest.xml خود اضافه کنید و مطمئن شوید که خروجی گرفته شده است.

برای مثال:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
بازگشت‌ها
ListenableFuture < PrepareEnvironmentResponse >

یک ListenableFuture که نتیجه را در بر می‌گیرد. این می‌تواند باشد

  • آینده‌ای موفق که یک PrepareEnvironmentResponse حاوی جزئیاتی درباره وضعیت نهایی آماده‌سازی محیط را در بر می‌گیرد.

  • یک خطای آینده‌نگر ناموفق که یک InvalidArgumentException را پوشش می‌دهد اگر:

    • ‎[notificationServiceComponentName] یک کامپوننت معتبر متعلق به برنامه فراخوانی کننده نیست یا در مانیفست صادر نشده است.
    • نقش‌های درخواستی معتبر نیستند.
    • نقش‌های درخواستی شامل {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} می‌شود و {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} ارائه نشده یا از {@code android.app.admin.DeviceAdminReceiver} ارث‌بری نمی‌کند.

  • یک خطای آینده‌ی ناموفق که شامل یک SecurityException می‌شود، اگر تماس‌گیرنده مجاز به فراخوانی این API نباشد.

  • اگر سرویس‌های گوگل پلی به‌روز نباشند، خطای GooglePlayServicesAppNotUpdatedException در آینده‌ی ناموفق رخ می‌دهد.

  • اگر نصب یا به‌روزرسانی خط‌مشی دستگاه اندروید با شکست مواجه شود و خطا غیرقابل بازیابی باشد، خطای AndroidDevicePolicyInstallOrUpdateUnrecoverableException در آینده‌ای ناموفق رخ می‌دهد.

  • یک خطای آینده ناموفق که در صورت عدم موفقیت نصب یا به‌روزرسانی برنامه خط‌مشی دستگاه AndroidDevicePolicyInstallOrUpdateRecoverableException و قابل بازیابی بودن خطا (مثلاً درخواست به دلیل مشکلات گذرای شبکه ناموفق بود) رخ می‌دهد، بنابراین درخواست می‌تواند دوباره امتحان شود.

  • یک خطای آینده‌نگر ناموفق که در صورت عدم پذیرش نصب برنامه‌ی Android Device Policy توسط کاربر، خطای AndroidDevicePolicyInstallConsentDeclinedException را نمایش می‌دهد.

  • یک خطای آینده‌ی ناموفق که در صورت رد شدن صفحه‌ی رضایت نصب توسط کاربر، خطای AndroidDevicePolicyInstallConsentDismissedException را نمایش می‌دهد.

  • یک تابع آینده ناموفق که یک InternalException را در بر می‌گیرد، اگر فراخوانی به دلیل خطای داخلی ناموفق باشد.

  • یک خطای آینده‌ی ناموفق که در صورت عدم موفقیت به‌روزرسانی فروشگاه پلی، خطای PlayStoreUpdateUnrecoverableException را در خود جای می‌دهد.

پرتاب‌ها
com.google.android.managementapi.common.exceptions.ApiLevelException

اگر سطح API SDK دستگاه برای برخی از نقش‌های درخواستی کافی نباشد. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} به API سطح ۲۳ یا بالاتر نیاز دارد. سایر نقش‌ها به API سطح ۲۸ یا بالاتر نیاز دارند.