Add IRestoreSession interface for the restore flow

Restore is a fairly complicated, somewhat stateful process, so we introduce
a new interface to encapsulate the various bits and pieces into a nicely
separable component.  In particular, this will make it much cleaner to
open and interrogate an expensive-to-construct transport and then reuse it
for the actual restore process itself.

2 files changed, 62 insertions, 0 deletions

diff --git a/core/java/android/backup/IBackupManager.aidl b/core/java/android/backup/IBackupManager.aidl
index f5b82fe..1054642 100644
--- a/core/java/android/backup/IBackupManager.aidl
+++ b/core/java/android/backup/IBackupManager.aidl
@@ -16,6 +16,8 @@
 
 package android.backup;
 
+import android.backup.IRestoreSession;
+
 /**
  * Direct interface to the Backup Manager Service that applications invoke on.  The only
  * operation currently needed is a simple notification that the app has made changes to
@@ -60,4 +62,12 @@ interface IBackupManager {
      * @return The ID of the previously selected transport.
      */
     int selectBackupTransport(int transportID);
+
+    /**
+     * Begin a restore session with the given transport (which may differ from the
+     * currently-active backup transport).
+     *
+     * @return An interface to the restore session, or null on error.
+     */
+    IRestoreSession beginRestoreSession(int transportID);
 }
diff --git a/core/java/android/backup/IRestoreSession.aidl b/core/java/android/backup/IRestoreSession.aidl
new file mode 100644
index 0000000..63b29a2
--- /dev/null
+++ b/core/java/android/backup/IRestoreSession.aidl
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.backup;
+
+import android.os.Bundle;
+
+/**
+ * Binder interface used by clients who wish to manage a restore operation.  Every
+ * method in this interface requires the android.permission.BACKUP permission.
+ *
+ * {@hide}
+ */
+interface IRestoreSession {
+    /**
+     * Ask the current transport what the available restore sets are.
+     *
+     * @return A bundle containing two elements:  an int array under the key
+     *   "tokens" whose entries are a transport-private identifier for each backup set;
+     *   and a String array under the key "names" whose entries are the user-meaningful
+     *   text corresponding to the backup sets at each index in the tokens array.
+     */
+    Bundle getAvailableRestoreSets();
+
+    /**
+     * 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.
+     *
+     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
+     *   the restore set that should be used.
+     */
+    int performRestore(int token);
+
+    /**
+     * End this restore session.  After this method is called, the IRestoreSession binder
+     * is no longer valid.
+     */
+    void endRestoreSession();
+}