Revamp IRestoreSession a bit

We now supply an array of RestoreSet objects instead of wacky Bundle
shenanigans.  Also, pushed beginRestoreSession() out to the BackupManager
concrete interface class so that SetupWizard can use it.

(beginRestoreSession() is @hide, non-privileged apps cannot use it.  It's
also guarded by android.permission.BACKUP enforcement.)

7 files changed, 140 insertions, 20 deletions

diff --git a/core/java/android/backup/BackupManager.java b/core/java/android/backup/BackupManager.java
index 30f781e..c3b6a02 100644
--- a/core/java/android/backup/BackupManager.java
+++ b/core/java/android/backup/BackupManager.java
@@ -32,8 +32,9 @@ import android.os.ServiceManager;
  * until the backup operation actually occurs.
  *
  * <p>The backup operation itself begins with the system launching the
- * {@link BackupService} subclass declared in your manifest.  See the documentation
- * for {@link BackupService} for a detailed description of how the backup then proceeds.
+ * {@link android.app.BackupAgent} subclass declared in your manifest.  See the
+ * documentation for {@link android.app.BackupAgent} for a detailed description
+ * of how the backup then proceeds.
  *
  * @hide pending API solidification
  */
@@ -64,7 +65,7 @@ public class BackupManager {
     /**
      * Notifies the Android backup system that your application wishes to back up
      * new changes to its data.  A backup operation using your application's
-     * {@link BackupService} subclass will be scheduled when you call this method.
+     * {@link android.app.BackupAgent} subclass will be scheduled when you call this method.
      */
     public void dataChanged() {
         try {
@@ -72,4 +73,20 @@ public class BackupManager {
         } catch (RemoteException e) {
         }
     }
+
+    /**
+     * Begin the process of restoring system data from backup.  This method requires
+     * that the application hold the "android.permission.BACKUP" permission, and is
+     * not public.
+     *
+     * {@hide}
+     */
+    public IRestoreSession beginRestoreSession(int transportID) {
+        IRestoreSession binder = null;
+        try {
+            binder = mService.beginRestoreSession(transportID);
+        } catch (RemoteException e) {
+        }
+        return binder;
+    }
 }
diff --git a/core/java/android/backup/IRestoreSession.aidl b/core/java/android/backup/IRestoreSession.aidl
index 63b29a2..6bca865 100644
--- a/core/java/android/backup/IRestoreSession.aidl
+++ b/core/java/android/backup/IRestoreSession.aidl
@@ -16,7 +16,7 @@
 
 package android.backup;
 
-import android.os.Bundle;
+import android.backup.RestoreSet;
 
 /**
  * Binder interface used by clients who wish to manage a restore operation.  Every
@@ -33,7 +33,7 @@ interface IRestoreSession {
      *   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();
+    RestoreSet[] getAvailableRestoreSets();
 
     /**
      * Restore the given set onto the device, replacing the current data of any app
diff --git a/core/java/android/backup/RestoreSet.aidl b/core/java/android/backup/RestoreSet.aidl
new file mode 100644
index 0000000..42e77bf
--- /dev/null
+++ b/core/java/android/backup/RestoreSet.aidl
@@ -0,0 +1,19 @@
+/*
+ * 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;
+
+parcelable RestoreSet;
\ No newline at end of file
diff --git a/core/java/android/backup/RestoreSet.java b/core/java/android/backup/RestoreSet.java
new file mode 100644
index 0000000..7f09af3
--- /dev/null
+++ b/core/java/android/backup/RestoreSet.java
@@ -0,0 +1,87 @@
+/*
+ * 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.Parcel;
+import android.os.Parcelable;
+
+/**
+ * Descriptive information about a set of backed-up app data available for restore.
+ * Used by IRestoreSession clients.
+ *
+ * @hide
+ */
+public class RestoreSet implements Parcelable {
+    /**
+     * Name of this restore set.  May be user generated, may simply be the name
+     * of the handset model, e.g. "T-Mobile G1".
+     */
+    public String name;
+
+    /**
+     * Identifier of the device whose data this is.  This will be as unique as
+     * is practically possible; for example, it might be an IMEI.
+     */
+    public String device;
+
+    /**
+     * Token that identifies this backup set unambiguously to the backup/restore
+     * transport.  This is guaranteed to be valid for the duration of a restore
+     * session, but is meaningless once the session has ended.
+     */
+    public int token;
+
+
+    RestoreSet() {
+        // Leave everything zero / null
+    }
+
+    RestoreSet(String _name, String _dev, int _token) {
+        name = _name;
+        device = _dev;
+        token = _token;
+    }
+
+
+    // Parcelable implementation
+    public int describeContents() {
+        return 0;
+    }
+
+    public void writeToParcel(Parcel out, int flags) {
+        out.writeString(name);
+        out.writeString(device);
+        out.writeInt(token);
+    }
+
+    public static final Parcelable.Creator<RestoreSet> CREATOR
+            = new Parcelable.Creator<RestoreSet>() {
+        public RestoreSet createFromParcel(Parcel in) {
+            return new RestoreSet(in);
+        }
+
+        public RestoreSet[] newArray(int size) {
+            return new RestoreSet[size];
+        }
+    };
+
+    private RestoreSet(Parcel in) {
+        name = in.readString();
+        device = in.readString();
+        token = in.readInt();
+    }
+}
\ No newline at end of file
diff --git a/core/java/com/android/internal/backup/AdbTransport.java b/core/java/com/android/internal/backup/AdbTransport.java
index 46f0ed1..d8a2186 100644
--- a/core/java/com/android/internal/backup/AdbTransport.java
+++ b/core/java/com/android/internal/backup/AdbTransport.java
@@ -1,7 +1,7 @@
 package com.android.internal.backup;
 
+import android.backup.RestoreSet;
 import android.content.pm.PackageInfo;
-import android.os.Bundle;
 import android.os.ParcelFileDescriptor;
 import android.os.RemoteException;
 
@@ -30,12 +30,12 @@ public class AdbTransport extends IBackupTransport.Stub {
     }
 
     // Restore handling
-    public Bundle getAvailableRestoreSets() throws android.os.RemoteException {
-        // !!! TODO: real implementation
-        Bundle b = new Bundle();
-        b.putIntArray("tokens", new int[0]);
-        b.putStringArray("names", new String[0]);
-        return b;
+    public RestoreSet[] getAvailableRestoreSets() throws android.os.RemoteException {
+        RestoreSet[] set = new RestoreSet[1];
+        set[0].device = "USB";
+        set[0].name = "adb";
+        set[0].token = 0;
+        return set;
     }
 
     public PackageInfo[] getAppSet(int token) throws android.os.RemoteException {
diff --git a/core/java/com/android/internal/backup/GoogleTransport.java b/core/java/com/android/internal/backup/GoogleTransport.java
index c20a957..06deec4 100644
--- a/core/java/com/android/internal/backup/GoogleTransport.java
+++ b/core/java/com/android/internal/backup/GoogleTransport.java
@@ -1,7 +1,7 @@
 package com.android.internal.backup;
 
+import android.backup.RestoreSet;
 import android.content.pm.PackageInfo;
-import android.os.Bundle;
 import android.os.ParcelFileDescriptor;
 import android.os.RemoteException;
 
@@ -28,12 +28,9 @@ public class GoogleTransport extends IBackupTransport.Stub {
     }
 
     // Restore handling
-    public Bundle getAvailableRestoreSets() throws android.os.RemoteException {
+    public RestoreSet[] getAvailableRestoreSets() throws android.os.RemoteException {
         // !!! TODO: real implementation
-        Bundle b = new Bundle();
-        b.putIntArray("tokens", new int[0]);
-        b.putStringArray("names", new String[0]);
-        return b;
+        return null;
     }
 
     public PackageInfo[] getAppSet(int token) throws android.os.RemoteException {
diff --git a/core/java/com/android/internal/backup/IBackupTransport.aidl b/core/java/com/android/internal/backup/IBackupTransport.aidl
index 1d59175..4821fd0 100644
--- a/core/java/com/android/internal/backup/IBackupTransport.aidl
+++ b/core/java/com/android/internal/backup/IBackupTransport.aidl
@@ -16,8 +16,8 @@
 
 package com.android.internal.backup;
 
+import android.backup.RestoreSet;
 import android.content.pm.PackageInfo;
-import android.os.Bundle;
 import android.os.ParcelFileDescriptor;
 
 /** {@hide} */
@@ -69,7 +69,7 @@ interface IBackupTransport {
      *   and a String array under the key "names" whose entries are the user-meaningful
      *   names corresponding to the backup sets at each index in the tokens array.
      **/
-    Bundle getAvailableRestoreSets();
+    RestoreSet[] getAvailableRestoreSets();
 
     /**
      * Get the set of applications from a given backup image.