محیط زیست 

public interface EnvironmentClient

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

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

خلاصه

روش‌های عمومی

abstract @ NonNull Environment

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

abstract @ NonNull ListenableFuture <@ NonNull Environment >

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

abstract @ NonNull PrepareEnvironmentResponse
prepareEnvironment (
@ NonNull PrepareEnvironmentRequest request,
ComponentName notificationServiceComponentName
)

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

abstract @ NonNull ListenableFuture <@ NonNull PrepareEnvironmentResponse >
prepareEnvironmentAsync (
@ NonNull PrepareEnvironmentRequest request,
ComponentName notificationServiceComponentName
)

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

روش‌های عمومی

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

abstract @NonNull Environment getEnvironment(@NonNull GetEnvironmentRequest request)

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 سطح ۲۸ یا بالاتر نیاز دارند.

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

abstract @NonNull ListenableFuture<@NonNull Environment> getEnvironmentAsync(@NonNull GetEnvironmentRequest request)

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

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

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

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

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

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

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

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

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

abstract @NonNull PrepareEnvironmentResponse prepareEnvironment(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

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

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

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

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

پارامترها
ComponentName notificationServiceComponentName

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()
  }
}
بازگشت‌ها
@ NonNull 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 سطح ۲۸ یا بالاتر نیاز دارند.

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

abstract @NonNull ListenableFuture<@NonNull PrepareEnvironmentResponse> prepareEnvironmentAsync(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

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

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

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

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

پارامترها
ComponentName notificationServiceComponentName

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()
  }
}
بازگشت‌ها
@ NonNull ListenableFuture <@ NonNull 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 سطح ۲۸ یا بالاتر نیاز دارند.