From 95d44d2c0e298718991618fa47d7c01b94065932 Mon Sep 17 00:00:00 2001 From: Eran Messeri Date: Thu, 5 Mar 2020 11:23:08 +0000 Subject: [PATCH] Update documentation for settings, affiliation API Update the documentation for settings-related and affiliation-related methods: * The methods for setting a global and secure settings are documented to be mostly deprecated, because there are methods for the settings that are honoured and some other settings no longer apply. * The methods for setting affiliation or binding to a service on another user can no longer work between a device owner and profile owner since this combination is no longer a valid one. Bug: 147795815 Test: manual, m update-docs Change-Id: I316148cb1d90fbe94999f9d1c242f08554869e97 --- .../app/admin/DevicePolicyManager.java | 71 ++++++++++++------- 1 file changed, 47 insertions(+), 24 deletions(-) diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index b219394ddfa96..c532279676a06 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -8781,18 +8781,20 @@ public class DevicePolicyManager { } /** + * This method is mostly deprecated. + * Most of the settings that still have an effect have dedicated setter methods or user + * restrictions. See individual settings for details. + *

* Called by device owner to update {@link android.provider.Settings.Global} settings. * Validation that the value of the setting is in the correct form for the setting type should * be performed by the caller. *

* The settings that can be updated with this method are: *

*

+ * The following settings used to be supported, but can be controlled in other ways: + *

+ *

* Changing the following settings has no effect as of {@link android.os.Build.VERSION_CODES#M}: *

* * @param admin Which {@link DeviceAdminReceiver} this request is associated with. @@ -8989,6 +9002,11 @@ public class DevicePolicyManager { } /** + * This method is mostly deprecated. + * Most of the settings that still have an effect have dedicated setter methods + * (e.g. {@link #setLocationEnabled}) or user restrictions. + *

+ * * Called by profile or device owners to update {@link android.provider.Settings.Secure} * settings. Validation that the value of the setting is in the correct form for the setting * type should be performed by the caller. @@ -9001,7 +9019,7 @@ public class DevicePolicyManager { *

* A device owner can additionally update the following settings: *

* * Note: Starting from Android O, apps should no longer call this method with the @@ -10355,19 +10373,23 @@ public class DevicePolicyManager { } /** - * Indicates the entity that controls the device or profile owner. Two users/profiles are - * affiliated if the set of ids set by their device or profile owners intersect. + * Indicates the entity that controls the device. Two users are + * affiliated if the set of ids set by the device owner and the admin of the secondary user. * - *

A user/profile that is affiliated with the device owner user is considered to be + *

A user that is affiliated with the device owner user is considered to be * affiliated with the device. * *

Note: Features that depend on user affiliation (such as security logging - * or {@link #bindDeviceAdminServiceAsUser}) won't be available when a secondary user or profile + * or {@link #bindDeviceAdminServiceAsUser}) won't be available when a secondary user * is created, until it becomes affiliated. Therefore it is recommended that the appropriate - * affiliation ids are set by its profile owner as soon as possible after the user/profile is + * affiliation ids are set by its owner as soon as possible after the user is * created. + *

+ * Note: This method used to be available for affiliating device owner and profile + * owner. However, since Android 11, this combination is not possible. This method is now + * only useful for affiliating the primary user with managed secondary users. * - * @param admin Which profile or device owner this request is associated with. + * @param admin Which device owner, or owner of secondary user, this request is associated with. * @param ids A set of opaque non-empty affiliation ids. * * @throws IllegalArgumentException if {@code ids} is null or contains an empty string. @@ -10399,10 +10421,10 @@ public class DevicePolicyManager { } /** - * Returns whether this user/profile is affiliated with the device. + * Returns whether this user is affiliated with the device. *

* By definition, the user that the device owner runs on is always affiliated with the device. - * Any other user/profile is considered affiliated with the device if the set specified by its + * Any other user is considered affiliated with the device if the set specified by its * profile owner via {@link #setAffiliationIds} intersects with the device owner's. * @see #setAffiliationIds */ @@ -10706,14 +10728,18 @@ public class DevicePolicyManager { } /** - * Called by a device owner to bind to a service from a profile owner or vice versa. - * See {@link #getBindDeviceAdminTargetUsers} for a definition of which - * device/profile owners are allowed to bind to services of another profile/device owner. + * Called by a device owner to bind to a service from a secondary managed user or vice versa. + * See {@link #getBindDeviceAdminTargetUsers} for the pre-requirements of a + * device owner to bind to services of another managed user. *

* The service must be protected by {@link android.Manifest.permission#BIND_DEVICE_ADMIN}. * Note that the {@link Context} used to obtain this * {@link DevicePolicyManager} instance via {@link Context#getSystemService(Class)} will be used * to bind to the {@link android.app.Service}. + *

+ * Note: This method used to be available for communication between device owner and profile + * owner. However, since Android 11, this combination is not possible. This method is now + * only useful for communication between device owner and managed secondary users. * * @param admin Which {@link DeviceAdminReceiver} this request is associated with. * @param serviceIntent Identifies the service to connect to. The Intent must specify either an @@ -10751,14 +10777,11 @@ public class DevicePolicyManager { } /** - * Returns the list of target users that the calling device or profile owner can use when - * calling {@link #bindDeviceAdminServiceAsUser}. + * Returns the list of target users that the calling device owner or owner of secondary user + * can use when calling {@link #bindDeviceAdminServiceAsUser}. *

- * A device owner can bind to a service from a profile owner and vice versa, provided that: - *

+ * A device owner can bind to a service from a secondary managed user and vice versa, provided + * that both users are affiliated. See {@link #setAffiliationIds}. */ public @NonNull List getBindDeviceAdminTargetUsers(@NonNull ComponentName admin) { throwIfParentInstance("getBindDeviceAdminTargetUsers");