Merge "Incorporate feedback on new wallpaper-related APIs" into nyc-dev am: 9d37bdcb91

am: 3de573733c

* commit '3de573733c05d204589d9c56fb26fbb985ecc060':
  Incorporate feedback on new wallpaper-related APIs

Change-Id: I7cbca080286f54040782c79eab57f2285cee222d

6 files changed, 49 insertions, 33 deletions

diff --git a/api/current.txt b/api/current.txt
index caaeb3ab62e4..da17b6a9334b 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -5784,7 +5784,7 @@ package android.app {
     method public int getWallpaperId(int);
     method public android.app.WallpaperInfo getWallpaperInfo();
     method public boolean hasResourceWallpaper(int);
-    method public boolean isWallpaperSettingAllowed();
+    method public boolean isSetWallpaperAllowed();
     method public boolean isWallpaperSupported();
     method public android.graphics.drawable.Drawable peekDrawable();
     method public android.graphics.drawable.Drawable peekFastDrawable();
diff --git a/api/system-current.txt b/api/system-current.txt
index f01effb434f0..a3f38883f07f 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -5933,7 +5933,7 @@ package android.app {
     method public int getWallpaperId(int);
     method public android.app.WallpaperInfo getWallpaperInfo();
     method public boolean hasResourceWallpaper(int);
-    method public boolean isWallpaperSettingAllowed();
+    method public boolean isSetWallpaperAllowed();
     method public boolean isWallpaperSupported();
     method public android.graphics.drawable.Drawable peekDrawable();
     method public android.graphics.drawable.Drawable peekFastDrawable();
diff --git a/api/test-current.txt b/api/test-current.txt
index 2950d0aee864..8cb8b20d0a73 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -5790,7 +5790,7 @@ package android.app {
     method public int getWallpaperId(int);
     method public android.app.WallpaperInfo getWallpaperInfo();
     method public boolean hasResourceWallpaper(int);
-    method public boolean isWallpaperSettingAllowed();
+    method public boolean isSetWallpaperAllowed();
     method public boolean isWallpaperSupported();
     method public android.graphics.drawable.Drawable peekDrawable();
     method public android.graphics.drawable.Drawable peekFastDrawable();
diff --git a/core/java/android/app/IWallpaperManager.aidl b/core/java/android/app/IWallpaperManager.aidl
index a42aed6fe28a..a0762b94a040 100644
--- a/core/java/android/app/IWallpaperManager.aidl
+++ b/core/java/android/app/IWallpaperManager.aidl
@@ -123,7 +123,7 @@ interface IWallpaperManager {
     /**
      * Check whether setting of wallpapers are allowed for the calling user.
      */
-    boolean isWallpaperSettingAllowed(in String callingPackage);
+    boolean isSetWallpaperAllowed(in String callingPackage);
 
     /*
      * Backup: is the current system wallpaper image eligible for off-device backup?
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index 2b82929debe0..18f93cd4688a 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -43,6 +43,7 @@ import android.graphics.drawable.BitmapDrawable;
 import android.graphics.drawable.Drawable;
 import android.net.Uri;
 import android.os.Bundle;
+import android.os.DeadSystemException;
 import android.os.Handler;
 import android.os.IBinder;
 import android.os.Looper;
@@ -76,7 +77,7 @@ import java.util.concurrent.TimeUnit;
  *
  * <p> An app can check whether wallpapers are supported for the current user, by calling
  * {@link #isWallpaperSupported()}, and whether setting of wallpapers is allowed, by calling
- * {@link #isWallpaperSettingAllowed()}.
+ * {@link #isSetWallpaperAllowed()}.
  */
 public class WallpaperManager {
     private static String TAG = "WallpaperManager";
@@ -483,7 +484,7 @@ public class WallpaperManager {
             float horizontalAlignment, float verticalAlignment, @SetWallpaperFlags int which) {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return null;
+            throw new RuntimeException(new DeadSystemException());
         }
 
         if (which != FLAG_SYSTEM && which != FLAG_LOCK) {
@@ -750,7 +751,7 @@ public class WallpaperManager {
 
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return null;
+            throw new RuntimeException(new DeadSystemException());
         } else {
             try {
                 Bundle outParams = new Bundle();
@@ -780,7 +781,7 @@ public class WallpaperManager {
         try {
             if (sGlobals.mService == null) {
                 Log.w(TAG, "WallpaperService not running");
-                return null;
+                throw new RuntimeException(new DeadSystemException());
             } else {
                 return sGlobals.mService.getWallpaperInfo();
             }
@@ -793,6 +794,10 @@ public class WallpaperManager {
      * Get the ID of the current wallpaper of the given kind.  If there is no
      * such wallpaper configured, returns a negative number.
      *
+     * <p>Every time the wallpaper image is set, a new ID is assigned to it.
+     * This method allows the caller to determine whether the wallpaper imagery
+     * has changed, regardless of how that change happened.
+     *
      * @param which The wallpaper whose ID is to be returned.  Must be a single
      *     defined kind of wallpaper, either {@link #FLAG_SYSTEM} or
      *     {@link #FLAG_LOCK}.
@@ -812,7 +817,7 @@ public class WallpaperManager {
         try {
             if (sGlobals.mService == null) {
                 Log.w(TAG, "WallpaperService not running");
-                return -1;
+                throw new RuntimeException(new DeadSystemException());
             } else {
                 return sGlobals.mService.getWallpaperIdForUser(which, userId);
             }
@@ -914,7 +919,7 @@ public class WallpaperManager {
             throws IOException {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return 0;
+            throw new RuntimeException(new DeadSystemException());
         }
         final Bundle result = new Bundle();
         final WallpaperSetCompletion completion = new WallpaperSetCompletion();
@@ -1027,7 +1032,7 @@ public class WallpaperManager {
         validateRect(visibleCropHint);
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return 0;
+            throw new RuntimeException(new DeadSystemException());
         }
         final Bundle result = new Bundle();
         final WallpaperSetCompletion completion = new WallpaperSetCompletion();
@@ -1073,7 +1078,8 @@ public class WallpaperManager {
      * <p>This method requires the caller to hold the permission
      * {@link android.Manifest.permission#SET_WALLPAPER}.
      *
-     * @param bitmapData A stream containing the raw data to install as a wallpaper.
+     * @param bitmapData A stream containing the raw data to install as a wallpaper.  This
+     *     data can be in any format handled by {@link BitmapRegionDecoder}.
      *
      * @throws IOException If an error occurs when attempting to set the wallpaper
      *     based on the provided image data.
@@ -1103,13 +1109,17 @@ public class WallpaperManager {
      * <p>This method requires the caller to hold the permission
      * {@link android.Manifest.permission#SET_WALLPAPER}.
      *
-     * @param bitmapData A stream containing the raw data to install as a wallpaper.
+     * @param bitmapData A stream containing the raw data to install as a wallpaper.  This
+     *     data can be in any format handled by {@link BitmapRegionDecoder}.
      * @param visibleCropHint The rectangular subregion of the streamed image that should be
      *     displayed as wallpaper.  Passing {@code null} for this parameter means that
      *     the full image should be displayed if possible given the image's and device's
      *     aspect ratios, etc.
      * @param allowBackup {@code true} if the OS is permitted to back up this wallpaper
      *     image for restore to a future device; {@code false} otherwise.
+     * @return An integer ID assigned to the newly active wallpaper; or zero on failure.
+     *
+     * @see #getWallpaperId(int)
      *
      * @throws IOException If an error occurs when attempting to set the wallpaper
      *     based on the provided image data.
@@ -1125,7 +1135,8 @@ public class WallpaperManager {
      * Version of {@link #setStream(InputStream, Rect, boolean)} that allows the caller
      * to specify which of the supported wallpaper categories to set.
      *
-     * @param bitmapData A stream containing the raw data to install as a wallpaper.
+     * @param bitmapData A stream containing the raw data to install as a wallpaper.  This
+     *     data can be in any format handled by {@link BitmapRegionDecoder}.
      * @param visibleCropHint The rectangular subregion of the streamed image that should be
      *     displayed as wallpaper.  Passing {@code null} for this parameter means that
      *     the full image should be displayed if possible given the image's and device's
@@ -1133,7 +1144,9 @@ public class WallpaperManager {
      * @param allowBackup {@code true} if the OS is permitted to back up this wallpaper
      *     image for restore to a future device; {@code false} otherwise.
      * @param which Flags indicating which wallpaper(s) to configure with the new imagery.
+     * @return An integer ID assigned to the newly active wallpaper; or zero on failure.
      *
+     * @see #getWallpaperId(int)
      * @see #FLAG_LOCK
      * @see #FLAG_SYSTEM
      *
@@ -1145,7 +1158,7 @@ public class WallpaperManager {
         validateRect(visibleCropHint);
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return 0;
+            throw new RuntimeException(new DeadSystemException());
         }
         final Bundle result = new Bundle();
         final WallpaperSetCompletion completion = new WallpaperSetCompletion();
@@ -1179,7 +1192,7 @@ public class WallpaperManager {
     public boolean hasResourceWallpaper(@RawRes int resid) {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return false;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             Resources resources = mContext.getResources();
@@ -1207,7 +1220,7 @@ public class WallpaperManager {
     public int getDesiredMinimumWidth() {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return 0;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             return sGlobals.mService.getWidthHint();
@@ -1233,7 +1246,7 @@ public class WallpaperManager {
     public int getDesiredMinimumHeight() {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return 0;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             return sGlobals.mService.getHeightHint();
@@ -1294,6 +1307,7 @@ public class WallpaperManager {
 
             if (sGlobals.mService == null) {
                 Log.w(TAG, "WallpaperService not running");
+                throw new RuntimeException(new DeadSystemException());
             } else {
                 sGlobals.mService.setDimensionHints(minimumWidth, minimumHeight,
                         mContext.getOpPackageName());
@@ -1316,6 +1330,7 @@ public class WallpaperManager {
         try {
             if (sGlobals.mService == null) {
                 Log.w(TAG, "WallpaperService not running");
+                throw new RuntimeException(new DeadSystemException());
             } else {
                 sGlobals.mService.setDisplayPadding(padding, mContext.getOpPackageName());
             }
@@ -1365,7 +1380,7 @@ public class WallpaperManager {
     public void clearWallpaper(@SetWallpaperFlags int which, int userId) {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             sGlobals.mService.clearWallpaper(mContext.getOpPackageName(), which, userId);
@@ -1386,7 +1401,7 @@ public class WallpaperManager {
     public boolean setWallpaperComponent(ComponentName name) {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return false;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             sGlobals.mService.setWallpaperComponentChecked(name, mContext.getOpPackageName());
@@ -1466,6 +1481,7 @@ public class WallpaperManager {
     public boolean isWallpaperSupported() {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
+            throw new RuntimeException(new DeadSystemException());
         } else {
             try {
                 return sGlobals.mService.isWallpaperSupported(mContext.getOpPackageName());
@@ -1473,7 +1489,6 @@ public class WallpaperManager {
                 throw e.rethrowFromSystemServer();
             }
         }
-        return false;
     }
 
     /**
@@ -1483,17 +1498,17 @@ public class WallpaperManager {
      *
      * @see android.os.UserManager#DISALLOW_SET_WALLPAPER
      */
-    public boolean isWallpaperSettingAllowed() {
+    public boolean isSetWallpaperAllowed() {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
+            throw new RuntimeException(new DeadSystemException());
         } else {
             try {
-                return sGlobals.mService.isWallpaperSettingAllowed(mContext.getOpPackageName());
+                return sGlobals.mService.isSetWallpaperAllowed(mContext.getOpPackageName());
             } catch (RemoteException e) {
                 throw e.rethrowFromSystemServer();
             }
         }
-        return false;
     }
 
     /**
@@ -1621,7 +1636,7 @@ public class WallpaperManager {
     public boolean setLockWallpaperCallback(IWallpaperManagerCallback callback) {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return false;
+            throw new RuntimeException(new DeadSystemException());
         }
 
         try {
@@ -1640,7 +1655,7 @@ public class WallpaperManager {
     public boolean isWallpaperBackupEligible() {
         if (sGlobals.mService == null) {
             Log.w(TAG, "WallpaperService not running");
-            return false;
+            throw new RuntimeException(new DeadSystemException());
         }
         try {
             return sGlobals.mService.isWallpaperBackupEligible(mContext.getUserId());
diff --git a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
index 06b93293b9ba..efd238201e7a 100644
--- a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
+++ b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
@@ -1011,7 +1011,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub {
     public void clearWallpaper(String callingPackage, int which, int userId) {
         if (DEBUG) Slog.v(TAG, "clearWallpaper");
         checkPermission(android.Manifest.permission.SET_WALLPAPER);
-        if (!isWallpaperSupported(callingPackage) || !isWallpaperSettingAllowed(callingPackage)) {
+        if (!isWallpaperSupported(callingPackage) || !isSetWallpaperAllowed(callingPackage)) {
             return;
         }
         userId = ActivityManager.handleIncomingUser(Binder.getCallingPid(),
@@ -1326,11 +1326,12 @@ public class WallpaperManagerService extends IWallpaperManager.Stub {
         checkPermission(android.Manifest.permission.SET_WALLPAPER);
 
         if ((which & (FLAG_LOCK|FLAG_SYSTEM)) == 0) {
-            Slog.e(TAG, "Must specify a valid wallpaper category to set");
-            return null;
+            final String msg = "Must specify a valid wallpaper category to set";
+            Slog.e(TAG, msg);
+            throw new IllegalArgumentException(msg);
         }
 
-        if (!isWallpaperSupported(callingPackage) || !isWallpaperSettingAllowed(callingPackage)) {
+        if (!isWallpaperSupported(callingPackage) || !isSetWallpaperAllowed(callingPackage)) {
             return null;
         }
 
@@ -1341,7 +1342,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub {
             if (cropHint.isEmpty()
                     || cropHint.left < 0
                     || cropHint.top < 0) {
-                return null;
+                throw new IllegalArgumentException("Invalid crop rect supplied: " + cropHint);
             }
         }
 
@@ -1449,7 +1450,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub {
 
     @Override
     public void setWallpaperComponentChecked(ComponentName name, String callingPackage) {
-        if (isWallpaperSupported(callingPackage) && isWallpaperSettingAllowed(callingPackage)) {
+        if (isWallpaperSupported(callingPackage) && isSetWallpaperAllowed(callingPackage)) {
             setWallpaperComponent(name);
         }
     }
@@ -1699,7 +1700,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub {
     }
 
     @Override
-    public boolean isWallpaperSettingAllowed(String callingPackage) {
+    public boolean isSetWallpaperAllowed(String callingPackage) {
         final PackageManager pm = mContext.getPackageManager();
         String[] uidPackages = pm.getPackagesForUid(Binder.getCallingUid());
         boolean uidMatchPackage = Arrays.asList(uidPackages).contains(callingPackage);