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 या इसके बाद का वर्शन ज़रूरी है.