public class LocalTransport extends BackupTransport
AGENT_ERROR, AGENT_UNKNOWN, FLAG_USER_INITIATED, NO_MORE_DATA, TRANSPORT_ERROR, TRANSPORT_NOT_INITIALIZED, TRANSPORT_OK, TRANSPORT_PACKAGE_REJECTED, TRANSPORT_QUOTA_EXCEEDED
Constructor and Description |
---|
LocalTransport(Context context) |
Modifier and Type | Method and Description |
---|---|
int |
abortFullRestore()
If the OS encounters an error while processing
RestoreDescription.TYPE_FULL_STREAM
data for restore, it will invoke this method to tell the transport that it should
abandon the data download for the current package. |
void |
cancelFullBackup()
Tells the transport to cancel the currently-ongoing full backup operation.
|
int |
checkFullBackupSize(long size)
Called after
BackupTransport.performFullBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int) to make sure that the transport is willing to
handle a full-data backup operation of the specified size on the current package. |
int |
clearBackupData(PackageInfo packageInfo)
Erase the given application's data from the backup destination.
|
Intent |
configurationIntent()
Ask the transport for an Intent that can be used to launch any internal
configuration Activity that it wishes to present.
|
String |
currentDestinationString()
On demand, supply a one-line string that can be shown to the user that
describes the current backend destination.
|
Intent |
dataManagementIntent()
Ask the transport for an Intent that can be used to launch a more detailed
secondary data management activity.
|
String |
dataManagementLabel()
On demand, supply a short string that can be shown to the user as the label
on an overflow menu item used to invoked the data management UI.
|
int |
finishBackup()
Finish sending application data to the backup destination.
|
void |
finishRestore()
End a restore session (aborting any in-process data transfer as necessary),
freeing any resources and connections used during the restore process.
|
RestoreSet[] |
getAvailableRestoreSets()
Get the set of all backups currently available over this transport.
|
long |
getBackupQuota(String packageName,
boolean isFullBackup)
Ask the transport about current quota for backup size of the package.
|
long |
getCurrentRestoreSet()
Get the identifying token of the backup set currently being stored from
this device.
|
int |
getNextFullRestoreDataChunk(ParcelFileDescriptor socket)
Ask the transport to provide data for the "current" package being restored.
|
int |
getRestoreData(ParcelFileDescriptor outFd)
Get the data for the application returned by
BackupTransport.nextRestorePackage() , if that
method reported RestoreDescription.TYPE_KEY_VALUE as its delivery type. |
int |
initializeDevice()
Initialize the server side storage for this device, erasing all stored data.
|
String |
name()
Ask the transport for the name under which it should be registered.
|
RestoreDescription |
nextRestorePackage()
Get the package name of the next application with data in the backup store, plus
a description of the structure of the restored archive: either TYPE_KEY_VALUE for
an original-API key/value dataset, or TYPE_FULL_STREAM for a tarball-type archive stream.
|
int |
performBackup(PackageInfo packageInfo,
ParcelFileDescriptor data)
Legacy version of
BackupTransport.performBackup(PackageInfo, ParcelFileDescriptor, int) that
doesn't use flags parameter. |
int |
performFullBackup(PackageInfo targetPackage,
ParcelFileDescriptor socket)
Legacy version of
BackupTransport.performFullBackup(PackageInfo, ParcelFileDescriptor, int) that
doesn't use flags parameter. |
long |
requestBackupTime()
Verify that this is a suitable time for a key/value backup pass.
|
long |
requestFullBackupTime()
Verify that this is a suitable time for a full-data backup pass.
|
int |
sendBackupData(int numBytes)
Tells the transport to read
numBytes bytes of data from the socket file
descriptor provided in the BackupTransport.performFullBackup(PackageInfo, ParcelFileDescriptor)
call, and deliver those bytes to the datastore. |
int |
startRestore(long token,
PackageInfo[] packages)
Start restoring application data from backup.
|
String |
transportDirName()
Ask the transport where, on local device storage, to keep backup state blobs.
|
getBinder, isAppEligibleForBackup, performBackup, performFullBackup
public LocalTransport(Context context)
public String name()
BackupTransport
name
in class BackupTransport
public Intent configurationIntent()
BackupTransport
If the transport does not supply any user-facing configuration UI, it should
return null
from this method.
configurationIntent
in class BackupTransport
null
if the transport does not offer any user-facing configuration UI.public String currentDestinationString()
BackupTransport
currentDestinationString
in class BackupTransport
public Intent dataManagementIntent()
BackupTransport
In the Settings UI, the configuration intent will typically be invoked when the user taps on the preferences item labeled with the current destination string, and the management intent will be placed in an overflow menu labelled with the management label string.
If the transport does not supply any user-facing data management
UI, then it should return null
from this method.
dataManagementIntent
in class BackupTransport
null
if the transport does not offer any user-facing data
management UI.public String dataManagementLabel()
BackupTransport
dataManagementLabel
in class BackupTransport
null
.public String transportDirName()
BackupTransport
transportDirName
in class BackupTransport
public long requestBackupTime()
BackupTransport
BackupTransport.performBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
/BackupTransport.finishBackup()
pair.
If this is not a suitable time for a backup, the transport should return a backoff delay, in milliseconds, after which the Backup Manager should try again.
requestBackupTime
in class BackupTransport
public int initializeDevice()
BackupTransport
BackupTransport.finishBackup()
will be called to ensure the request
is sent and received successfully.
If the transport returns anything other than TRANSPORT_OK from this method, the OS will halt the current initialize operation and schedule a retry in the near future. Even if the transport is in a state such that attempting to "initialize" the backend storage is meaningless -- for example, if there is no current live dataset at all, or there is no authenticated account under which to store the data remotely -- the transport should return TRANSPORT_OK here and treat the initializeDevice() / finishBackup() pair as a graceful no-op.
initializeDevice
in class BackupTransport
BackupTransport.TRANSPORT_OK
(OK so far) or
BackupTransport.TRANSPORT_ERROR
(to retry following network error
or other failure).public int performBackup(PackageInfo packageInfo, ParcelFileDescriptor data)
BackupTransport
BackupTransport.performBackup(PackageInfo, ParcelFileDescriptor, int)
that
doesn't use flags parameter.performBackup
in class BackupTransport
public int clearBackupData(PackageInfo packageInfo)
BackupTransport
finishBackup
must be called to ensure that the operation is recorded successfully.clearBackupData
in class BackupTransport
BackupTransport.performBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
.public int finishBackup()
BackupTransport
BackupTransport.performBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
, BackupTransport.performFullBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
, or clearBackupData
to ensure that all data is sent and the operation properly finalized. Only when this
method returns true can a backup be assumed to have succeeded.finishBackup
in class BackupTransport
BackupTransport.performBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
or BackupTransport.performFullBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
.public long requestFullBackupTime()
BackupTransport
BackupTransport.performFullBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
/BackupTransport.finishBackup()
pair.
If this is not a suitable time for a backup, the transport should return a backoff delay, in milliseconds, after which the Backup Manager should try again.
requestFullBackupTime
in class BackupTransport
BackupTransport.requestBackupTime()
public int checkFullBackupSize(long size)
BackupTransport
BackupTransport.performFullBackup(android.content.pm.PackageInfo, android.os.ParcelFileDescriptor, int)
to make sure that the transport is willing to
handle a full-data backup operation of the specified size on the current package.
If the transport returns anything other than TRANSPORT_OK, the package's backup
operation will be skipped (and invoked
with no data for that
package being passed to BackupTransport.sendBackupData(int)
.
The platform does no size-based rejection of full backup attempts on
its own: it is always the responsibility of the transport to implement its own policy.
In particular, even if the preflighted payload size is zero, the platform will still call
this method and will proceed to back up an archive metadata header with no file content
if this method returns TRANSPORT_OK. To avoid storing such payloads the transport
must recognize this case and return TRANSPORT_PACKAGE_REJECTED.
Added in Build.VERSION_CODES.M
.
checkFullBackupSize
in class BackupTransport
size
- The estimated size of the full-data payload for this app. This includes
manifest and archive format overhead, but is not guaranteed to be precise.public int performFullBackup(PackageInfo targetPackage, ParcelFileDescriptor socket)
BackupTransport
BackupTransport.performFullBackup(PackageInfo, ParcelFileDescriptor, int)
that
doesn't use flags parameter.performFullBackup
in class BackupTransport
public int sendBackupData(int numBytes)
BackupTransport
numBytes
bytes of data from the socket file
descriptor provided in the BackupTransport.performFullBackup(PackageInfo, ParcelFileDescriptor)
call, and deliver those bytes to the datastore.sendBackupData
in class BackupTransport
numBytes
- The number of bytes of tarball data available to be read from the
socket.public void cancelFullBackup()
BackupTransport
#performFullBackup()
and BackupTransport.finishBackup()
if the OS needs to abort the backup operation for any reason, such as a crash in
the application undergoing backup.
When it receives this call, the transport should discard any partial archive that it has stored so far. If possible it should also roll back to the previous known-good archive in its datastore.
If the transport receives this callback, it will not receive a
call to BackupTransport.finishBackup()
. It needs to tear down any ongoing backup state
here.
cancelFullBackup
in class BackupTransport
public RestoreSet[] getAvailableRestoreSets()
BackupTransport
getAvailableRestoreSets
in class BackupTransport
public long getCurrentRestoreSet()
BackupTransport
getCurrentRestoreSet
in class BackupTransport
BackupTransport.startRestore(long, android.content.pm.PackageInfo[])
, or 0 if there
is no backup set available corresponding to the current device state.public int startRestore(long token, PackageInfo[] packages)
BackupTransport
BackupTransport.nextRestorePackage()
and #nextRestoreData
to walk through the actual application data.startRestore
in class BackupTransport
token
- A backup token as returned by BackupTransport.getAvailableRestoreSets()
or BackupTransport.getCurrentRestoreSet()
.packages
- List of applications to restore (if data is available).
Application data will be restored in the order given.BackupTransport.TRANSPORT_OK
(OK so far, call
BackupTransport.nextRestorePackage()
) or BackupTransport.TRANSPORT_ERROR
(an error occurred, the restore should be aborted and rescheduled).public RestoreDescription nextRestorePackage()
BackupTransport
If the package name in the returned RestoreDescription object is the singleton
RestoreDescription.NO_MORE_PACKAGES
, it indicates that no further data is available
in the current restore session: all packages described in startRestore() have been
processed.
If this method returns null
, it means that a transport-level error has
occurred and the entire restore operation should be abandoned.
The OS may call BackupTransport.nextRestorePackage()
multiple times
before calling either getRestoreData()
or getNextFullRestoreDataChunk()
.
It does this when it has determined that it needs to skip restore of one or more
packages. The transport should not actually transfer any restore data for
the given package in response to BackupTransport.nextRestorePackage()
, but rather wait
for an explicit request before doing so.
nextRestorePackage
in class BackupTransport
BackupTransport.startRestore(long, android.content.pm.PackageInfo[])
plus an indicator of the data type of that
restore data; or RestoreDescription.NO_MORE_PACKAGES
to indicate that
no more packages can be restored in this session; or null
to indicate
a transport-level error.public int getRestoreData(ParcelFileDescriptor outFd)
BackupTransport
BackupTransport.nextRestorePackage()
, if that
method reported RestoreDescription.TYPE_KEY_VALUE
as its delivery type.
If the package has only TYPE_FULL_STREAM data, then this method will return an
error.getRestoreData
in class BackupTransport
BackupTransport.startRestore(long, android.content.pm.PackageInfo[])
.public void finishRestore()
BackupTransport
finishRestore
in class BackupTransport
public int getNextFullRestoreDataChunk(ParcelFileDescriptor socket)
After this method returns zero, the system will then call
#getNextFullRestorePackage()
to begin the restore process for the next
application, and the sequence begins again.
getNextFullRestoreDataChunk
in class BackupTransport
socket
- The file descriptor that the transport will use for delivering the
streamed archive.BackupTransport.TRANSPORT_ERROR
,
indicating a fatal error condition that precludes further restore operations
on the current dataset.public int abortFullRestore()
RestoreDescription.TYPE_FULL_STREAM
data for restore, it will invoke this method to tell the transport that it should
abandon the data download for the current package. The OS will then either call
nextRestorePackage()
again to move on to restoring the next package in the
set being iterated over, or will call finishRestore()
to shut down the restore
operation.abortFullRestore
in class BackupTransport
BackupTransport.TRANSPORT_OK
if the transport was successful in shutting down the
current stream cleanly, or BackupTransport.TRANSPORT_ERROR
to indicate a serious
transport-level failure. If the transport reports an error here, the entire restore
operation will immediately be finished with no further attempts to restore app data.public long getBackupQuota(String packageName, boolean isFullBackup)
BackupTransport
getBackupQuota
in class BackupTransport
packageName
- ID of package to provide the quota.isFullBackup
- If set, transport should return limit for full data backup, otherwise
for key-value backup.