EnvironmentClient

interface EnvironmentClient

क्लाइंट को एनवायरमेंट से जुड़ी एपीआई ऐक्सेस करने की अनुमति देता है.

इंस्टेंस बनाने के लिए 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 ऐप्लिकेशन इंस्टॉल हो और इस्तेमाल के लिए तैयार हो.

पब्लिक फ़ंक्शन

getEnvironment

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

अगर डिवाइस का एसडीके एपीआई लेवल, अनुरोध की गई कुछ भूमिकाओं के लिए ज़रूरी शर्तों को पूरा नहीं करता है. ऐसा कॉल के लिए, सामान्य तौर पर एपीआई लेवल की ज़रूरी शर्त के अलावा भी हो सकता है. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} के लिए, एपीआई लेवल 23 या उसके बाद का वर्शन ज़रूरी है. अन्य भूमिकाओं के लिए, एपीआई लेवल 28 या उसके बाद का वर्शन ज़रूरी है.

getEnvironmentAsync

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

Environment दिखाता है. इससे कॉल करने वाले व्यक्ति को यह पता चलता है कि एनवायरमेंट तैयार है या नहीं.

रिटर्न
ListenableFuture<Environment>

नतीजे को रैप करने वाला ListenableFuture. यह स्थिति हो सकती है:

  • अगर ऑपरेशन पूरा हो जाता है, तो Environment रैप करने वाला एक फ़्यूचर.

  • अगर अनुरोध की गई भूमिकाएं मान्य नहीं हैं, तो InvalidArgumentException को रैप करने वाला फ़्यूचर पूरा नहीं होगा.

  • अगर किसी अंदरूनी गड़बड़ी की वजह से कॉल पूरा नहीं हो सका, तो InternalException को रैप करने वाला फ़ेल हुआ फ़्यूचर.
थ्रो
com.google.android.managementapi.common.exceptions.ApiLevelException

अगर डिवाइस का एसडीके एपीआई लेवल, अनुरोध की गई कुछ भूमिकाओं के लिए ज़रूरी शर्तों को पूरा नहीं करता है. ऐसा कॉल के लिए, सामान्य तौर पर एपीआई लेवल की ज़रूरी शर्त के अलावा भी हो सकता है. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} के लिए, एपीआई लेवल 23 या उसके बाद का वर्शन ज़रूरी है. अन्य भूमिकाओं के लिए, एपीआई लेवल 28 या उसके बाद का वर्शन ज़रूरी है.

prepareEnvironment

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

यह डिवाइस को तैयार करता है. इसके लिए, यह पक्का करता है कि Android Device Policy ऐप्लिकेशन इंस्टॉल हो और इस्तेमाल के लिए तैयार हो.

यह कॉन्टेक्स्ट के हिसाब से तय होता है:

  • डिवाइस ट्रस्ट फ़्लो: अगर Android Device Policy ऐप्लिकेशन इंस्टॉल नहीं है, तो उपयोगकर्ता को इसे इंस्टॉल करने के लिए कहा जाता है. अगर ऐप्लिकेशन पहले से इंस्टॉल है, तो उसे साइलेंट मोड में अपडेट किया जाता है.

  • डिवाइस रजिस्ट्रेशन फ़्लो: अगर Android Device Policy ऐप्लिकेशन पहले से इंस्टॉल नहीं है, तो यह उसे साइलेंट मोड में इंस्टॉल करता है. साथ ही, यह पक्का करता है कि उपयोगकर्ता के इंटरैक्शन के बिना ही, ऐप्लिकेशन इस्तेमाल के लिए तैयार हो.

पैरामीटर
notificationServiceComponentName: ComponentName?

ComponentName की सेवा NotificationReceiverService तक जारी रहेगी. अगर यह जानकारी दी जाती है, तो यह कॉल करने वाले ऐप्लिकेशन का मान्य कॉम्पोनेंट होना चाहिए. साथ ही, इसे मेनिफ़ेस्ट में एक्सपोर्ट किया गया हो. एनवायरमेंट तैयार करने से जुड़े इवेंट की सूचना पाने के लिए, आपको ये काम करने होंगे:

  1. अपने ऐप्लिकेशन में EnvironmentListener इंटरफ़ेस लागू करें.

  2. मिले हुए इवेंट को मैनेज करने का तरीका लागू करें.

  3. NotificationReceiverService को बढ़ाएं और EnvironmentListener इंस्टेंस उपलब्ध कराएं.

  4. अपनी AndroidManifest.xml फ़ाइल में, एक्सटेंड की गई NotificationReceiverService क्लास जोड़ें. साथ ही, यह पक्का करें कि इसे एक्सपोर्ट किया गया हो.

उदाहरण के लिए:

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

अगर कॉलर को इस एपीआई को कॉल करने की अनुमति नहीं है.
com.google.android.managementapi.environment.GooglePlayServicesAppNotUpdatedException

अगर Google Play services अप-टू-डेट नहीं है.
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

अगर Play Store अपडेट नहीं हो पाया है.
com.google.android.managementapi.common.exceptions.ApiLevelException

अगर डिवाइस के एसडीके का एपीआई लेवल, अनुरोध की गई कुछ भूमिकाओं के लिए ज़रूरी शर्तों को पूरा नहीं करता है. ऐसा कॉल के लिए, एपीआई लेवल की सामान्य ज़रूरी शर्तों के अलावा भी हो सकता है. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} के लिए, एपीआई लेवल 23 या इससे ऊपर का लेवल होना ज़रूरी है. अन्य भूमिकाओं के लिए, एपीआई लेवल 28 या उसके बाद का वर्शन ज़रूरी है.

prepareEnvironmentAsync

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

यह डिवाइस को तैयार करता है. इसके लिए, यह पक्का करता है कि Android Device Policy ऐप्लिकेशन इंस्टॉल हो और इस्तेमाल के लिए तैयार हो.

यह कॉन्टेक्स्ट के हिसाब से तय होता है:

  • डिवाइस ट्रस्ट फ़्लो: अगर Android Device Policy ऐप्लिकेशन इंस्टॉल नहीं है, तो उपयोगकर्ता को इसे इंस्टॉल करने के लिए कहा जाता है. अगर ऐप्लिकेशन पहले से इंस्टॉल है, तो उसे साइलेंट मोड में अपडेट किया जाता है.

  • डिवाइस रजिस्ट्रेशन फ़्लो: अगर Android Device Policy ऐप्लिकेशन पहले से इंस्टॉल नहीं है, तो यह उसे साइलेंट मोड में इंस्टॉल करता है. साथ ही, यह पक्का करता है कि उपयोगकर्ता के इंटरैक्शन के बिना ही, ऐप्लिकेशन इस्तेमाल के लिए तैयार हो.

पैरामीटर
notificationServiceComponentName: ComponentName?

ComponentName की सेवा NotificationReceiverService तक जारी रहेगी. अगर यह जानकारी दी जाती है, तो यह कॉल करने वाले ऐप्लिकेशन का मान्य कॉम्पोनेंट होना चाहिए. साथ ही, इसे मेनिफ़ेस्ट में एक्सपोर्ट किया गया हो. एनवायरमेंट तैयार करने से जुड़े इवेंट की सूचना पाने के लिए, आपको ये काम करने होंगे:

  1. अपने ऐप्लिकेशन में EnvironmentListener इंटरफ़ेस लागू करें.

  2. मिले हुए इवेंट को मैनेज करने का तरीका लागू करें.

  3. NotificationReceiverService को बढ़ाएं और EnvironmentListener इंस्टेंस उपलब्ध कराएं.

  4. अपनी AndroidManifest.xml फ़ाइल में, एक्सटेंड की गई NotificationReceiverService क्लास जोड़ें. साथ ही, यह पक्का करें कि इसे एक्सपोर्ट किया गया हो.

उदाहरण के लिए:

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 को रैप करने वाला फ़ेल हो जाएगा.

  • अगर Google Play services अप-टू-डेट नहीं है, तो GooglePlayServicesAppNotUpdatedException को रैप करने वाला फ़्यूचर पूरा नहीं होगा.

  • अगर Android Device Policy इंस्टॉल या अपडेट नहीं हो पाती है और गड़बड़ी ठीक नहीं की जा सकती, तो AndroidDevicePolicyInstallOrUpdateUnrecoverableException को रैप करने वाला फ़्यूचर फ़ेल हो जाता है.

  • अगर Android Device Policy ऐप्लिकेशन इंस्टॉल या अपडेट नहीं हो पाता है और गड़बड़ी ठीक की जा सकती है (जैसे, नेटवर्क से जुड़ी कुछ समय के लिए हुई समस्याओं की वजह से अनुरोध पूरा नहीं हो सका), तो AndroidDevicePolicyInstallOrUpdateRecoverableException को रैप करने वाला फ़्यूचर पूरा नहीं हो पाता. इसलिए, अनुरोध को फिर से आज़माया जा सकता है.

  • अगर उपयोगकर्ता Android Device Policy ऐप्लिकेशन इंस्टॉल करने से मना करता है, तो AndroidDevicePolicyInstallConsentDeclinedException को रैप करने वाला फ़ेल हुआ फ़्यूचर.

  • अगर उपयोगकर्ता, इंस्टॉल करने की सहमति वाली स्क्रीन को खारिज कर देता है, तो AndroidDevicePolicyInstallConsentDismissedException को रैप करने वाला फ़ेल हो चुका फ़्यूचर.

  • अगर किसी अंदरूनी गड़बड़ी की वजह से कॉल पूरा नहीं हो सका, तो InternalException को रैप करने वाला फ़ेल हुआ फ़्यूचर.

  • अगर Play Store अपडेट नहीं हो पाता है, तो PlayStoreUpdateUnrecoverableException को रैप करने वाला फ़ेल हुआ फ़्यूचर.
थ्रो
com.google.android.managementapi.common.exceptions.ApiLevelException

अगर डिवाइस के एसडीके का एपीआई लेवल, अनुरोध की गई कुछ भूमिकाओं के लिए ज़रूरी शर्तों को पूरा नहीं करता है. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} के लिए, एपीआई लेवल 23 या उसके बाद का वर्शन ज़रूरी है. अन्य भूमिकाओं के लिए, एपीआई लेवल 28 या उसके बाद का वर्शन ज़रूरी है.