Merge change 3506 into donut

* changes:
  Revamp IRestoreSession a bit

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
+ * {@link android.app.BackupAgent} subclass declared in your manifest.  See the
- * for {@link BackupService} for a detailed description of how the backup then proceeds.
+ * 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;
+    }
 }

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

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;

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();
+    }
+}

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 {
+    public RestoreSet[] getAvailableRestoreSets() throws android.os.RemoteException {
-        // !!! TODO: real implementation
+        RestoreSet[] set = new RestoreSet[1];
-        Bundle b = new Bundle();
+        set[0].device = "USB";
-        b.putIntArray("tokens", new int[0]);
+        set[0].name = "adb";
-        b.putStringArray("names", new String[0]);
+        set[0].token = 0;
-        return b;
+        return set;
     }
 
     public PackageInfo[] getAppSet(int token) throws android.os.RemoteException {

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();
+        return null;
-        b.putIntArray("tokens", new int[0]);
-        b.putStringArray("names", new String[0]);
-        return b;
     }
 
     public PackageInfo[] getAppSet(int token) throws android.os.RemoteException {

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.

services/java/com/android/server/BackupManagerService.java

@@ -44,6 +44,7 @@ import android.util.SparseArray;
 import android.backup.IBackupManager;
 import android.backup.IRestoreSession;
 import android.backup.BackupManager;
+import android.backup.RestoreSet;
 
 import com.android.internal.backup.AdbTransport;
 import com.android.internal.backup.GoogleTransport;
@@ -617,6 +618,36 @@ class BackupManagerService extends IBackupManager.Stub {
         return null;
     }
 
+    // ----- Restore session -----
+
+    class RestoreSession extends IRestoreSession.Stub {
+        private IBackupTransport mRestoreTransport = null;
+        RestoreSet[] mRestoreSets = null;
+
+        RestoreSession(int transportID) {
+            mRestoreTransport = createTransport(transportID);
+        }
+
+        // --- Binder interface ---
+        public RestoreSet[] getAvailableRestoreSets() throws android.os.RemoteException {
+            synchronized(this) {
+                if (mRestoreSets == null) {
+                    mRestoreSets = mRestoreTransport.getAvailableRestoreSets();
+                }
+                return mRestoreSets;
+            }
+        }
+
+        public int performRestore(int token) throws android.os.RemoteException {
+            return -1;
+        }
+
+        public void endRestoreSession() throws android.os.RemoteException {
+            mRestoreTransport.endSession();
+            mRestoreTransport = null;
+        }
+    }
+
 
     @Override
     public void dump(FileDescriptor fd, PrintWriter pw, String[] args) {