Defines the calling interface that BackupAgentHelper uses
when dispatching backup and restore operations to the installed helpers.
Applications can define and install their own helpers as well as using those
provided as part of the Android framework.

Although multiple helper objects may be installed simultaneously, each helper
is responsible only for handling its own data, and will not see entities
created by other components within the backup system. Invocations of multiple
helpers are performed sequentially by the BackupAgentHelper, with each
helper given a chance to access its own saved state from within the state record
produced during the previous backup operation.

Public methods

performBackup

Based on oldState, determine what application content
needs to be backed up, write it to data, and fill in
newState with the complete state as it exists now.

Implementing this method is much like implementing
onBackup() — the method parameters are the same. When this method is invoked the
oldState descriptor points to the beginning of the state data
written during this helper's previous backup operation, and the newState
descriptor points to the file location at which the helper should write its
new state after performing the backup operation.

Note: The helper should not close or seek either the oldState or
the newState file descriptors. It is essential that when reading the helper's
saved state from the oldState file, no extra content is consumed beyond
what was stored by this helper. If more old state data is read, even accidentally,
it will make it impossible for additional helpers that may be invoked after this one
to properly reconstruct their prior state.

Parameters

oldState

ParcelFileDescriptor: An open, read-only ParcelFileDescriptor pointing to the
last backup state provided by the application. May be
null, in which case no prior state is being
provided and the application should perform a full backup.

data

BackupDataOutput: An open, read/write BackupDataOutput
pointing to the backup data destination.
Typically the application will use backup helper classes to
write to this file.

newState

ParcelFileDescriptor: An open, read/write ParcelFileDescriptor pointing to an
empty file. The application should record the final backup
state here after writing the requested data to the data
output stream.

writeNewStateDescription

Called by BackupAgentHelper
after a restore operation to write the backup state file corresponding to
the data as processed by the helper. The data written here will be
available to the helper during the next call to its
performBackup() method.

This method will be called even if the handler's
restoreEntity() method was never invoked during
the restore operation.

Note: The helper should not close or seek the newState
file descriptor.