Add single-package restore from an app's most-recent data

Renamed the RestoreSession performRestore() method to restoreAll(), and
added a new restorePackage() method that only restores the single
specified app.  In order to restore an app other than itself, the
caller must hold the android.permission.BACKUP permission.

This change also introduces dataset tracking:  the Backup Manager
persistently remembers both the current backup dataset's identity
and that of the "ancestral" dataset, i.e. the one most recently used
for a whole-device restore such as performed by SetupWizard.  When a
single package is restored via restorePackage(), the selection of
most-recent dataset to use is this:

1. The data from the currently-active backup dataset, if such exists.
   An app that has ever backed up data will therefore get its last-
   known-good data.

2. The app's data from the ancestral dataset, if such exists.  This
   covers the case of a factory reset followed by reinstallation of
   an app at a later time.  The app had not yet backed anything up
   post-wipe, but the old data is in the ancestral dataset and should
   be brought forward when the app reappears.

3. If neither 1. nor 2. exist, there is no data to restore, so just
   skip it and return failure.

Note that the infrastructure to automatically attempt a restore after
an application has been installed does not yet exist; that's coming.

Change-Id: I0ba170df9885128000c46ed28d3dddda3a63a143

2 files changed, 60 insertions, 10 deletions

diff --git a/core/java/android/backup/IRestoreSession.aidl b/core/java/android/backup/IRestoreSession.aidl
index fd40d98..bead395 100644
--- a/core/java/android/backup/IRestoreSession.aidl
+++ b/core/java/android/backup/IRestoreSession.aidl
@@ -40,6 +40,8 @@ interface IRestoreSession {
      * Restore the given set onto the device, replacing the current data of any app
      * contained in the restore set with the data previously backed up.
      *
+     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
+     *
      * @return Zero on success; nonzero on error.  The observer will only receive
      *   progress callbacks if this method returned zero.
      * @param token The token from {@link getAvailableRestoreSets()} corresponding to
@@ -47,7 +49,24 @@ interface IRestoreSession {
      * @param observer If non-null, this binder points to an object that will receive
      *   progress callbacks during the restore operation.
      */
-    int performRestore(long token, IRestoreObserver observer);
+    int restoreAll(long token, IRestoreObserver observer);
+
+    /**
+     * Restore a single application from backup.  The data will be restored from the
+     * current backup dataset if the given package has stored data there, or from
+     * the dataset used during the last full device setup operation if the current
+     * backup dataset has no matching data.  If no backup data exists for this package
+     * in either source, a nonzero value will be returned.
+     *
+     * @return Zero on success; nonzero on error.  The observer will only receive
+     *   progress callbacks if this method returned zero.
+     * @param packageName The name of the package whose data to restore.  If this is
+     *   not the name of the caller's own package, then the android.permission.BACKUP
+     *   permission must be held.
+     * @param observer If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
+     */
+    int restorePackage(in String packageName, IRestoreObserver observer);
 
     /**
      * End this restore session.  After this method is called, the IRestoreSession binder
diff --git a/core/java/android/backup/RestoreSession.java b/core/java/android/backup/RestoreSession.java
index 6b35fe8..d10831e 100644
--- a/core/java/android/backup/RestoreSession.java
+++ b/core/java/android/backup/RestoreSession.java
@@ -58,25 +58,56 @@ public class RestoreSession {
      * Restore the given set onto the device, replacing the current data of any app
      * contained in the restore set with the data previously backed up.
      *
+     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
+     *
      * @return Zero on success; nonzero on error.  The observer will only receive
      *   progress callbacks if this method returned zero.
-     * @param token The token from {@link #getAvailableRestoreSets()} corresponding to
+     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
      *   the restore set that should be used.
-     * @param observer If non-null, this argument points to an object that will receive
-     *   progress callbacks during the restore operation. These callbacks will occur
-     *   on the main thread of the application.
+     * @param observer If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
+     */
+    public int restoreAll(long token, RestoreObserver observer) {
+        int err = -1;
+        if (mObserver != null) {
+            Log.d(TAG, "restoreAll() called during active restore");
+            return -1;
+        }
+        mObserver = new RestoreObserverWrapper(mContext, observer);
+        try {
+            err = mBinder.restoreAll(token, mObserver);
+        } catch (RemoteException e) {
+            Log.d(TAG, "Can't contact server to restore");
+        }
+        return err;
+    }
+
+    /**
+     * Restore a single application from backup.  The data will be restored from the
+     * current backup dataset if the given package has stored data there, or from
+     * the dataset used during the last full device setup operation if the current
+     * backup dataset has no matching data.  If no backup data exists for this package
+     * in either source, a nonzero value will be returned.
+     *
+     * @return Zero on success; nonzero on error.  The observer will only receive
+     *   progress callbacks if this method returned zero.
+     * @param packageName The name of the package whose data to restore.  If this is
+     *   not the name of the caller's own package, then the android.permission.BACKUP
+     *   permission must be held.
+     * @param observer If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
      */
-    public int performRestore(long token, RestoreObserver observer) {
+    public int restorePackage(String packageName, RestoreObserver observer) {
         int err = -1;
         if (mObserver != null) {
-            Log.d(TAG, "performRestore() called during active restore");
+            Log.d(TAG, "restorePackage() called during active restore");
             return -1;
         }
         mObserver = new RestoreObserverWrapper(mContext, observer);
         try {
-            err = mBinder.performRestore(token, mObserver);
+            err = mBinder.restorePackage(packageName, mObserver);
         } catch (RemoteException e) {
-            Log.d(TAG, "Can't contact server to perform restore");
+            Log.d(TAG, "Can't contact server to restore package");
         }
         return err;
     }
@@ -87,7 +118,7 @@ public class RestoreSession {
      *
      * <p><b>Note:</b> The caller <i>must</i> invoke this method to end the restore session,
      *   even if {@link #getAvailableRestoreSets()} or
-     *   {@link #performRestore(long, RestoreObserver)} failed.
+     *   {@link #restorePackage(long, String, RestoreObserver)} failed.
      */
     public void endRestoreSession() {
         try {