bmgr lets you inspect and 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
+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
+to and from some storage location. A device can have multipe transports installed, though only
+one is active at any given time. Transports are identified by name. You can see what
+transports are available on your device or emulator by running the
+bmgr list transports command:
+
+
adb shell bmgr list transports+ +
The output of this command is a list of the transports available on the device. The currently
+active transport is flagged with a * character. Transport names may look like
+component names -- for example, android/com.android.internal.backup.LocalTransport --
+but they need not be, and the strings are never used as direct class references. The use of
+a component-like naming scheme is simply for purposes of preventing name collisions.
+
+
You can change which transport is currently active from the command line as well: + +
adb shell bmgr transport NAME+ +
where NAME is one of the names as printed by the bmgr list transports
+command. From this point forward, backup and restore operations will be directed through the
+newly-selected transport. Backup state tracking is managed separately for each transport, so
+switching back and forth between them will not corrupt the saved state.
+
+
+
+
All of the application data that a device has written to a given backup transport is tracked +together, and is collectively sometimes called a restore set, because the typical use +of the data set is during restore operations. Each time a device is initially provisioned, a +new data set is established. The user can get a listing of all the data sets that can be +restored through the current transport by running this shell command: + +
adb shell bmgr list sets+ +
The output is listing of available restore sets, one per line. The first item on each line is +a token, a number in hexadecimal that identifies the restore set to the transport. After +that is a string that may provide some brief identifying information about the restore set. Only +the token is actually used within the backup and restore mechanism. + + + +
Normally, applications notify the backup manager directly that their data has changed, in +response to which the backup manager will make sure to invoke that application's agent when the +next backup operation is run. You can simulate this manually from the command line if you wish, +by running this shell command: + +
adb shell bmgr backup PACKAGE+ +
PACKAGE is the formal package name of the application you wish to schedule for
+backup. At this point you know that the application's agent will be invoked for backup at some
+point in the future, though there is no hard guarantee of when that will occur. You can force
+all pending backup operations to run immediately by using the following command:
+
+
adb shell bmgr run+ +
This causes a backup pass to execute immediately, invoking the agents of all applications that
+had called BackupManager.dataChanged() since the time of the last backup operation,
+plus any applications which had been manually scheduled for backup via
+bmgr backup PACKAGE.
+
+
+
+
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 restores an entire device with the data from a given restore set. This +is typically only performed when a device is first provisioned, to replicate settings and other +such saved state from the user's previous device. The second kind of restore operation restores +a single application from the active data set; that is, from the data set currently +being written to by backup operations. This second form is available as part of the public API. +It allows applications to abandon their current data and revert to the last-known-good data as +represented in their current backup image. + +
A full-system restore operation can be initiated with this shell command: + +
adb shell bmgr restore TOKEN+ +
where TOKEN is the desired restore set's token as printed out by the bmgr
+list sets command. Warning! This operation will replace the
+data of all backup-enabled applications with the contents of the given restore set. Be careful,
+and be aware of the potential consequences.
+
+
A single-application restore operation does not reference a restore set token; it always uses +the data from the currently active data set. You can induce such an operation from the command +line like this: + +
adb shell bmgr restore PACKAGE+ +
PACKAGE is the formal package name of an application that is participating in the
+backup/restore mechanism. The backup manager will immediately instantiate the application's
+agent and invoke it for restore.
+
+
+
The data for a single application can be erased from the active data set on demand. This is +very useful during development of backup agents, in case bugs lead you to write corrupt data +or saved state information. The shell command for wiping an application's data is this: + +
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 by running this command: + +
adb shell bmgr enabled+ +
This might be useful if your application's 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+ +
where 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 transport will explicitly wipe
+the entire active data set from its backend storage. This is so that when a user says that no,
+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 fd163f6b2ba26..269e807d8c709 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -282,6 +282,7 @@