android/android-9.0.0_r35 : android/app/backup/BackupManager.java

BackupManager
https://source.android.com/
/*
 * Copyright (C) 2009 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.app.backup;

import android.annotation.Nullable;
import android.annotation.RequiresPermission;
import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.os.Handler;
import android.os.Message;
import android.os.RemoteException;
import android.os.ServiceManager;
import android.os.UserHandle;
import android.util.Log;
import android.util.Pair;

The interface through which an application interacts with the Android backup service to
request backup and restore operations.
Applications instantiate it using the constructor and issue calls through that instance.
 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.

Developer Guides
For more information about using BackupManager, read the
Data Backup developer guide.
@attr ref android.R.styleable#AndroidManifestApplication_allowBackup
@attr ref android.R.styleable#AndroidManifestApplication_backupAgent
@attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore
@attr ref android.R.styleable#AndroidManifestApplication_restoreAnyVersion/**
 * The interface through which an application interacts with the Android backup service to
 * request backup and restore operations.
 * Applications instantiate it using the constructor and issue calls through that instance.
 * <p>
 * When an application has made changes to data which should be backed up, a
 * call to {@link #dataChanged()} will notify the backup service. The system
 * will then schedule a backup operation to occur in the near future. Repeated
 * calls to {@link #dataChanged()} have no further effect until the backup
 * operation actually occurs.
 * <p>
 * A backup or restore operation for your application begins when the system launches the
 * {@link android.app.backup.BackupAgent} subclass you've declared in your manifest. See the
 * documentation for {@link android.app.backup.BackupAgent} for a detailed description
 * of how the operation then proceeds.
 * <p>
 * Several attributes affecting the operation of the backup and restore mechanism
 * can be set on the <code>
 * <a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
 * tag in your application's AndroidManifest.xml file.
 *
 * <div class="special reference">
 * <h3>Developer Guides</h3>
 * <p>For more information about using BackupManager, read the
 * <a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a> developer guide.</p></div>
 *
 * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup
 * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent
 * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore
 * @attr ref android.R.styleable#AndroidManifestApplication_restoreAnyVersion
 */
public class BackupManager {
    private static final String TAG = "BackupManager";

    // BackupObserver status codes
    Indicates that backup succeeded.
@hide /**
     * Indicates that backup succeeded.
     *
     * @hide
     */
    @SystemApi
    public static final int SUCCESS = 0;

    Indicates that backup is either not enabled at all or
backup for the package was rejected by backup service
or backup transport,
@hide /**
     * Indicates that backup is either not enabled at all or
     * backup for the package was rejected by backup service
     * or backup transport,
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_BACKUP_NOT_ALLOWED = -2001;

    The requested app is not installed on the device.
@hide /**
     * The requested app is not installed on the device.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_PACKAGE_NOT_FOUND = -2002;

    The backup operation was cancelled.
@hide /**
     * The backup operation was cancelled.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_BACKUP_CANCELLED = -2003;

    The transport for some reason was not in a good state and
aborted the entire backup request. This is a transient
failure and should not be retried immediately.
@hide /**
     * The transport for some reason was not in a good state and
     * aborted the entire backup request. This is a transient
     * failure and should not be retried immediately.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_TRANSPORT_ABORTED = BackupTransport.TRANSPORT_ERROR;

    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. The remaining packages provided to requestBackup(String[], BackupObserver) will still be attempted. 
@hide /**
     * 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. The remaining
     * packages provided to {@link #requestBackup(String[], BackupObserver)}
     * will still be attempted.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_TRANSPORT_PACKAGE_REJECTED =
            BackupTransport.TRANSPORT_PACKAGE_REJECTED;

    Returned when the transport reject the attempt to backup because
backup data size exceeded current quota limit for this package.
@hide /**
     * Returned when the transport reject the attempt to backup because
     * backup data size exceeded current quota limit for this package.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_TRANSPORT_QUOTA_EXCEEDED =
            BackupTransport.TRANSPORT_QUOTA_EXCEEDED;

    The BackupAgent for the requested package failed for some reason and didn't provide appropriate backup data. 
@hide /**
     * The {@link BackupAgent} for the requested package failed for some reason
     * and didn't provide appropriate backup data.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_AGENT_FAILURE = BackupTransport.AGENT_ERROR;

    Intent extra when any subsidiary backup-related UI is launched from Settings:  does
device policy or configuration permit backup operations to run at all?
@hide /**
     * Intent extra when any subsidiary backup-related UI is launched from Settings:  does
     * device policy or configuration permit backup operations to run at all?
     *
     * @hide
     */
    public static final String EXTRA_BACKUP_SERVICES_AVAILABLE = "backup_services_available";

    If this flag is passed to requestBackup(String[], BackupObserver, BackupManagerMonitor), BackupManager will pass a blank old state to BackupAgents of requested packages. 
@hide /**
     * If this flag is passed to {@link #requestBackup(String[], BackupObserver, int)},
     * BackupManager will pass a blank old state to BackupAgents of requested packages.
     *
     * @hide
     */
    @SystemApi
    public static final int FLAG_NON_INCREMENTAL_BACKUP = 1;

    Use with requestBackup to force backup of package meta data. Typically you do not need to explicitly request this be backed up as it is handled internally by the BackupManager. If you are requesting backups with FLAG_NON_INCREMENTAL, this package won't automatically be backed up and you have to explicitly request for its backup. 
@hide /**
     * Use with {@link #requestBackup} to force backup of
     * package meta data. Typically you do not need to explicitly request this be backed up as it is
     * handled internally by the BackupManager. If you are requesting backups with
     * FLAG_NON_INCREMENTAL, this package won't automatically be backed up and you have to
     * explicitly request for its backup.
     *
     * @hide
     */
    @SystemApi
    public static final String PACKAGE_MANAGER_SENTINEL = "@pm@";


    This error code is passed to SelectBackupTransportCallback.onFailure(int) if the requested transport is unavailable. 
@hide /**
     * This error code is passed to {@link SelectBackupTransportCallback#onFailure(int)}
     * if the requested transport is unavailable.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_TRANSPORT_UNAVAILABLE = -1;

    This error code is passed to SelectBackupTransportCallback.onFailure(int) if the requested transport is not a valid BackupTransport. 
@hide /**
     * This error code is passed to {@link SelectBackupTransportCallback#onFailure(int)} if the
     * requested transport is not a valid BackupTransport.
     *
     * @hide
     */
    @SystemApi
    public static final int ERROR_TRANSPORT_INVALID = -2;

    private Context mContext;
    private static IBackupManager sService;

    private static void checkServiceBinder() {
        if (sService == null) {
            sService = IBackupManager.Stub.asInterface(
                    ServiceManager.getService(Context.BACKUP_SERVICE));
        }
    }

    Constructs a BackupManager object through which the application can
communicate with the Android backup system.
Params: context – The Context that was provided when one of your application's Activities was created./**
     * Constructs a BackupManager object through which the application can
     * communicate with the Android backup system.
     *
     * @param context The {@link android.content.Context} that was provided when
     *                one of your application's {@link android.app.Activity Activities}
     *                was created.
     */
    public BackupManager(Context context) {
        mContext = context;
    }

    Notifies the Android backup system that your application wishes to back up new changes to its data. A backup operation using your application's BackupAgent subclass will be scheduled when you call this method. /**
     * Notifies the Android backup system that your application wishes to back up
     * new changes to its data.  A backup operation using your application's
     * {@link android.app.backup.BackupAgent} subclass will be scheduled when you
     * call this method.
     */
    public void dataChanged() {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.dataChanged(mContext.getPackageName());
            } catch (RemoteException e) {
                Log.d(TAG, "dataChanged() couldn't connect");
            }
        }
    }

    Convenience method for callers who need to indicate that some other package
needs a backup pass.  This can be useful in the case of groups of packages
that share a uid.

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.
Params: packageName – The package name identifying the application to back up./**
     * Convenience method for callers who need to indicate that some other package
     * needs a backup pass.  This can be useful in the case of groups of packages
     * that share a uid.
     * <p>
     * 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.
     *
     * @param packageName The package name identifying the application to back up.
     */
    public static void dataChanged(String packageName) {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.dataChanged(packageName);
            } catch (RemoteException e) {
                Log.e(TAG, "dataChanged(pkg) couldn't connect");
            }
        }
    }

    Params: observer – The RestoreObserver to receive callbacks during the restore operation. This must not be null.
Deprecated: Applications shouldn't request a restore operation using this method. In Android
P and later, this method is a no-op.
Restore the calling application from backup. The data will be restored from the
current backup dataset if the application has stored data there, or from
the dataset used during the last full device setup operation if the current
backup dataset has no matching data.  If no backup data exists for this application
in either source, a non-zero value is returned.
If this method returns zero (meaning success), the OS attempts 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. 
Unlike other restore operations, this method doesn't terminate the application after the restore. The application continues running to receive the RestoreObserver callbacks on the observer argument. Full backups use an Application base class while key-value backups use the application subclass declared in the AndroidManifest.xml <application> tag.
Returns: Zero on success; nonzero on error./**
     * @deprecated Applications shouldn't request a restore operation using this method. In Android
     * P and later, this method is a no-op.
     *
     * <p>Restore the calling application from backup. The data will be restored from the
     * current backup dataset if the application has stored data there, or from
     * the dataset used during the last full device setup operation if the current
     * backup dataset has no matching data.  If no backup data exists for this application
     * in either source, a non-zero value is returned.
     *
     * <p>If this method returns zero (meaning success), the OS attempts to retrieve a backed-up
     * dataset from the remote transport, instantiate the application's backup agent, and pass the
     * dataset to the agent's
     * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
     * method.
     *
     * <p class="caution">Unlike other restore operations, this method doesn't terminate the
     * application after the restore. The application continues running to receive the
     * {@link RestoreObserver} callbacks on the {@code observer} argument. Full backups use an
     * {@link android.app.Application Application} base class while key-value backups use the
     * application subclass declared in the AndroidManifest.xml {@code <application>} tag.
     *
     * @param observer The {@link RestoreObserver} to receive callbacks during the restore
     * operation. This must not be null.
     *
     * @return Zero on success; nonzero on error.
     */
    @Deprecated
    public int requestRestore(RestoreObserver observer) {
        return requestRestore(observer, null);
    }

    // system APIs start here

    Params: observer – The RestoreObserver to receive callbacks during the restore operation. This must not be null.
monitor – the BackupManagerMonitor to receive callbacks during the restore operation.
Deprecated: Since Android P app can no longer request restoring of its backup.
Restore the calling application from backup.  The data will be restored from the
current backup dataset if the application has stored data there, or from
the dataset used during the last full device setup operation if the current
backup dataset has no matching data.  If no backup data exists for this application
in either source, a nonzero value will be returned.
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.
Returns: Zero on success; nonzero on error.
@hide /**
     * @deprecated Since Android P app can no longer request restoring of its backup.
     *
     * <p>Restore the calling application from backup.  The data will be restored from the
     * current backup dataset if the application has stored data there, or from
     * the dataset used during the last full device setup operation if the current
     * backup dataset has no matching data.  If no backup data exists for this application
     * in either source, a nonzero value will be returned.
     *
     * <p>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
     * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
     * method.
     *
     * @param observer The {@link RestoreObserver} to receive callbacks during the restore
     * operation. This must not be null.
     *
     * @param monitor the {@link BackupManagerMonitor} to receive callbacks during the restore
     * operation.
     *
     * @return Zero on success; nonzero on error.
     *
     * @hide
     */
    @Deprecated
    @SystemApi
    public int requestRestore(RestoreObserver observer, BackupManagerMonitor monitor) {
        Log.w(TAG, "requestRestore(): Since Android P app can no longer request restoring"
                + " of its backup.");
        return -1;
    }

    Begin the process of restoring data from backup. See the RestoreSession class for documentation on that process. 
@hide /**
     * Begin the process of restoring data from backup.  See the
     * {@link android.app.backup.RestoreSession} class for documentation on that process.
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public RestoreSession beginRestoreSession() {
        RestoreSession session = null;
        checkServiceBinder();
        if (sService != null) {
            try {
                // All packages, current transport
                IRestoreSession binder = sService.beginRestoreSession(null, null);
                if (binder != null) {
                    session = new RestoreSession(mContext, binder);
                }
            } catch (RemoteException e) {
                Log.e(TAG, "beginRestoreSession() couldn't connect");
            }
        }
        return session;
    }

    Enable/disable the backup service entirely.  When disabled, no backup
or restore operations will take place.  Data-changed notifications will
still be observed and collected, however, so that changes made while the
mechanism was disabled will still be backed up properly if it is enabled
at some point in the future.
@hide /**
     * Enable/disable the backup service entirely.  When disabled, no backup
     * or restore operations will take place.  Data-changed notifications will
     * still be observed and collected, however, so that changes made while the
     * mechanism was disabled will still be backed up properly if it is enabled
     * at some point in the future.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void setBackupEnabled(boolean isEnabled) {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.setBackupEnabled(isEnabled);
            } catch (RemoteException e) {
                Log.e(TAG, "setBackupEnabled() couldn't connect");
            }
        }
    }

    Report whether the backup mechanism is currently enabled.
@hide /**
     * Report whether the backup mechanism is currently enabled.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public boolean isBackupEnabled() {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.isBackupEnabled();
            } catch (RemoteException e) {
                Log.e(TAG, "isBackupEnabled() couldn't connect");
            }
        }
        return false;
    }

    Report whether the backup mechanism is currently active.
When it is inactive, the device will not perform any backup operations, nor will it
deliver data for restore, although clients can still safely call BackupManager methods.
@hide /**
     * Report whether the backup mechanism is currently active.
     * When it is inactive, the device will not perform any backup operations, nor will it
     * deliver data for restore, although clients can still safely call BackupManager methods.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public boolean isBackupServiceActive(UserHandle user) {
        mContext.enforceCallingOrSelfPermission(android.Manifest.permission.BACKUP,
                "isBackupServiceActive");
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.isBackupServiceActive(user.getIdentifier());
            } catch (RemoteException e) {
                Log.e(TAG, "isBackupEnabled() couldn't connect");
            }
        }
        return false;
    }

    Enable/disable data restore at application install time.  When enabled, app
installation will include an attempt to fetch the app's historical data from
the archival restore dataset (if any).  When disabled, no such attempt will
be made.
@hide /**
     * Enable/disable data restore at application install time.  When enabled, app
     * installation will include an attempt to fetch the app's historical data from
     * the archival restore dataset (if any).  When disabled, no such attempt will
     * be made.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void setAutoRestore(boolean isEnabled) {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.setAutoRestore(isEnabled);
            } catch (RemoteException e) {
                Log.e(TAG, "setAutoRestore() couldn't connect");
            }
        }
    }

    Identify the currently selected transport.
Returns: The name of the currently active backup transport. In case of failure or if no transport is currently active, this method returns null.
@hide /**
     * Identify the currently selected transport.
     * @return The name of the currently active backup transport.  In case of
     *   failure or if no transport is currently active, this method returns {@code null}.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public String getCurrentTransport() {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.getCurrentTransport();
            } catch (RemoteException e) {
                Log.e(TAG, "getCurrentTransport() couldn't connect");
            }
        }
        return null;
    }

    Request a list of all available backup transports' names.
@hide /**
     * Request a list of all available backup transports' names.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public String[] listAllTransports() {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.listAllTransports();
            } catch (RemoteException e) {
                Log.e(TAG, "listAllTransports() couldn't connect");
            }
        }
        return null;
    }

    Update the attributes of the transport identified by transportComponent. If the specified transport has not been bound at least once (for registration), this call will be ignored. Only the host process of the transport can change its description, otherwise a SecurityException will be thrown. 
Params: transportComponent – The identity of the transport being described.
name – A String with the new name for the transport. This is NOT for identification. MUST NOT be null.
configurationIntent – An Intent that can be passed to Context.startActivity in order to launch the transport's configuration UI. It may be null if the transport does not offer any user-facing configuration UI.
currentDestinationString – A String describing the destination to which the transport is currently sending data. MUST NOT be null.
dataManagementIntent – An Intent that can be passed to Context.startActivity in order to launch the transport's data-management UI. It may be null if the transport does not offer any user-facing data management UI.
dataManagementLabel – A String to be used as the label for the transport's data management affordance. This MUST be null when dataManagementIntent is null and MUST NOT be null when dataManagementIntent is not null.
Throws: SecurityException – If the UID of the calling process differs from the package UID of transportComponent or if the caller does NOT have BACKUP permission.
@hide /**
     * Update the attributes of the transport identified by {@code transportComponent}. If the
     * specified transport has not been bound at least once (for registration), this call will be
     * ignored. Only the host process of the transport can change its description, otherwise a
     * {@link SecurityException} will be thrown.
     *
     * @param transportComponent The identity of the transport being described.
     * @param name A {@link String} with the new name for the transport. This is NOT for
     *     identification. MUST NOT be {@code null}.
     * @param configurationIntent An {@link Intent} that can be passed to
     *     {@link Context#startActivity} in order to launch the transport's configuration UI. It may
     *     be {@code null} if the transport does not offer any user-facing configuration UI.
     * @param currentDestinationString A {@link String} describing the destination to which the
     *     transport is currently sending data. MUST NOT be {@code null}.
     * @param dataManagementIntent An {@link Intent} that can be passed to
     *     {@link Context#startActivity} in order to launch the transport's data-management UI. It
     *     may be {@code null} if the transport does not offer any user-facing data
     *     management UI.
     * @param dataManagementLabel A {@link String} to be used as the label for the transport's data
     *     management affordance. This MUST be {@code null} when dataManagementIntent is
     *     {@code null} and MUST NOT be {@code null} when dataManagementIntent is not {@code null}.
     * @throws SecurityException If the UID of the calling process differs from the package UID of
     *     {@code transportComponent} or if the caller does NOT have BACKUP permission.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void updateTransportAttributes(
            ComponentName transportComponent,
            String name,
            @Nullable Intent configurationIntent,
            String currentDestinationString,
            @Nullable Intent dataManagementIntent,
            @Nullable String dataManagementLabel) {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.updateTransportAttributes(
                        transportComponent,
                        name,
                        configurationIntent,
                        currentDestinationString,
                        dataManagementIntent,
                        dataManagementLabel);
            } catch (RemoteException e) {
                Log.e(TAG, "describeTransport() couldn't connect");
            }
        }
    }

    Specify the current backup transport.
Params: transport – The name of the transport to select. This should be one of the names returned by listAllTransports(). This is the String returned by BackupTransport.name() for the particular transport.
Returns: The name of the previously selected transport.  If the given transport
  name is not one of the currently available transports, no change is made to
  the current transport setting and the method returns null.
@hide /**
     * Specify the current backup transport.
     *
     * @param transport The name of the transport to select.  This should be one
     *   of the names returned by {@link #listAllTransports()}. This is the String returned by
     *   {@link BackupTransport#name()} for the particular transport.
     * @return The name of the previously selected transport.  If the given transport
     *   name is not one of the currently available transports, no change is made to
     *   the current transport setting and the method returns null.
     *
     * @hide
     */
    @Deprecated
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public String selectBackupTransport(String transport) {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.selectBackupTransport(transport);
            } catch (RemoteException e) {
                Log.e(TAG, "selectBackupTransport() couldn't connect");
            }
        }
        return null;
    }

    Specify the current backup transport and get notified when the transport is ready to be used.
This method is async because BackupManager might need to bind to the specified transport
which is in a separate process.
Params: transport – ComponentName of the service hosting the transport. This is different from the transport's name that is returned by BackupTransport.name().
listener – A listener object to get a callback on the transport being selected.
@hide /**
     * Specify the current backup transport and get notified when the transport is ready to be used.
     * This method is async because BackupManager might need to bind to the specified transport
     * which is in a separate process.
     *
     * @param transport ComponentName of the service hosting the transport. This is different from
     *                  the transport's name that is returned by {@link BackupTransport#name()}.
     * @param listener A listener object to get a callback on the transport being selected.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void selectBackupTransport(ComponentName transport,
            SelectBackupTransportCallback listener) {
        checkServiceBinder();
        if (sService != null) {
            try {
                SelectTransportListenerWrapper wrapper = listener == null ?
                        null : new SelectTransportListenerWrapper(mContext, listener);
                sService.selectBackupTransportAsync(transport, wrapper);
            } catch (RemoteException e) {
                Log.e(TAG, "selectBackupTransportAsync() couldn't connect");
            }
        }
    }

    Schedule an immediate backup attempt for all pending key/value updates.  This
is primarily intended for transports to use when they detect a suitable
opportunity for doing a backup pass.  If there are no pending updates to
be sent, no action will be taken.  Even if some updates are pending, the
transport will still be asked to confirm via the usual requestBackupTime()
method.
@hide /**
     * Schedule an immediate backup attempt for all pending key/value updates.  This
     * is primarily intended for transports to use when they detect a suitable
     * opportunity for doing a backup pass.  If there are no pending updates to
     * be sent, no action will be taken.  Even if some updates are pending, the
     * transport will still be asked to confirm via the usual requestBackupTime()
     * method.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void backupNow() {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.backupNow();
            } catch (RemoteException e) {
                Log.e(TAG, "backupNow() couldn't connect");
            }
        }
    }

    Ask the framework which dataset, if any, the given package's data would be
restored from if we were to install it right now.
Params: packageName – The name of the package whose most-suitable dataset we
    wish to look up
Returns: The dataset token from which a restore should be attempted, or zero if
    no suitable data is available.
@hide /**
     * Ask the framework which dataset, if any, the given package's data would be
     * restored from if we were to install it right now.
     *
     * @param packageName The name of the package whose most-suitable dataset we
     *     wish to look up
     * @return The dataset token from which a restore should be attempted, or zero if
     *     no suitable data is available.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public long getAvailableRestoreToken(String packageName) {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.getAvailableRestoreToken(packageName);
            } catch (RemoteException e) {
                Log.e(TAG, "getAvailableRestoreToken() couldn't connect");
            }
        }
        return 0;
    }

    Ask the framework whether this app is eligible for backup.
Params: packageName – The name of the package.
Returns: Whether this app is eligible for backup.
@hide /**
     * Ask the framework whether this app is eligible for backup.
     *
     * @param packageName The name of the package.
     * @return Whether this app is eligible for backup.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public boolean isAppEligibleForBackup(String packageName) {
        checkServiceBinder();
        if (sService != null) {
            try {
                return sService.isAppEligibleForBackup(packageName);
            } catch (RemoteException e) {
                Log.e(TAG, "isAppEligibleForBackup(pkg) couldn't connect");
            }
        }
        return false;
    }

    Request an immediate backup, providing an observer to which results of the backup operation
will be published. The Android backup system will decide for each package whether it will
be full app data backup or key/value-pair-based backup.
If this method returns SUCCESS, the OS will attempt to backup all provided packages using the remote transport. 
Params: packages – List of package names to backup.
observer – The BackupObserver to receive callbacks during the backup operation. Could be null.
Throws: IllegalArgumentException – on null or empty packages param.
Returns: SUCCESS on success; nonzero on error.
@hide /**
     * Request an immediate backup, providing an observer to which results of the backup operation
     * will be published. The Android backup system will decide for each package whether it will
     * be full app data backup or key/value-pair-based backup.
     *
     * <p>If this method returns {@link BackupManager#SUCCESS}, the OS will attempt to backup all
     * provided packages using the remote transport.
     *
     * @param packages List of package names to backup.
     * @param observer The {@link BackupObserver} to receive callbacks during the backup
     * operation. Could be {@code null}.
     * @return {@link BackupManager#SUCCESS} on success; nonzero on error.
     * @exception  IllegalArgumentException on null or empty {@code packages} param.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public int requestBackup(String[] packages, BackupObserver observer) {
        return requestBackup(packages, observer, null, 0);
    }

    Request an immediate backup, providing an observer to which results of the backup operation
will be published. The Android backup system will decide for each package whether it will
be full app data backup or key/value-pair-based backup.
If this method returns SUCCESS, the OS will attempt to backup all provided packages using the remote transport. 
Params: packages – List of package names to backup.
observer – The BackupObserver to receive callbacks during the backup operation. Could be null.
monitor –  The BackupManagerMonitorWrapper to receive callbacks of important events during the backup operation. Could be null.
flags –  FLAG_NON_INCREMENTAL_BACKUP.
Throws: IllegalArgumentException – on null or empty packages param.
Returns: SUCCESS on success; nonzero on error.
@hide /**
     * Request an immediate backup, providing an observer to which results of the backup operation
     * will be published. The Android backup system will decide for each package whether it will
     * be full app data backup or key/value-pair-based backup.
     *
     * <p>If this method returns {@link BackupManager#SUCCESS}, the OS will attempt to backup all
     * provided packages using the remote transport.
     *
     * @param packages List of package names to backup.
     * @param observer The {@link BackupObserver} to receive callbacks during the backup
     *                 operation. Could be {@code null}.
     * @param monitor  The {@link BackupManagerMonitorWrapper} to receive callbacks of important
     *                 events during the backup operation. Could be {@code null}.
     * @param flags    {@link #FLAG_NON_INCREMENTAL_BACKUP}.
     * @return {@link BackupManager#SUCCESS} on success; nonzero on error.
     * @throws IllegalArgumentException on null or empty {@code packages} param.
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public int requestBackup(String[] packages, BackupObserver observer,
            BackupManagerMonitor monitor, int flags) {
        checkServiceBinder();
        if (sService != null) {
            try {
                BackupObserverWrapper observerWrapper = observer == null
                        ? null
                        : new BackupObserverWrapper(mContext, observer);
                BackupManagerMonitorWrapper monitorWrapper = monitor == null
                        ? null
                        : new BackupManagerMonitorWrapper(monitor);
                return sService.requestBackup(packages, observerWrapper, monitorWrapper, flags);
            } catch (RemoteException e) {
                Log.e(TAG, "requestBackup() couldn't connect");
            }
        }
        return -1;
    }

    Cancel all running backups. After this call returns, no currently running backups will
interact with the selected transport.
@hide /**
     * Cancel all running backups. After this call returns, no currently running backups will
     * interact with the selected transport.
     *
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public void cancelBackups() {
        checkServiceBinder();
        if (sService != null) {
            try {
                sService.cancelBackups();
            } catch (RemoteException e) {
                Log.e(TAG, "cancelBackups() couldn't connect.");
            }
        }
    }

    Returns an Intent for the specified transport's configuration UI. This value is set by updateTransportAttributes(ComponentName, String, Intent, String, Intent, String). 
Params: transportName – The name of the registered transport.
@hide /**
     * Returns an {@link Intent} for the specified transport's configuration UI.
     * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String,
     * Intent, String)}.
     * @param transportName The name of the registered transport.
     * @hide
     */
    @SystemApi
    @TestApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public Intent getConfigurationIntent(String transportName) {
        if (sService != null) {
            try {
                return sService.getConfigurationIntent(transportName);
            } catch (RemoteException e) {
                Log.e(TAG, "getConfigurationIntent() couldn't connect");
            }
        }
        return null;
    }

    Returns a String describing where the specified transport is sending data. This value is set by updateTransportAttributes(ComponentName, String, Intent, String, Intent, String). 
Params: transportName – The name of the registered transport.
@hide /**
     * Returns a {@link String} describing where the specified transport is sending data.
     * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String,
     * Intent, String)}.
     * @param transportName The name of the registered transport.
     * @hide
     */
    @SystemApi
    @TestApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public String getDestinationString(String transportName) {
        if (sService != null) {
            try {
                return sService.getDestinationString(transportName);
            } catch (RemoteException e) {
                Log.e(TAG, "getDestinationString() couldn't connect");
            }
        }
        return null;
    }

    Returns an Intent for the specified transport's data management UI. This value is set by updateTransportAttributes(ComponentName, String, Intent, String, Intent, String). 
Params: transportName – The name of the registered transport.
@hide /**
     * Returns an {@link Intent} for the specified transport's data management UI.
     * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String,
     * Intent, String)}.
     * @param transportName The name of the registered transport.
     * @hide
     */
    @SystemApi
    @TestApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public Intent getDataManagementIntent(String transportName) {
        if (sService != null) {
            try {
                return sService.getDataManagementIntent(transportName);
            } catch (RemoteException e) {
                Log.e(TAG, "getDataManagementIntent() couldn't connect");
            }
        }
        return null;
    }

    Returns a String describing what the specified transport's data management intent is used for. This value is set by updateTransportAttributes(ComponentName, String, Intent, String, Intent, String). 
Params: transportName – The name of the registered transport.
@hide /**
     * Returns a {@link String} describing what the specified transport's data management intent is
     * used for.
     * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String,
     * Intent, String)}.
     *
     * @param transportName The name of the registered transport.
     * @hide
     */
    @SystemApi
    @TestApi
    @RequiresPermission(android.Manifest.permission.BACKUP)
    public String getDataManagementLabel(String transportName) {
        if (sService != null) {
            try {
                return sService.getDataManagementLabel(transportName);
            } catch (RemoteException e) {
                Log.e(TAG, "getDataManagementLabel() couldn't connect");
            }
        }
        return null;
    }

    /*
     * We wrap incoming binder calls with a private class implementation that
     * redirects them into main-thread actions.  This serializes the backup
     * progress callbacks nicely within the usual main-thread lifecycle pattern.
     */
    private class BackupObserverWrapper extends IBackupObserver.Stub {
        final Handler mHandler;
        final BackupObserver mObserver;

        static final int MSG_UPDATE = 1;
        static final int MSG_RESULT = 2;
        static final int MSG_FINISHED = 3;

        BackupObserverWrapper(Context context, BackupObserver observer) {
            mHandler = new Handler(context.getMainLooper()) {
                @Override
                public void handleMessage(Message msg) {
                    switch (msg.what) {
                        case MSG_UPDATE:
                            Pair<String, BackupProgress> obj =
                                (Pair<String, BackupProgress>) msg.obj;
                            mObserver.onUpdate(obj.first, obj.second);
                            break;
                        case MSG_RESULT:
                            mObserver.onResult((String)msg.obj, msg.arg1);
                            break;
                        case MSG_FINISHED:
                            mObserver.backupFinished(msg.arg1);
                            break;
                        default:
                            Log.w(TAG, "Unknown message: " + msg);
                            break;
                    }
                }
            };
            mObserver = observer;
        }

        // Binder calls into this object just enqueue on the main-thread handler
        @Override
        public void onUpdate(String currentPackage, BackupProgress backupProgress) {
            mHandler.sendMessage(
                mHandler.obtainMessage(MSG_UPDATE, Pair.create(currentPackage, backupProgress)));
        }

        @Override
        public void onResult(String currentPackage, int status) {
            mHandler.sendMessage(
                mHandler.obtainMessage(MSG_RESULT, status, 0, currentPackage));
        }

        @Override
        public void backupFinished(int status) {
            mHandler.sendMessage(
                mHandler.obtainMessage(MSG_FINISHED, status, 0));
        }
    }

    private class SelectTransportListenerWrapper extends ISelectBackupTransportCallback.Stub {

        private final Handler mHandler;
        private final SelectBackupTransportCallback mListener;

        SelectTransportListenerWrapper(Context context, SelectBackupTransportCallback listener) {
            mHandler = new Handler(context.getMainLooper());
            mListener = listener;
        }

        @Override
        public void onSuccess(final String transportName) {
            mHandler.post(new Runnable() {
                @Override
                public void run() {
                    mListener.onSuccess(transportName);
                }
            });
        }

        @Override
        public void onFailure(final int reason) {
            mHandler.post(new Runnable() {
                @Override
                public void run() {
                    mListener.onFailure(reason);
                }
            });
        }
    }

    private class BackupManagerMonitorWrapper extends IBackupManagerMonitor.Stub {
        final BackupManagerMonitor mMonitor;

        BackupManagerMonitorWrapper(BackupManagerMonitor monitor) {
            mMonitor = monitor;
        }

        @Override
        public void onEvent(final Bundle event) throws RemoteException {
            mMonitor.onEvent(event);
        }
    }

}
@attr	ref android.R.styleable#AndroidManifestApplication_allowBackup
@attr	ref android.R.styleable#AndroidManifestApplication_backupAgent
@attr	ref android.R.styleable#AndroidManifestApplication_killAfterRestore
@attr	ref android.R.styleable#AndroidManifestApplication_restoreAnyVersion
Params:	observer – The `RestoreObserver` to receive callbacks during the restore operation. This must not be null. monitor – the `BackupManagerMonitor` to receive callbacks during the restore operation.
Deprecated:	Since Android P app can no longer request restoring of its backup. Restore the calling application from backup. The data will be restored from the current backup dataset if the application has stored data there, or from the dataset used during the last full device setup operation if the current backup dataset has no matching data. If no backup data exists for this application in either source, a nonzero value will be returned. 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.
Returns:	Zero on success; nonzero on error.
@hide
Returns:	The name of the currently active backup transport. In case of failure or if no transport is currently active, this method returns `null`.
@hide
Params:	transportComponent – The identity of the transport being described. name – A `String` with the new name for the transport. This is NOT for identification. MUST NOT be `null`. configurationIntent – An `Intent` that can be passed to `Context.startActivity` in order to launch the transport's configuration UI. It may be `null` if the transport does not offer any user-facing configuration UI. currentDestinationString – A `String` describing the destination to which the transport is currently sending data. MUST NOT be `null`. dataManagementIntent – An `Intent` that can be passed to `Context.startActivity` in order to launch the transport's data-management UI. It may be `null` if the transport does not offer any user-facing data management UI. dataManagementLabel – A `String` to be used as the label for the transport's data management affordance. This MUST be `null` when dataManagementIntent is `null` and MUST NOT be `null` when dataManagementIntent is not `null`.
Throws:	SecurityException – If the UID of the calling process differs from the package UID of `transportComponent` or if the caller does NOT have BACKUP permission.
@hide
Params:	transport – The name of the transport to select. This should be one of the names returned by `listAllTransports()`. This is the String returned by `BackupTransport.name()` for the particular transport.
Returns:	The name of the previously selected transport. If the given transport name is not one of the currently available transports, no change is made to the current transport setting and the method returns null.
@hide
Params:	transport – ComponentName of the service hosting the transport. This is different from the transport's name that is returned by `BackupTransport.name()`. listener – A listener object to get a callback on the transport being selected.
@hide
Params:	packageName – The name of the package whose most-suitable dataset we wish to look up
Returns:	The dataset token from which a restore should be attempted, or zero if no suitable data is available.
@hide
Params:	packageName – The name of the package.
Returns:	Whether this app is eligible for backup.
@hide
Params:	packages – List of package names to backup. observer – The `BackupObserver` to receive callbacks during the backup operation. Could be `null`.
Throws:	IllegalArgumentException – on null or empty `packages` param.
Returns:	`SUCCESS` on success; nonzero on error.
@hide
Params:	transportName – The name of the registered transport.
@hide
/

android/ android-9.0.0_r35/ android/app/backup/BackupManager.java

Developer Guides
