Merge "Update documentation for Launcher Apps." into main
diff --git a/core/java/android/content/pm/LauncherApps.java b/core/java/android/content/pm/LauncherApps.java
index 27ab5d05..6168b68 100644
--- a/core/java/android/content/pm/LauncherApps.java
+++ b/core/java/android/content/pm/LauncherApps.java
@@ -29,6 +29,7 @@
import android.annotation.RequiresPermission;
import android.annotation.SdkConstant;
import android.annotation.SdkConstant.SdkConstantType;
+import android.annotation.SuppressLint;
import android.annotation.SystemApi;
import android.annotation.SystemService;
import android.annotation.TestApi;
@@ -694,9 +695,16 @@
* <p>If the caller is running on a managed profile, it'll return only the current profile.
* Otherwise it'll return the same list as {@link UserManager#getUserProfiles()} would.
*
- * <p> To get hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>To get hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public List<UserHandle> getProfiles() {
@@ -756,15 +764,21 @@
* list.</li>
* </ul>
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param packageName The specific package to query. If null, it checks all installed packages
* in the profile.
* @param user The UserHandle of the profile.
* @return List of launchable activities. Can be an empty list but will not be null.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public List<LauncherActivityInfo> getActivityList(String packageName, UserHandle user) {
@@ -806,15 +820,21 @@
* Returns information related to a user which is useful for displaying UI elements
* to distinguish it from other users (eg, badges).
*
- * <p>If the user in question is a hidden profile like
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param userHandle user handle of the user for which LauncherUserInfo is requested.
* @return the {@link LauncherUserInfo} object related to the user specified, null in case
* the user is inaccessible.
*/
@Nullable
+ @SuppressLint("RequiresPermission")
@FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
@@ -853,9 +873,14 @@
* </ul>
* </p>
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param packageName the package for which intent sender to launch App Market Activity is
* required.
@@ -864,6 +889,7 @@
* there is no such activity.
*/
@Nullable
+ @SuppressLint("RequiresPermission")
@FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
@@ -887,9 +913,14 @@
* <p>An empty list denotes that all system packages should be treated as pre-installed for that
* user at creation.
*
- * <p>If the user in question is a hidden profile like
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param userHandle the user for which installed system packages are required.
* @return {@link List} of {@link String}, representing the package name of the installed
@@ -897,6 +928,7 @@
*/
@FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)
@NonNull
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public List<String> getPreInstalledSystemPackages(@NonNull UserHandle userHandle) {
@@ -936,14 +968,20 @@
* Returns the activity info for a given intent and user handle, if it resolves. Otherwise it
* returns null.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param intent The intent to find a match for.
* @param user The profile to look in for a match.
* @return An activity info object if there is a match.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public LauncherActivityInfo resolveActivity(Intent intent, UserHandle user) {
@@ -995,15 +1033,21 @@
/**
* Starts a Main activity in the specified profile.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param component The ComponentName of the activity to launch
* @param user The UserHandle of the profile
* @param sourceBounds The Rect containing the source bounds of the clicked icon
* @param opts Options to pass to startActivity
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public void startMainActivity(ComponentName component, UserHandle user, Rect sourceBounds,
@@ -1043,15 +1087,21 @@
* Starts the settings activity to show the application details for a
* package in the specified profile.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param component The ComponentName of the package to launch settings for.
* @param user The UserHandle of the profile
* @param sourceBounds The Rect containing the source bounds of the clicked icon
* @param opts Options to pass to startActivity
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public void startAppDetailsActivity(ComponentName component, UserHandle user,
@@ -1165,15 +1215,21 @@
/**
* Checks if the package is installed and enabled for a profile.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param packageName The package to check.
* @param user The UserHandle of the profile.
*
* @return true if the package exists and is enabled.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public boolean isPackageEnabled(String packageName, UserHandle user) {
@@ -1193,9 +1249,14 @@
* <p>The contents of this {@link Bundle} are supposed to be a contract between the suspending
* app and the launcher.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* <p>Note: This just returns whatever extras were provided to the system, <em>which might
* even be {@code null}.</em>
@@ -1208,6 +1269,7 @@
* @see Callback#onPackagesSuspended(String[], UserHandle, Bundle)
* @see PackageManager#isPackageSuspended()
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public @Nullable Bundle getSuspendedPackageLauncherExtras(String packageName, UserHandle user) {
@@ -1224,14 +1286,20 @@
* could be done because the package was marked as distracting to the user via
* {@code PackageManager.setDistractingPackageRestrictions(String[], int)}.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param packageName The package for which to check.
* @param user the {@link UserHandle} of the profile.
* @return
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public boolean shouldHideFromSuggestions(@NonNull String packageName,
@@ -1248,9 +1316,14 @@
/**
* Returns {@link ApplicationInfo} about an application installed for a specific user profile.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param packageName The package name of the application
* @param flags Additional option flags {@link PackageManager#getApplicationInfo}
@@ -1260,6 +1333,7 @@
* {@code null} if the package isn't installed for the given profile, or the profile
* isn't enabled.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public ApplicationInfo getApplicationInfo(@NonNull String packageName,
@@ -1311,15 +1385,21 @@
* <p>The activity may still not be exported, in which case {@link #startMainActivity} will
* throw a {@link SecurityException} unless the caller has the same UID as the target app's.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param component The activity to check.
* @param user The UserHandle of the profile.
*
* @return true if the activity exists and is enabled.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public boolean isActivityEnabled(ComponentName component, UserHandle user) {
@@ -1880,12 +1960,18 @@
/**
* Registers a callback for changes to packages in this user and managed profiles.
*
- * <p>To receive callbacks for hidden profile{@link UserManager.USER_TYPE_PROFILE_PRIVATE},
- * caller should have {@link android.app.role.RoleManager.ROLE_HOME} and either of the
- * permissions required.
+ * <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param callback The callback to register.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public void registerCallback(Callback callback) {
@@ -1896,12 +1982,18 @@
* Registers a callback for changes to packages in this user and managed profiles.
*
* <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
- * caller should have {@link android.app.role.RoleManager.ROLE_HOME} and either of the
- * permissions required.
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @param callback The callback to register.
* @param handler that should be used to post callbacks on, may be null.
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public void registerCallback(Callback callback, Handler handler) {
@@ -2354,12 +2446,18 @@
* package name in the app's manifest, have the android.permission.QUERY_ALL_PACKAGES, or be
* the session owner to retrieve these details.
*
- * <p>If the user in question is a hidden profile
- * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have
- * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.
+ * <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},
+ * caller should have either:</p>
+ * <ul>
+ * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES}
+ * permission</li>
+ * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the
+ * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>
+ * </ul>
*
* @see PackageInstaller#getAllSessions()
*/
+ @SuppressLint("RequiresPermission")
@RequiresPermission(conditional = true,
anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
public @NonNull List<SessionInfo> getAllPackageInstallerSessions() {