public class BackupManager extends Object
When an application has made changes to data which should be backed up, a
call to dataChanged()
will notify the backup service. The system
will then schedule a backup operation to occur in the near future. Repeated
calls to dataChanged()
have no further effect until the backup
operation actually occurs.
A backup or restore operation for your application begins when the system launches the
BackupAgent
subclass you've declared in your manifest. See the
documentation for BackupAgent
for a detailed description
of how the operation then proceeds.
Several attributes affecting the operation of the backup and restore mechanism
can be set on the
<application>
tag in your application's AndroidManifest.xml file.
For more information about using BackupManager, read the Data Backup developer guide.
Modifier and Type | Field and Description |
---|---|
static int |
ERROR_AGENT_FAILURE
The
BackupAgent for the requested package failed for some reason
and didn't provide appropriate backup data. |
static int |
ERROR_BACKUP_NOT_ALLOWED
Indicates that backup is either not enabled at all or
backup for the package was rejected by backup service
or backup transport,
|
static int |
ERROR_PACKAGE_NOT_FOUND
The requested app is not installed on the device.
|
static int |
ERROR_TRANSPORT_ABORTED
The transport for some reason was not in a good state and
aborted the entire backup request.
|
static int |
ERROR_TRANSPORT_PACKAGE_REJECTED
Returned when the transport was unable to process the
backup request for a given package, for example if the
transport hit a transient network failure.
|
static int |
ERROR_TRANSPORT_QUOTA_EXCEEDED
Returned when the transport reject the attempt to backup because
backup data size exceeded current quota limit for this package.
|
static String |
EXTRA_BACKUP_SERVICES_AVAILABLE
Intent extra when any subsidiary backup-related UI is launched from Settings: does
device policy or configuration permit backup operations to run at all?
|
static int |
SUCCESS
Indicates that backup succeeded.
|
Constructor and Description |
---|
BackupManager(Context context)
Constructs a BackupManager object through which the application can
communicate with the Android backup system.
|
Modifier and Type | Method and Description |
---|---|
void |
backupNow()
Schedule an immediate backup attempt for all pending key/value updates.
|
RestoreSession |
beginRestoreSession()
Begin the process of restoring data from backup.
|
void |
dataChanged()
Notifies the Android backup system that your application wishes to back up
new changes to its data.
|
static void |
dataChanged(String packageName)
Convenience method for callers who need to indicate that some other package
needs a backup pass.
|
long |
getAvailableRestoreToken(String packageName)
Ask the framework which dataset, if any, the given package's data would be
restored from if we were to install it right now.
|
String |
getCurrentTransport()
Identify the currently selected transport.
|
boolean |
isAppEligibleForBackup(String packageName)
Ask the framework whether this app is eligible for backup.
|
boolean |
isBackupEnabled()
Report whether the backup mechanism is currently enabled.
|
String[] |
listAllTransports()
Request a list of all available backup transports' names.
|
int |
requestBackup(String[] packages,
BackupObserver observer)
Request an immediate backup, providing an observer to which results of the backup operation
will be published.
|
int |
requestRestore(RestoreObserver observer)
Restore the calling application from backup.
|
String |
selectBackupTransport(String transport)
Specify the current backup transport.
|
void |
setAutoRestore(boolean isEnabled)
Enable/disable data restore at application install time.
|
void |
setBackupEnabled(boolean isEnabled)
Enable/disable the backup service entirely.
|
public static final int SUCCESS
public static final int ERROR_BACKUP_NOT_ALLOWED
public static final int ERROR_PACKAGE_NOT_FOUND
public static final int ERROR_TRANSPORT_ABORTED
public static final int ERROR_TRANSPORT_PACKAGE_REJECTED
requestBackup(String[], BackupObserver)
will still be attempted.public static final int ERROR_TRANSPORT_QUOTA_EXCEEDED
public static final int ERROR_AGENT_FAILURE
BackupAgent
for the requested package failed for some reason
and didn't provide appropriate backup data.public static final String EXTRA_BACKUP_SERVICES_AVAILABLE
public BackupManager(Context context)
context
- The Context
that was provided when
one of your application's Activities
was created.public void dataChanged()
BackupAgent
subclass will be scheduled when you
call this method.public static void dataChanged(String packageName)
This method requires that the application hold the "android.permission.BACKUP" permission if the package named in the argument does not run under the same uid as the caller.
packageName
- The package name identifying the application to back up.public int requestRestore(RestoreObserver observer)
If this method returns zero (meaning success), the OS will attempt to retrieve
a backed-up dataset from the remote transport, instantiate the application's
backup agent, and pass the dataset to the agent's
onRestore()
method.
observer
- The RestoreObserver
to receive callbacks during the restore
operation. This must not be null.public RestoreSession beginRestoreSession()
RestoreSession
class for documentation on that process.public void setBackupEnabled(boolean isEnabled)
Callers must hold the android.permission.BACKUP permission to use this method.
public boolean isBackupEnabled()
Callers must hold the android.permission.BACKUP permission to use this method.
public void setAutoRestore(boolean isEnabled)
Callers must hold the android.permission.BACKUP permission to use this method.
public String getCurrentTransport()
null
.public String[] listAllTransports()
public String selectBackupTransport(String transport)
transport
- The name of the transport to select. This should be one
of the names returned by listAllTransports()
.public void backupNow()
Callers must hold the android.permission.BACKUP permission to use this method.
public long getAvailableRestoreToken(String packageName)
Callers must hold the android.permission.BACKUP permission to use this method.
packageName
- The name of the package whose most-suitable dataset we
wish to look uppublic boolean isAppEligibleForBackup(String packageName)
Callers must hold the android.permission.BACKUP permission to use this method.
packageName
- The name of the package.public int requestBackup(String[] packages, BackupObserver observer)
If this method returns SUCCESS
, the OS will attempt to backup all
provided packages using the remote transport.
packages
- List of package names to backup.observer
- The BackupObserver
to receive callbacks during the backup
operation. Could be null
.SUCCESS
on success; nonzero on error.IllegalArgumentException
- on null or empty packages
param.