Merge change 811 into donut

* changes:
  Add android.backup.BackupManager

api/current.xml

@@ -21742,6 +21742,36 @@
 </package>
 <package name="android.backup"
 >
+<class name="BackupManager"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<constructor name="BackupManager"
+ type="android.backup.BackupManager"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="context" type="android.content.Context">
+</parameter>
+</constructor>
+<method name="dataChanged"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+</class>
 <class name="BackupService"
  extends="android.app.Service"
  abstract="true"

core/java/android/backup/BackupManager.java

@@ -0,0 +1,67 @@
+/*
+ * 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.content.Context;
+import android.os.RemoteException;
+import android.os.ServiceManager;
+
+/**
+ * BackupManager is the interface to the system's backup service.
+ * Applications simply instantiate one, and then use that instance
+ * to communicate with the backup infrastructure.
+ *
+ * <p>When your application has made changes to data it wishes to have
+ * backed up, call {@link #dataChanged()} to notify the backup service.
+ * The system will then schedule a backup operation to occur in the near
+ * future.  Repeated calls to {@link #dataChanged()} have no further effect
+ * 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.
+ */
+public class BackupManager {
+    private Context mContext;
+    private IBackupManager mService;
+
+    /**
+     * Constructs a BackupManager object through which the application can
+     * communicate with the Android backup system.
+     * 
+     * @param context The {@link android.content.Context} that was provided when
+     *                one of your application's {@link android.app.Activity Activities}
+     *                was created.
+     */
+    public BackupManager (Context context) {
+        mContext = context;
+        mService = IBackupManager.Stub.asInterface(
+                ServiceManager.getService(Context.BACKUP_SERVICE));
+    }
+
+    /**
+     * 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.
+     */
+    public void dataChanged() {
+        try {
+            mService.dataChanged(mContext.getPackageName());
+        } catch (RemoteException e) {
+        }
+    }
+}

core/java/android/backup/BackupService.java

@@ -29,6 +29,19 @@ import android.util.Log;
  * This is the central interface between an application and Android's
  * settings backup mechanism.
  * 
+ * In order to use the backup service, your application must implement a
+ * subclass of BackupService, and declare an intent filter
+ * in the application manifest specifying that your BackupService subclass
+ * handles the {link #SERVICE_ACTION} intent action.  For example:
+ * 
+ * <pre class="prettyprint">
+ *      &lt;!-- Use the class "MyBackupService" to perform backups for my app --&gt;
+ *      &lt;service android:name=".MyBackupService"&gt;
+ *          &lt;intent-filter&gt;
+ *              &lt;action android:name="android.service.action.BACKUP"&gt;
+ *          &lt;/intent-filter&gt;
+ *      &lt;/service&gt;</pre>
+ * 
  * <p><em>Not hidden but API subject to change and should not be published</em>
  */
 

core/java/android/backup/IBackupManager.aidl

@@ -21,12 +21,15 @@ package android.backup;
  * operation currently needed is a simple notification that the app has made changes to
  * data it wishes to back up, so the system should run a backup pass.
  *
- * {@hide pending API solidification}
+ * Apps will use the {@link android.backup.BackupManager} class rather than going through
+ * this Binder interface directly.
+ * 
+ * {@hide}
  */
 interface IBackupManager {
     /**
      * Tell the system service that the caller has made changes to its
      * data, and therefore needs to undergo a backup pass.
      */
-    oneway void dataChanged();
+    oneway void dataChanged(String packageName);
 }

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

@@ -164,7 +164,7 @@ class BackupManagerService extends IBackupManager.Stub {
     
     // ----- IBackupManager binder interface -----
     
-    public void dataChanged() throws RemoteException {
+    public void dataChanged(String packageName) throws RemoteException {
         // Record that we need a backup pass for the caller.  Since multiple callers
         // may share a uid, we need to note all candidates within that uid and schedule
         // a backup pass for each of them.
@@ -173,10 +173,14 @@ class BackupManagerService extends IBackupManager.Stub {
         if (targets != null) {
             synchronized (mQueueLock) {
                 // Note that this client has made data changes that need to be backed up
-                // !!! add them to the set of pending packages
                 for (ServiceInfo service : targets) {
-                    if (mPendingBackups.add(service)) {
+                    // validate the caller-supplied package name against the known set of
-                        // !!! TODO: write to the pending-backup journal file in case of crash
+                    // packages associated with this uid
+                    if (service.packageName.equals(packageName)) {
+                        // add the caller to the set of pending backups
+                        if (mPendingBackups.add(service)) {
+                            // !!! TODO: write to the pending-backup journal file in case of crash
+                        }
                     }
                 }