Merge "Review of suspend/unsuspend APIs" into pi-dev am: 2188383b8a

am: 03026cb894

Change-Id: Ifd15ef4d5db195b862cf800cf0d2fff11b26745d

8 files changed, 54 insertions, 26 deletions

diff --git a/api/current.txt b/api/current.txt
index 01d7c737aecc..de1604781707 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -10956,7 +10956,7 @@ package android.content.pm {
     method public abstract void onPackageRemoved(java.lang.String, android.os.UserHandle);
     method public abstract void onPackagesAvailable(java.lang.String[], android.os.UserHandle, boolean);
     method public void onPackagesSuspended(java.lang.String[], android.os.UserHandle);
-    method public void onPackagesSuspended(java.lang.String[], android.os.Bundle, android.os.UserHandle);
+    method public void onPackagesSuspended(java.lang.String[], android.os.UserHandle, android.os.Bundle);
     method public abstract void onPackagesUnavailable(java.lang.String[], android.os.UserHandle, boolean);
     method public void onPackagesUnsuspended(java.lang.String[], android.os.UserHandle);
     method public void onShortcutsChanged(java.lang.String, java.util.List<android.content.pm.ShortcutInfo>, android.os.UserHandle);
diff --git a/api/system-current.txt b/api/system-current.txt
index a559b7a27f59..de51aa09f8c1 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -1030,7 +1030,7 @@ package android.content.pm {
     method public abstract void grantRuntimePermission(java.lang.String, java.lang.String, android.os.UserHandle);
     method public abstract int installExistingPackage(java.lang.String) throws android.content.pm.PackageManager.NameNotFoundException;
     method public abstract int installExistingPackage(java.lang.String, int) throws android.content.pm.PackageManager.NameNotFoundException;
-    method public boolean isPackageSuspended(java.lang.String);
+    method public boolean isPackageSuspended(java.lang.String) throws android.content.pm.PackageManager.NameNotFoundException;
     method public java.util.List<android.content.pm.ResolveInfo> queryBroadcastReceiversAsUser(android.content.Intent, int, android.os.UserHandle);
     method public abstract void registerDexModule(java.lang.String, android.content.pm.PackageManager.DexModuleRegisterCallback);
     method public abstract void removeOnPermissionsChangeListener(android.content.pm.PackageManager.OnPermissionsChangedListener);
diff --git a/core/java/android/app/ApplicationPackageManager.java b/core/java/android/app/ApplicationPackageManager.java
index 2e93d88e0388..1084b425ea92 100644
--- a/core/java/android/app/ApplicationPackageManager.java
+++ b/core/java/android/app/ApplicationPackageManager.java
@@ -2187,8 +2187,12 @@ public class ApplicationPackageManager extends PackageManager {
 
     /** @hide */
     @Override
-    public boolean isPackageSuspended(String packageName) {
-        return isPackageSuspendedForUser(packageName, mContext.getUserId());
+    public boolean isPackageSuspended(String packageName) throws NameNotFoundException {
+        try {
+            return isPackageSuspendedForUser(packageName, mContext.getUserId());
+        } catch (IllegalArgumentException ie) {
+            throw new NameNotFoundException(packageName);
+        }
     }
 
     @Override
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 01ee67158a93..f608fcb1a5df 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -40,6 +40,7 @@ import android.os.Bundle;
 import android.os.IBinder;
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.os.PersistableBundle;
 import android.os.Process;
 import android.os.ResultReceiver;
 import android.os.ShellCommand;
@@ -1814,8 +1815,12 @@ public class Intent implements Parcelable, Cloneable {
     public static final String EXTRA_PACKAGE_NAME = "android.intent.extra.PACKAGE_NAME";
 
     /**
-     * Intent extra: A {@link Bundle} of extras for a package being suspended. Will be sent with
-     * {@link #ACTION_MY_PACKAGE_SUSPENDED}.
+     * Intent extra: A {@link Bundle} of extras for a package being suspended. Will be sent as an
+     * extra with {@link #ACTION_MY_PACKAGE_SUSPENDED}.
+     *
+     * <p>The contents of this {@link Bundle} are a contract between the suspended app and the
+     * suspending app, i.e. any app with the permission {@code android.permission.SUSPEND_APPS}.
+     * This is meant to enable the suspended app to better handle the state of being suspended.
      *
      * @see #ACTION_MY_PACKAGE_SUSPENDED
      * @see #ACTION_MY_PACKAGE_UNSUSPENDED
@@ -2284,6 +2289,10 @@ public class Intent implements Parcelable, Cloneable {
     /**
      * Activity Action: Started to show more details about why an application was suspended.
      *
+     * <p>Whenever the system detects an activity launch for a suspended app, it shows a dialog to
+     * the user to inform them of the state and present them an affordance to start this activity
+     * action to show more details about the reason for suspension.
+     *
      * <p>Apps holding {@link android.Manifest.permission#SUSPEND_APPS} must declare an activity
      * handling this intent and protect it with
      * {@link android.Manifest.permission#SEND_SHOW_SUSPENDED_APP_DETAILS}.
@@ -2293,6 +2302,8 @@ public class Intent implements Parcelable, Cloneable {
      * <p class="note">This is a protected intent that can only be sent
      * by the system.
      *
+     * @see PackageManager#setPackagesSuspended(String[], boolean, PersistableBundle,
+     * PersistableBundle, String)
      * @see PackageManager#isPackageSuspended()
      * @see #ACTION_PACKAGES_SUSPENDED
      *
diff --git a/core/java/android/content/pm/LauncherApps.java b/core/java/android/content/pm/LauncherApps.java
index 9aace2e7ba8d..8223363a2bc8 100644
--- a/core/java/android/content/pm/LauncherApps.java
+++ b/core/java/android/content/pm/LauncherApps.java
@@ -212,7 +212,7 @@ public class LauncherApps {
          * an applicaton.
          *
          * <p>Note: On devices running {@link android.os.Build.VERSION_CODES#P Android P} or higher,
-         * any apps that override {@link #onPackagesSuspended(String[], Bundle, UserHandle)} will
+         * any apps that override {@link #onPackagesSuspended(String[], UserHandle, Bundle)} will
          * not receive this callback.
          *
          * @param packageNames The names of the packages that have just been
@@ -226,15 +226,20 @@ public class LauncherApps {
          * Indicates that one or more packages have been suspended. A device administrator or an app
          * with {@code android.permission.SUSPEND_APPS} can do this.
          *
+         * <p>A suspending app with the permission {@code android.permission.SUSPEND_APPS} can
+         * optionally provide a {@link Bundle} of extra information that it deems helpful for the
+         * launcher to handle the suspended state of these packages. The contents of this
+         * {@link Bundle} supposed to be a contract between the suspending app and the launcher.
+         *
          * @param packageNames The names of the packages that have just been suspended.
-         * @param launcherExtras A {@link Bundle} of extras for the launcher.
          * @param user the user for which the given packages were suspended.
-         *
+         * @param launcherExtras A {@link Bundle} of extras for the launcher, if provided to the
+         *                      system, {@code null} otherwise.
          * @see PackageManager#isPackageSuspended()
          * @see #getSuspendedPackageLauncherExtras(String, UserHandle)
          */
-        public void onPackagesSuspended(String[] packageNames, @Nullable Bundle launcherExtras,
-                UserHandle user) {
+        public void onPackagesSuspended(String[] packageNames, UserHandle user,
+                @Nullable Bundle launcherExtras) {
             onPackagesSuspended(packageNames, user);
         }
 
@@ -662,6 +667,9 @@ public class LauncherApps {
      * {@code PackageManager#setPackagesSuspended(String[], boolean, PersistableBundle,
      * PersistableBundle, String)}.
      *
+     * <p>The contents of this {@link Bundle} are supposed to be a contract between the suspending
+     * app and the launcher.
+     *
      * <p>Note: This just returns whatever extras were provided to the system, <em>which might
      * even be {@code null}.</em>
      *
@@ -670,7 +678,7 @@ public class LauncherApps {
      * @return A {@link Bundle} of launcher extras. Or {@code null} if the package is not currently
      *         suspended.
      *
-     * @see Callback#onPackagesSuspended(String[], Bundle, UserHandle)
+     * @see Callback#onPackagesSuspended(String[], UserHandle, Bundle)
      * @see PackageManager#isPackageSuspended()
      */
     public @Nullable Bundle getSuspendedPackageLauncherExtras(String packageName, UserHandle user) {
@@ -1298,8 +1306,8 @@ public class LauncherApps {
                     mCallback.onPackagesUnavailable(info.packageNames, info.user, info.replacing);
                     break;
                 case MSG_SUSPENDED:
-                    mCallback.onPackagesSuspended(info.packageNames, info.launcherExtras,
-                            info.user);
+                    mCallback.onPackagesSuspended(info.packageNames, info.user, info.launcherExtras
+                    );
                     break;
                 case MSG_UNSUSPENDED:
                     mCallback.onPackagesUnsuspended(info.packageNames, info.user);
diff --git a/core/java/android/content/pm/PackageManager.java b/core/java/android/content/pm/PackageManager.java
index 6bbcf17face5..c68f253d4e88 100644
--- a/core/java/android/content/pm/PackageManager.java
+++ b/core/java/android/content/pm/PackageManager.java
@@ -5577,7 +5577,8 @@ public abstract class PackageManager {
      * @param packageName The name of the package to get the suspended status of.
      * @param userId The user id.
      * @return {@code true} if the package is suspended or {@code false} if the package is not
-     * suspended or could not be found.
+     * suspended.
+     * @throws IllegalArgumentException if the package was not found.
      * @hide
      */
     public abstract boolean isPackageSuspendedForUser(String packageName, int userId);
@@ -5586,12 +5587,13 @@ public abstract class PackageManager {
      * Query if an app is currently suspended.
      *
      * @return {@code true} if the given package is suspended, {@code false} otherwise
+     * @throws NameNotFoundException if the package could not be found.
      *
      * @see #setPackagesSuspended(String[], boolean, PersistableBundle, PersistableBundle, String)
      * @hide
      */
     @SystemApi
-    public boolean isPackageSuspended(String packageName) {
+    public boolean isPackageSuspended(String packageName) throws NameNotFoundException {
         throw new UnsupportedOperationException("isPackageSuspended not implemented");
     }
 
@@ -5622,11 +5624,16 @@ public abstract class PackageManager {
     }
 
     /**
-     * Returns any extra information supplied as {@code appExtras} to the system when the calling
-     * app was suspended.
+     * Returns a {@link Bundle} of extras that was meant to be sent to the calling app when it was
+     * suspended. An app with the permission {@code android.permission.SUSPEND_APPS} can supply this
+     * to the system at the time of suspending an app.
      *
-     * <p>Note: If no extras were supplied to the system, this method will return {@code null}, even
-     * when the calling app has been suspended.</p>
+     * <p>This is the same {@link Bundle} that is sent along with the broadcast
+     * {@link Intent#ACTION_MY_PACKAGE_SUSPENDED}, whenever the app is suspended. The contents of
+     * this {@link Bundle} are a contract between the suspended app and the suspending app.
+     *
+     * <p>Note: These extras are optional, so if no extras were supplied to the system, this method
+     * will return {@code null}, even when the calling app has been suspended.
      *
      * @return A {@link Bundle} containing the extras for the app, or {@code null} if the
      * package is not currently suspended.
@@ -5634,6 +5641,7 @@ public abstract class PackageManager {
      * @see #isPackageSuspended()
      * @see Intent#ACTION_MY_PACKAGE_UNSUSPENDED
      * @see Intent#ACTION_MY_PACKAGE_SUSPENDED
+     * @see Intent#EXTRA_SUSPENDED_PACKAGE_EXTRAS
      */
     public @Nullable Bundle getSuspendedPackageAppExtras() {
         throw new UnsupportedOperationException("getSuspendedPackageAppExtras not implemented");
diff --git a/services/core/java/com/android/server/pm/PackageManagerService.java b/services/core/java/com/android/server/pm/PackageManagerService.java
index f8c9118d6733..56345a62fa54 100644
--- a/services/core/java/com/android/server/pm/PackageManagerService.java
+++ b/services/core/java/com/android/server/pm/PackageManagerService.java
@@ -14150,9 +14150,6 @@ public class PackageManagerService extends IPackageManager.Stub
         mPermissionManager.enforceCrossUserPermission(callingUid, userId,
                 true /* requireFullPermission */, false /* checkShell */,
                 "isPackageSuspendedForUser for user " + userId);
-        if (getPackageUid(packageName, 0, userId) != callingUid) {
-            mContext.enforceCallingOrSelfPermission(Manifest.permission.SUSPEND_APPS, null);
-        }
         synchronized (mPackages) {
             final PackageSetting ps = mSettings.mPackages.get(packageName);
             if (ps == null || filterAppAccessLPr(ps, callingUid, userId)) {
diff --git a/services/tests/servicestests/src/com/android/server/pm/SuspendPackagesTest.java b/services/tests/servicestests/src/com/android/server/pm/SuspendPackagesTest.java
index 084f7e531858..c5cd0a3f6a2a 100644
--- a/services/tests/servicestests/src/com/android/server/pm/SuspendPackagesTest.java
+++ b/services/tests/servicestests/src/com/android/server/pm/SuspendPackagesTest.java
@@ -242,7 +242,7 @@ public class SuspendPackagesTest {
     }
 
     @Test
-    public void testIsPackageSuspended() {
+    public void testIsPackageSuspended() throws Exception {
         suspendTestPackage(null, null, null);
         assertTrue("isPackageSuspended is false",
                 mPackageManager.isPackageSuspended(TEST_APP_PACKAGE_NAME));
@@ -370,8 +370,8 @@ public class SuspendPackagesTest {
             }
 
             @Override
-            public void onPackagesSuspended(String[] packageNames, Bundle launcherExtras,
-                    UserHandle user) {
+            public void onPackagesSuspended(String[] packageNames, UserHandle user,
+                    Bundle launcherExtras) {
                 final StringBuilder errorString = new StringBuilder();
                 if (!Arrays.equals(packageNames, PACKAGES_TO_SUSPEND)) {
                     errorString.append("Received unexpected packageNames in onPackagesSuspended:");