Merge "API review: WallpaperManager" into nyc-dev
diff --git a/api/current.txt b/api/current.txt
index e743881..9939286 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -5755,8 +5755,8 @@
     field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap";
     field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap";
     field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT";
-    field public static final int FLAG_SET_LOCK = 2; // 0x2
-    field public static final int FLAG_SET_SYSTEM = 1; // 0x1
+    field public static final int FLAG_LOCK = 2; // 0x2
+    field public static final int FLAG_SYSTEM = 1; // 0x1
     field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview";
   }
 
diff --git a/api/system-current.txt b/api/system-current.txt
index 008b860..a34f6c6 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -5893,8 +5893,8 @@
     field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap";
     field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap";
     field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT";
-    field public static final int FLAG_SET_LOCK = 2; // 0x2
-    field public static final int FLAG_SET_SYSTEM = 1; // 0x1
+    field public static final int FLAG_LOCK = 2; // 0x2
+    field public static final int FLAG_SYSTEM = 1; // 0x1
     field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview";
   }
 
diff --git a/api/test-current.txt b/api/test-current.txt
index 78a1d3a..56b7586 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -5759,8 +5759,8 @@
     field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap";
     field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap";
     field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT";
-    field public static final int FLAG_SET_LOCK = 2; // 0x2
-    field public static final int FLAG_SET_SYSTEM = 1; // 0x1
+    field public static final int FLAG_LOCK = 2; // 0x2
+    field public static final int FLAG_SYSTEM = 1; // 0x1
     field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview";
   }
 
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index b52af27..72b9318 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -161,8 +161,8 @@
 
     /** @hide */
     @IntDef(flag = true, value = {
-            FLAG_SET_SYSTEM,
-            FLAG_SET_LOCK
+            FLAG_SYSTEM,
+            FLAG_LOCK
     })
     @Retention(RetentionPolicy.SOURCE)
     public @interface SetWallpaperFlags {}
@@ -170,12 +170,12 @@
     /**
      * Flag: use the supplied imagery as the general system wallpaper.
      */
-    public static final int FLAG_SET_SYSTEM = 1 << 0;
+    public static final int FLAG_SYSTEM = 1 << 0;
 
     /**
      * Flag: use the supplied imagery as the lock-screen wallpaper.
      */
-    public static final int FLAG_SET_LOCK = 1 << 1;
+    public static final int FLAG_LOCK = 1 << 1;
 
     private final Context mContext;
 
@@ -336,7 +336,7 @@
 
             try {
                 Bundle params = new Bundle();
-                ParcelFileDescriptor fd = mService.getWallpaper(this, FLAG_SET_SYSTEM,
+                ParcelFileDescriptor fd = mService.getWallpaper(this, FLAG_SYSTEM,
                         params, userId);
                 if (fd != null) {
                     try {
@@ -663,11 +663,18 @@
 
     /**
      * Get an open, readable file descriptor to the given wallpaper image file.
-     * The callee is resopnsible for closing the fd when done ingesting the file.
+     * The caller is responsible for closing the file descriptor when done ingesting the file.
      *
      * <p>If no lock-specific wallpaper has been configured for the given user, then
-     * this method will return {@code null} when requesting {@link #FLAG_SET_LOCK} rather than
+     * this method will return {@code null} when requesting {@link #FLAG_LOCK} rather than
      * returning the system wallpaper's image file.
+     *
+     * @param which The wallpaper whose image file is to be retrieved.  Must be a single
+     *     defined kind of wallpaper, either {@link #FLAG_SYSTEM} or
+     *     {@link #FLAG_LOCK}.
+     *
+     * @see #FLAG_LOCK
+     * @see #FLAG_SYSTEM
      */
     public ParcelFileDescriptor getWallpaperFile(int which) {
         return getWallpaperFile(which, mContext.getUserId());
@@ -677,10 +684,19 @@
      * Version of {@link #getWallpaperFile(int)} that can access the wallpaper data
      * for a given user.  The caller must hold the INTERACT_ACROSS_USERS_FULL
      * permission to access another user's wallpaper data.
+     *
+     * @param which The wallpaper whose image file is to be retrieved.  Must be a single
+     *     defined kind of wallpaper, either {@link #FLAG_SYSTEM} or
+     *     {@link #FLAG_LOCK}.
+     * @param userId The user or profile whose imagery is to be retrieved
+     *
+     * @see #FLAG_LOCK
+     * @see #FLAG_SYSTEM
+     *
      * @hide
      */
     public ParcelFileDescriptor getWallpaperFile(int which, int userId) {
-        if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) {
+        if (which != FLAG_SYSTEM && which != FLAG_LOCK) {
             throw new IllegalArgumentException("Must request exactly one kind of wallpaper");
         }
 
@@ -730,8 +746,8 @@
      * such wallpaper configured, returns a negative number.
      *
      * @param which The wallpaper whose ID is to be returned.  Must be a single
-     *     defined kind of wallpaper, either {@link #FLAG_SET_SYSTEM} or
-     *     {@link #FLAG_SET_LOCK}.
+     *     defined kind of wallpaper, either {@link #FLAG_SYSTEM} or
+     *     {@link #FLAG_LOCK}.
      * @return The positive numeric ID of the current wallpaper of the given kind,
      *     or a negative value if no such wallpaper is configured.
      */
@@ -823,24 +839,24 @@
      * <p>This method requires the caller to hold the permission
      * {@link android.Manifest.permission#SET_WALLPAPER}.
      *
-     * @param resid The bitmap to save.
+     * @param resid The resource ID of the bitmap to be used as the wallpaper image
      *
      * @throws IOException If an error occurs reverting to the built-in
      * wallpaper.
      */
     public void setResource(@RawRes int resid) throws IOException {
-        setResource(resid, FLAG_SET_SYSTEM);
+        setResource(resid, FLAG_SYSTEM);
     }
 
     /**
-     * Version of {@link #setResource(int)} that takes an optional Bundle for returning
-     * metadata about the operation to the caller.
+     * Version of {@link #setResource(int)} that allows the caller to specify which
+     * of the supported wallpaper categories to set.
      *
-     * @param resid
-     * @param which Flags indicating which wallpaper(s) to configure with the new imagery.
+     * @param resid The resource ID of the bitmap to be used as the wallpaper image
+     * @param which Flags indicating which wallpaper(s) to configure with the new imagery
      *
-     * @see #FLAG_SET_LOCK
-     * @see #FLAG_SET_SYSTEM
+     * @see #FLAG_LOCK
+     * @see #FLAG_SYSTEM
      *
      * @return An integer ID assigned to the newly active wallpaper; or zero on failure.
      *
@@ -934,11 +950,10 @@
      */
     public int setBitmap(Bitmap fullImage, Rect visibleCropHint, boolean allowBackup)
             throws IOException {
-        return setBitmap(fullImage, visibleCropHint, allowBackup, FLAG_SET_SYSTEM);
+        return setBitmap(fullImage, visibleCropHint, allowBackup, FLAG_SYSTEM);
     }
 
     /**
-    /**
      * Version of {@link #setBitmap(Bitmap, Rect, boolean)} that allows the caller
      * to specify which of the supported wallpaper categories to set.
      *
@@ -951,8 +966,8 @@
      *     image for restore to a future device; {@code false} otherwise.
      * @param which Flags indicating which wallpaper(s) to configure with the new imagery.
      *
-     * @see #FLAG_SET_LOCK
-     * @see #FLAG_SET_SYSTEM
+     * @see #FLAG_LOCK
+     * @see #FLAG_SYSTEM
      *
      * @return An integer ID assigned to the newly active wallpaper; or zero on failure.
      *
@@ -1054,7 +1069,7 @@
      */
     public int setStream(InputStream bitmapData, Rect visibleCropHint, boolean allowBackup)
             throws IOException {
-        return setStream(bitmapData, visibleCropHint, allowBackup, FLAG_SET_SYSTEM);
+        return setStream(bitmapData, visibleCropHint, allowBackup, FLAG_SYSTEM);
     }
 
     /**
@@ -1070,8 +1085,8 @@
      *     image for restore to a future device; {@code false} otherwise.
      * @param which Flags indicating which wallpaper(s) to configure with the new imagery.
      *
-     * @see #FLAG_SET_LOCK
-     * @see #FLAG_SET_SYSTEM
+     * @see #FLAG_LOCK
+     * @see #FLAG_SYSTEM
      *
      * @throws IOException
      */
@@ -1287,7 +1302,7 @@
      */
     @SystemApi
     public void clearWallpaper() {
-        clearWallpaper(FLAG_SET_SYSTEM, mContext.getUserId());
+        clearWallpaper(FLAG_SYSTEM, mContext.getUserId());
     }
 
     /**
@@ -1467,20 +1482,20 @@
 
     /**
      * Remove one or more currently set wallpapers, reverting to the system default
-     * display for each one.  If {@link #FLAG_SET_SYSTEM} is set in the {@code which}
+     * display for each one.  If {@link #FLAG_SYSTEM} is set in the {@code which}
      * parameter, the intent {@link Intent#ACTION_WALLPAPER_CHANGED} will be broadcast
      * upon success.
      *
-     * @param which A bitwise combination of {@link #FLAG_SET_SYSTEM} or
-     *   {@link #FLAG_SET_LOCK}
+     * @param which A bitwise combination of {@link #FLAG_SYSTEM} or
+     *   {@link #FLAG_LOCK}
      * @throws IOException If an error occurs reverting to the built-in wallpaper.
      */
     public void clear(int which) throws IOException {
-        if ((which & FLAG_SET_SYSTEM) != 0) {
+        if ((which & FLAG_SYSTEM) != 0) {
             clear();
         }
-        if ((which & FLAG_SET_LOCK) != 0) {
-            clearWallpaper(FLAG_SET_LOCK, mContext.getUserId());
+        if ((which & FLAG_LOCK) != 0) {
+            clearWallpaper(FLAG_LOCK, mContext.getUserId());
         }
     }
 
diff --git a/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java b/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java
index 65e7973..3812429 100644
--- a/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java
+++ b/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java
@@ -85,7 +85,7 @@
             // wallpaper.
             final int lockWallpaperUserId =
                     mSelectedUser != null ? mSelectedUser.getIdentifier() : mCurrentUserId;
-            ParcelFileDescriptor fd = mService.getWallpaper(null, WallpaperManager.FLAG_SET_LOCK,
+            ParcelFileDescriptor fd = mService.getWallpaper(null, WallpaperManager.FLAG_LOCK,
                     new Bundle(), lockWallpaperUserId);
             if (fd != null) {
                 try {
diff --git a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
index 4848523..1c5556f 100644
--- a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
+++ b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
@@ -16,8 +16,8 @@
 
 package com.android.server.wallpaper;
 
-import static android.app.WallpaperManager.FLAG_SET_SYSTEM;
-import static android.app.WallpaperManager.FLAG_SET_LOCK;
+import static android.app.WallpaperManager.FLAG_SYSTEM;
+import static android.app.WallpaperManager.FLAG_LOCK;
 import static android.os.ParcelFileDescriptor.*;
 
 import android.app.ActivityManager;
@@ -231,7 +231,7 @@
                                         false, wallpaper, null);
                             }
                             if (lockWallpaperChanged
-                                    || (wallpaper.whichPending & FLAG_SET_LOCK) != 0) {
+                                    || (wallpaper.whichPending & FLAG_LOCK) != 0) {
                                 if (DEBUG) {
                                     Slog.i(TAG, "Lock-relevant wallpaper changed");
                                 }
@@ -505,7 +505,7 @@
                                 && mWallpaper.lastDiedTime + MIN_WALLPAPER_CRASH_TIME
                                     > SystemClock.uptimeMillis()) {
                             Slog.w(TAG, "Reverting to built-in wallpaper!");
-                            clearWallpaperLocked(true, FLAG_SET_SYSTEM, mWallpaper.userId, null);
+                            clearWallpaperLocked(true, FLAG_SYSTEM, mWallpaper.userId, null);
                         } else {
                             mWallpaper.lastDiedTime = SystemClock.uptimeMillis();
                         }
@@ -584,7 +584,7 @@
                         if (!bindWallpaperComponentLocked(comp, false, false,
                                 wallpaper, null)) {
                             Slog.w(TAG, "Wallpaper no longer available; reverting to default");
-                            clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null);
+                            clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null);
                         }
                     }
                 }
@@ -664,7 +664,7 @@
                     if (doit) {
                         Slog.w(TAG, "Wallpaper uninstalled, removing: "
                                 + wallpaper.wallpaperComponent);
-                        clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null);
+                        clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null);
                     }
                 }
             }
@@ -684,7 +684,7 @@
                 } catch (NameNotFoundException e) {
                     Slog.w(TAG, "Wallpaper component gone, removing: "
                             + wallpaper.wallpaperComponent);
-                    clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null);
+                    clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null);
                 }
             }
             if (wallpaper.nextWallpaperComponent != null
@@ -746,7 +746,7 @@
                 if (DEBUG) {
                     Slog.i(TAG, "Unable to regenerate crop; resetting");
                 }
-                clearWallpaperLocked(false, FLAG_SET_SYSTEM, UserHandle.USER_SYSTEM, null);
+                clearWallpaperLocked(false, FLAG_SYSTEM, UserHandle.USER_SYSTEM, null);
             }
         } else {
             if (DEBUG) {
@@ -842,7 +842,7 @@
     void switchUser(int userId, IRemoteCallback reply) {
         synchronized (mLock) {
             mCurrentUserId = userId;
-            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM);
+            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM);
             // Not started watching yet, in case wallpaper data was loaded for other reasons.
             if (wallpaper.wallpaperObserver == null) {
                 wallpaper.wallpaperObserver = new WallpaperObserver(wallpaper);
@@ -865,7 +865,7 @@
                 e = e1;
             }
             Slog.w(TAG, "Failure starting previous wallpaper", e);
-            clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, reply);
+            clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, reply);
         }
     }
 
@@ -885,12 +885,12 @@
     }
 
     void clearWallpaperLocked(boolean defaultFailed, int which, int userId, IRemoteCallback reply) {
-        if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) {
+        if (which != FLAG_SYSTEM && which != FLAG_LOCK) {
             throw new IllegalArgumentException("Must specify exactly one kind of wallpaper to read");
         }
 
         WallpaperData wallpaper = null;
-        if (which == FLAG_SET_LOCK) {
+        if (which == FLAG_LOCK) {
             wallpaper = mLockWallpaperMap.get(userId);
             if (wallpaper == null) {
                 // It's already gone; we're done.
@@ -916,7 +916,7 @@
             if (wallpaper.wallpaperFile.exists()) {
                 wallpaper.wallpaperFile.delete();
                 wallpaper.cropFile.delete();
-                if (which == FLAG_SET_LOCK) {
+                if (which == FLAG_LOCK) {
                     mLockWallpaperMap.remove(userId);
                     final IWallpaperManagerCallback cb = mKeyguardListener;
                     if (cb != null) {
@@ -1008,7 +1008,7 @@
         }
         synchronized (mLock) {
             int userId = UserHandle.getCallingUserId();
-            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM);
+            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM);
             if (width <= 0 || height <= 0) {
                 throw new IllegalArgumentException("width and height must be > 0");
             }
@@ -1070,7 +1070,7 @@
         }
         synchronized (mLock) {
             int userId = UserHandle.getCallingUserId();
-            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM);
+            WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM);
             if (padding.left < 0 || padding.top < 0 || padding.right < 0 || padding.bottom < 0) {
                 throw new IllegalArgumentException("padding must be positive: " + padding);
             }
@@ -1103,13 +1103,13 @@
         wallpaperUserId = ActivityManager.handleIncomingUser(Binder.getCallingPid(),
                 Binder.getCallingUid(), wallpaperUserId, false, true, "getWallpaper", null);
 
-        if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) {
+        if (which != FLAG_SYSTEM && which != FLAG_LOCK) {
             throw new IllegalArgumentException("Must specify exactly one kind of wallpaper to read");
         }
 
         synchronized (mLock) {
             final SparseArray<WallpaperData> whichSet =
-                    (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap;
+                    (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap;
             WallpaperData wallpaper = whichSet.get(wallpaperUserId);
             if (wallpaper == null) {
                 // common case, this is the first lookup post-boot of the system or
@@ -1157,12 +1157,12 @@
         userId = ActivityManager.handleIncomingUser(Binder.getCallingPid(),
                 Binder.getCallingUid(), userId, false, true, "getWallpaperIdForUser", null);
 
-        if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) {
+        if (which != FLAG_SYSTEM && which != FLAG_LOCK) {
             throw new IllegalArgumentException("Must specify exactly one kind of wallpaper");
         }
 
         final SparseArray<WallpaperData> map =
-                (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap;
+                (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap;
         synchronized (mLock) {
             WallpaperData wallpaper = map.get(userId);
             if (wallpaper != null) {
@@ -1186,7 +1186,7 @@
             Rect cropHint, Bundle extras, int which, IWallpaperManagerCallback completion) {
         checkPermission(android.Manifest.permission.SET_WALLPAPER);
 
-        if ((which & (FLAG_SET_LOCK|FLAG_SET_SYSTEM)) == 0) {
+        if ((which & (FLAG_LOCK|FLAG_SYSTEM)) == 0) {
             Slog.e(TAG, "Must specify a valid wallpaper category to set");
             return null;
         }
@@ -1637,7 +1637,7 @@
         // Combined or just-system operations use the 'system' WallpaperData
         // for this use; lock-only operations use the dedicated one.
         final SparseArray<WallpaperData> whichSet =
-                (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap;
+                (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap;
         WallpaperData wallpaper = whichSet.get(userId);
         if (wallpaper == null) {
             // common case, this is the first lookup post-boot of the system or
@@ -1648,7 +1648,7 @@
             // yet a lock-only wallpaper set for this user, so we need to establish
             // it now.
             if (wallpaper == null) {
-                if (which == FLAG_SET_LOCK) {
+                if (which == FLAG_LOCK) {
                     wallpaper = new WallpaperData(userId,
                             WALLPAPER_LOCK_ORIG, WALLPAPER_LOCK_CROP);
                     mLockWallpaperMap.put(userId, wallpaper);