From c4b5cc5957b7a0d0fadb92f3b10fc6df61374b0a Mon Sep 17 00:00:00 2001 From: Alex Kershaw Date: Thu, 13 Feb 2020 19:10:08 +0000 Subject: [PATCH] Update cross-profile javadoc Update the javadoc after reviewing the new public-facing Javadoc implemented for the INTERACT_ACROSS_PROFILES work. Bug: 136249261 Test: no Java changes Change-Id: I1a669adea2ff47171dbbcbe6e847a3be0cfa7509 --- .../app/admin/DevicePolicyManager.java | 39 ++++++++------- .../android/content/pm/CrossProfileApps.java | 47 ++++++++++++++----- 2 files changed, 56 insertions(+), 30 deletions(-) diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index 4a5a23ab36f81..40b81dd6d5baa 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -11580,13 +11580,16 @@ public class DevicePolicyManager { } /** - * Sets the set of package names that are allowed to request user consent for cross-profile - * communication. + * Sets the set of admin-whitelisted package names that are allowed to request user consent for + * cross-profile communication. * *

Assumes that the caller is a profile owner and is the given {@code admin}. * *

Previous calls are overridden by each subsequent call to this method. * + *

Note that other apps may be able to request user consent for cross-profile communication + * if they have been explicitly whitelisted by the OEM. + * *

When previously-set cross-profile packages are missing from {@code packageNames}, the * app-op for {@code INTERACT_ACROSS_PROFILES} will be reset for those packages. This will not * occur for packages that are whitelisted by the OEM. @@ -11608,15 +11611,18 @@ public class DevicePolicyManager { /** * Returns the set of package names that the admin has previously set as allowed to request user - * consent for cross-profile communication, via {@link - * #setCrossProfilePackages(ComponentName, Set)}. + * consent for cross-profile communication, via {@link #setCrossProfilePackages(ComponentName, + * Set)}. * *

Assumes that the caller is a profile owner and is the given {@code admin}. * + *

Note that other apps not included in the returned set may be able to request user consent + * for cross-profile communication if they have been explicitly whitelisted by the OEM. + * * @param admin the {@link DeviceAdminReceiver} this request is associated with * @return the set of package names the admin has previously set as allowed to request user - * consent for cross-profile communication, via {@link - * #setCrossProfilePackages(ComponentName, Set)} + * consent for cross-profile communication, via {@link #setCrossProfilePackages(ComponentName, + * Set)} */ public @NonNull Set getCrossProfilePackages(@NonNull ComponentName admin) { throwIfParentInstance("getCrossProfilePackages"); @@ -11634,18 +11640,17 @@ public class DevicePolicyManager { * Returns the combined set of the following: *

* * @return the combined set of whitelisted package names set via - * {@link #setCrossProfilePackages(ComponentName, Set)}, - * {@link com.android.internal.R.array#cross_profile_apps}, - * and {@link com.android.internal.R.array#vendor_cross_profile_apps}. + * {@link #setCrossProfilePackages(ComponentName, Set)}, {@link com.android.internal.R.array + * #cross_profile_apps}, and {@link com.android.internal.R.array#vendor_cross_profile_apps}. * * @hide */ @@ -11668,9 +11673,9 @@ public class DevicePolicyManager { /** * Returns the default package names set by the OEM that are allowed to request user consent for - * cross-profile communication without being explicitly enabled by the admin, via - * {@link com.android.internal.R.array#cross_profile_apps} and - * {@link com.android.internal.R.array#vendor_cross_profile_apps}. + * cross-profile communication without being explicitly enabled by the admin, via {@link + * com.android.internal.R.array#cross_profile_apps} and {@link com.android.internal.R.array + * #vendor_cross_profile_apps}. * * @hide */ diff --git a/core/java/android/content/pm/CrossProfileApps.java b/core/java/android/content/pm/CrossProfileApps.java index 50841c369e52f..eb1da67972fdd 100644 --- a/core/java/android/content/pm/CrossProfileApps.java +++ b/core/java/android/content/pm/CrossProfileApps.java @@ -47,8 +47,15 @@ import java.util.stream.Collectors; public class CrossProfileApps { /** - * Broadcast signalling that the receiving app's ability to interact across profiles has - * changed, as defined by the return value of {@link #canInteractAcrossProfiles()}. + * Broadcast signalling that the receiving app's permission to interact across profiles has + * changed. This includes the user, admin, or OEM changing their consent such that the + * permission for the app to interact across profiles has changed. + * + *

This broadcast is not sent when other circumstances result in a change to being able to + * interact across profiles in practice, such as the profile being turned off or removed, apps + * being uninstalled, etc. The methods {@link #canInteractAcrossProfiles()} and {@link + * #canRequestInteractAcrossProfiles()} can be used by apps prior to attempting to interact + * across profiles or attempting to request user consent to interact across profiles. * *

Apps that have set the {@code android:crossProfile} manifest attribute to {@code true} * can receive this broadcast in manifest broadcast receivers. Otherwise, it can only be @@ -99,8 +106,11 @@ public class CrossProfileApps { /** * Starts the specified activity of the caller package in the specified profile. * - *

The caller must have the {@link android.Manifest.permission#INTERACT_ACROSS_PROFILES} - * permission and both the caller and target user profiles must be in the same profile group. + *

The caller must have the {@link android.Manifest.permission#INTERACT_ACROSS_PROFILES}, + * {@code android.Manifest.permission#INTERACT_ACROSS_USERS}, or {@code + * android.Manifest.permission#INTERACT_ACROSS_USERS_FULL} permission. Both the caller and + * target user profiles must be in the same profile group. The target user must be a valid user + * returned from {@link #getTargetUserProfiles()}. * * @param intent The intent to launch. A component in the caller package must be specified. * @param targetUser The {@link UserHandle} of the profile; must be one of the users returned by @@ -219,10 +229,11 @@ public class CrossProfileApps { } /** - * Returns whether the calling package can request to interact across profiles. + * Returns whether the calling package can request user consent to interact across profiles. * - *

The package's current ability to interact across profiles can be checked with - * {@link #canInteractAcrossProfiles()}. + *

If {@code true}, user consent can be obtained via {@link + * #createRequestInteractAcrossProfilesIntent()}. The package can then listen to {@link + * #ACTION_CAN_INTERACT_ACROSS_PROFILES_CHANGED} broadcasts. * *

Specifically, returns whether the following are all true: *

* + *

Note that user consent could already be granted if given a return value of {@code true}. + * The package's current ability to interact across profiles can be checked with {@link + * #canInteractAcrossProfiles()}. + * * @return true if the calling package can request to interact across profiles. */ public boolean canRequestInteractAcrossProfiles() { @@ -247,10 +262,7 @@ public class CrossProfileApps { /** * Returns whether the calling package can interact across profiles. - * - *

The package's current ability to request to interact across profiles can be checked with - * {@link #canRequestInteractAcrossProfiles()}. - * + *

Specifically, returns whether the following are all true: *

* + *

If {@code false}, the package's current ability to request user consent to interact across + * profiles can be checked with {@link #canRequestInteractAcrossProfiles()}. If {@code true}, + * user consent can be obtained via {@link #createRequestInteractAcrossProfilesIntent()}. The + * package can then listen to {@link #ACTION_CAN_INTERACT_ACROSS_PROFILES_CHANGED} broadcasts. + * * @return true if the calling package can interact across profiles. * @throws SecurityException if {@code mContext.getPackageName()} does not belong to the * calling UID. @@ -276,11 +293,15 @@ public class CrossProfileApps { /** * Returns an {@link Intent} to open the settings page that allows the user to decide whether - * the calling app can interact across profiles. The current state is given by - * {@link #canInteractAcrossProfiles()}. + * the calling app can interact across profiles. * *

Returns {@code null} if {@link #canRequestInteractAcrossProfiles()} is {@code false}. * + *

Note that the user may already have given consent and the app may already be able to + * interact across profiles, even if {@link #canRequestInteractAcrossProfiles()} is {@code + * true}. The current ability to interact across profiles is given by {@link + * #canInteractAcrossProfiles()}. + * * @return an {@link Intent} to open the settings page that allows the user to decide whether * the app can interact across profiles *