bmgr lets you inspect and control the backup/restore system on an Android device.
+
bmgr lets you control the backup/restore system on an Android device.
bmgr is a shell tool that developers can use to interact with the Backup Manager
-on Android devices supporting API version 8 or later. It provides commands for inducing backup
-and restore operations on demand so that you do not need to repeatedly wipe data or take similar
-intrusive steps to test the operation of an application's backup agent. These commands are
+
bmgr is a shell tool you can use to interact with the Backup Manager
+on Android devices supporting API Level 8 or greater. It provides commands to induce backup
+and restore operations so that you don't need to repeatedly wipe data or take similar
+intrusive steps in order to test your application's backup agent. These commands are
accessed via the adb shell.
-
There are a couple of basic concepts used by the Backup Manager that are built into the way
-that bmgr operates. These are backup transports and
-restore sets.
-
-
A backup transport is the code module responsible for moving backup and restore data +
Normally, your application must notify the Backup Manager when its data has changed, via {@link
+android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
+backup agent's {@link
+android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
+onBackup()} implementation at some time in the future. However, instead of calling {@link
+android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
+line by running the bmgr backup command:
+
+
adb shell bmgr backup <package>+ +
<package> is the formal package name of the application you wish to
+schedule for
+backup. When you execute this backup command, your application's backup agent will be invoked to
+perform a backup operation at some time in the future (via your {@link
+android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
+onBackup()} method), though there is no guarantee when it will occur. However, you can force all
+pending backup operations to run immediately by using the bmgr run command:
+
+
adb shell bmgr run+ +
This causes a backup pass to execute immediately, invoking the backup agents of all applications
+that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
+last backup operation, plus any applications which had been manually scheduled for
+backup via bmgr backup.
+
+
+
+
Unlike backup operations, which are batched together and run on an occasional basis, restore +operations execute immediately. The Backup Manager currently provides two kinds of restore +operations. The first kind restores an entire device with the data that has been backed up. This +is typically performed only when a device is first provisioned (to replicate settings and other +saved state from the user's previous device) and is an operation that only the system can +perform. The second kind of restore operation restores +a single application to its "active" data set; that is, the application will abandon its current +data and revert to the last-known-good data that is held in the current backup image. You can +invoke this second restore operation with the {@link +android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The +Backup Manager will then invoke your backup agent's {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} implementation. + +
While testing your application, you can immediately invoke the restore operation (bypassing the
+{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
+for your application by using the bmgr restore command:
+
+
adb shell bmgr restore <package>+ +
<package> is the formal Java-style package name of the application
+participating in the backup/restore mechanism, which you would like to restore. The Backup
+Manager will immediately instantiate the application's backup agent and invoke it for restore. This
+will happen even if your application is not currently running.
+
+
+
+
+
+
The data for a single application can be erased from the active data set on demand. This is
+very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
+or saved state information. You can wipe an application's data with the bmgr wipe
+command:
+
+
adb shell bmgr wipe <package>+ +
<package> is the formal package name of the application whose data
+you wish to
+erase. The next backup operation that the application's agent processes will look as
+though the application had never backed anything up before.
+
+
You can see whether the Backup Manager is operational at all with the bmgr
+enabled command:
+
+
adb shell bmgr enabled+ +
This might be useful if your application's backup agent is never being invoked for backup, to +verify whether the operating system thinks it should be performing such operations at all.
+ +You can also directly disable or enable the Backup Manager with this command: + +
adb shell bmgr enable <boolean>+ +
<boolean> is either true or false.
+This is equivalent to disabling or enabling backup in the device's main Settings UI.
Warning! When backup is disabled, the current backup transport
+will explicitly wipe
+the entire active data set from its backend storage. This is so that when a user says
+they do not want their data backed up, the Backup Manager respects that wish. No further
+data will be saved from the device, and no restore operations will be possible, unless the Backup
+Manager is re-enabled (either through Settings or through the above bmgr command).
+
+
+
+
+
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 269e807d8c709..8f66bddb5d6e5 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -282,7 +282,8 @@