| /* |
| * 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.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.RequiresPermission; |
| import android.annotation.SystemApi; |
| import android.app.backup.BackupAnnotations.OperationType; |
| import android.app.compat.CompatChanges; |
| import android.compat.annotation.ChangeId; |
| import android.compat.annotation.EnabledAfter; |
| import android.compat.annotation.UnsupportedAppUsage; |
| import android.content.ComponentName; |
| import android.content.Context; |
| import android.content.Intent; |
| import android.os.Build; |
| 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; |
| |
| import com.android.internal.annotations.VisibleForTesting; |
| |
| import java.util.List; |
| |
| /** |
| * 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"><application></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 |
| */ |
| @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 |
| */ |
| @SystemApi |
| public static final int ERROR_BACKUP_NOT_ALLOWED = -2001; |
| |
| /** |
| * 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 |
| */ |
| @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 |
| */ |
| @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 {@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 |
| */ |
| @SystemApi |
| public static final int ERROR_TRANSPORT_QUOTA_EXCEEDED = |
| BackupTransport.TRANSPORT_QUOTA_EXCEEDED; |
| |
| /** |
| * 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 |
| */ |
| public static final String EXTRA_BACKUP_SERVICES_AVAILABLE = "backup_services_available"; |
| |
| /** |
| * 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 {@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 {@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 {@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; |
| |
| /** |
| * @hide Making this package private is not sufficient for the test to access it, that's because |
| * the test is in the same package but is loaded with a different class loader. Package |
| * private members are not accessible across class loaders. So we make it public and @hide it. |
| */ |
| @UnsupportedAppUsage |
| @VisibleForTesting |
| public static IBackupManager sService; |
| |
| @UnsupportedAppUsage |
| 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. |
| * |
| * @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 |
| * {@link android.app.backup.BackupAgent} subclass will be scheduled when you |
| * call this method. |
| * |
| * <p> |
| * Note: This only works if your application is performing Key/Value backups. |
| */ |
| 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. |
| * <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. |
| * <p> |
| * Note: Only works for packages performing Key/Value backups. |
| */ |
| 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"); |
| } |
| } |
| } |
| |
| /** |
| * Convenience method for callers who need to indicate that some other package or |
| * some other user needs a backup pass. This can be useful in the case of groups of |
| * packages that share a uid and/or have user-specific data. |
| * <p> |
| * This method requires that the application hold the "android.permission.BACKUP" |
| * permission if the package named in the package argument does not run under the |
| * same uid as the caller. This method also requires that the application hold the |
| * "android.permission.INTERACT_ACROSS_USERS_FULL" if the user argument is not the |
| * same as the user the caller is running under. |
| * @param userId The user to back up |
| * @param packageName The package name identifying the application to back up. |
| * |
| * @hide |
| */ |
| public static void dataChangedForUser(int userId, String packageName) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| sService.dataChangedForUser(userId, packageName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "dataChanged(userId,pkg) couldn't connect"); |
| } |
| } |
| } |
| |
| /** |
| * @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 |
| |
| /** |
| * @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 |
| * {@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.beginRestoreSessionForUser(mContext.getUserId(), 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 |
| */ |
| @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"); |
| } |
| } |
| } |
| |
| /** |
| * Enable/disable the framework backup scheduling entirely for the context user. When disabled, |
| * no Key/Value or Full backup jobs will be scheduled by the Android framework. |
| * |
| * <p>Note: This does not disable backups: only their scheduling is affected and backups can |
| * still be triggered manually. |
| * |
| * <p>Callers must hold the android.permission.BACKUP permission to use this method. If the |
| * context user is different from the calling user, then the caller must additionally hold the |
| * android.permission.INTERACT_ACROSS_USERS_FULL permission. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(allOf = {android.Manifest.permission.BACKUP, |
| android.Manifest.permission.INTERACT_ACROSS_USERS_FULL}, conditional = true) |
| public void setFrameworkSchedulingEnabled(boolean isEnabled) { |
| checkServiceBinder(); |
| if (sService == null) { |
| Log.e(TAG, "setFrameworkSchedulingEnabled() couldn't connect"); |
| return; |
| } |
| |
| try { |
| sService.setFrameworkSchedulingEnabledForUser(mContext.getUserId(), isEnabled); |
| } catch (RemoteException e) { |
| Log.e(TAG, "setFrameworkSchedulingEnabled() couldn't connect"); |
| } |
| } |
| |
| /** |
| * 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; |
| } |
| |
| |
| /** |
| * If this change is enabled, the {@code BACKUP} permission needed for |
| * {@code isBackupServiceActive()} will be enforced on the service end |
| * rather than client-side in {@link BackupManager}. |
| * @hide |
| */ |
| @ChangeId |
| @EnabledAfter(targetSdkVersion = Build.VERSION_CODES.R) |
| public static final long IS_BACKUP_SERVICE_ACTIVE_ENFORCE_PERMISSION_IN_SERVICE = 158482162; |
| |
| /** |
| * 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) { |
| if (!CompatChanges.isChangeEnabled( |
| IS_BACKUP_SERVICE_ACTIVE_ENFORCE_PERMISSION_IN_SERVICE)) { |
| 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 |
| */ |
| @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. |
| * @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; |
| } |
| |
| /** |
| * Returns the {@link ComponentName} of the host service of the selected transport or {@code |
| * null} if no transport selected or if the transport selected is not registered. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| @Nullable |
| public ComponentName getCurrentTransportComponent() { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getCurrentTransportComponentForUser(mContext.getUserId()); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getCurrentTransportComponent() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * 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 {@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. |
| * @deprecated Since Android Q, please use the variant {@link |
| * #updateTransportAttributes(ComponentName, String, Intent, String, Intent, CharSequence)} |
| * instead. |
| * @hide |
| */ |
| @Deprecated |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public void updateTransportAttributes( |
| @NonNull ComponentName transportComponent, |
| @NonNull String name, |
| @Nullable Intent configurationIntent, |
| @NonNull String currentDestinationString, |
| @Nullable Intent dataManagementIntent, |
| @Nullable String dataManagementLabel) { |
| updateTransportAttributes( |
| transportComponent, |
| name, |
| configurationIntent, |
| currentDestinationString, |
| dataManagementIntent, |
| (CharSequence) dataManagementLabel); |
| } |
| |
| /** |
| * 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 CharSequence} 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( |
| @NonNull ComponentName transportComponent, |
| @NonNull String name, |
| @Nullable Intent configurationIntent, |
| @NonNull String currentDestinationString, |
| @Nullable Intent dataManagementIntent, |
| @Nullable CharSequence dataManagementLabel) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| sService.updateTransportAttributesForUser( |
| mContext.getUserId(), |
| transportComponent, |
| name, |
| configurationIntent, |
| currentDestinationString, |
| dataManagementIntent, |
| dataManagementLabel); |
| } catch (RemoteException e) { |
| Log.e(TAG, "describeTransport() couldn't connect"); |
| } |
| } |
| } |
| |
| /** |
| * 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. |
| * |
| * @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.selectBackupTransportAsyncForUser( |
| mContext.getUserId(), 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 |
| */ |
| @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. |
| * |
| * @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.getAvailableRestoreTokenForUser(mContext.getUserId(), packageName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getAvailableRestoreToken() couldn't connect"); |
| } |
| } |
| return 0; |
| } |
| |
| /** |
| * 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.isAppEligibleForBackupForUser(mContext.getUserId(), 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. |
| * |
| * <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. |
| * |
| * <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 |
| */ |
| @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 a {@link UserHandle} for the user that has {@code ancestralSerialNumber} as the |
| * serial number of the its ancestral work profile or {@code null} if there is none. |
| * |
| * <p> The ancestral serial number will have a corresponding {@link UserHandle} if the device |
| * has a work profile that was restored from another work profile with serial number |
| * {@code ancestralSerialNumber}. |
| * |
| * @see android.os.UserManager#getSerialNumberForUser(UserHandle) |
| */ |
| @Nullable |
| public UserHandle getUserForAncestralSerialNumber(long ancestralSerialNumber) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getUserForAncestralSerialNumber(ancestralSerialNumber); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getUserForAncestralSerialNumber() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Sets the ancestral work profile for the calling user. |
| * |
| * <p> The ancestral work profile corresponds to the profile that was used to restore to the |
| * callers profile. |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public void setAncestralSerialNumber(long ancestralSerialNumber) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| sService.setAncestralSerialNumber(ancestralSerialNumber); |
| } catch (RemoteException e) { |
| Log.e(TAG, "setAncestralSerialNumber() couldn't connect"); |
| } |
| } |
| } |
| |
| /** |
| * Returns an {@link Intent} for the specified transport's configuration UI. |
| * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String, |
| * Intent, CharSequence)}. |
| * @param transportName The name of the registered transport. |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public Intent getConfigurationIntent(String transportName) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getConfigurationIntentForUser(mContext.getUserId(), transportName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getConfigurationIntent() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Returns a {@link String} describing where the specified transport is sending data. |
| * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String, |
| * Intent, CharSequence)}. |
| * @param transportName The name of the registered transport. |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public String getDestinationString(String transportName) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getDestinationStringForUser(mContext.getUserId(), transportName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getDestinationString() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Returns an {@link Intent} for the specified transport's data management UI. |
| * This value is set by {@link #updateTransportAttributes(ComponentName, String, Intent, String, |
| * Intent, CharSequence)}. |
| * @param transportName The name of the registered transport. |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public Intent getDataManagementIntent(String transportName) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getDataManagementIntentForUser(mContext.getUserId(), transportName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getDataManagementIntent() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * 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, CharSequence)}. |
| * |
| * @param transportName The name of the registered transport. |
| * @deprecated Since Android Q, please use the variant {@link |
| * #getDataManagementIntentLabel(String)} instead. |
| * @hide |
| */ |
| @Deprecated |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| @Nullable |
| public String getDataManagementLabel(@NonNull String transportName) { |
| CharSequence label = getDataManagementIntentLabel(transportName); |
| return label == null ? null : label.toString(); |
| } |
| |
| /** |
| * Returns a {@link CharSequence} describing what the specified transport's data management |
| * intent is used for. This value is set by {@link #updateTransportAttributes(ComponentName, |
| * String, Intent, String, Intent, CharSequence)}. |
| * |
| * @param transportName The name of the registered transport. |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| @Nullable |
| public CharSequence getDataManagementIntentLabel(@NonNull String transportName) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| return sService.getDataManagementLabelForUser(mContext.getUserId(), transportName); |
| } catch (RemoteException e) { |
| Log.e(TAG, "getDataManagementIntentLabel() couldn't connect"); |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Excludes keys from KV restore for a given package. The corresponding data will be excluded |
| * from the data set available the backup agent during restore. However, final list of keys |
| * that have been excluded will be passed to the agent to make it aware of the exclusions. |
| * |
| * @param packageName The name of the package for which to exclude keys. |
| * @param keys The list of keys to exclude. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(android.Manifest.permission.BACKUP) |
| public void excludeKeysFromRestore(@NonNull String packageName, @NonNull List<String> keys) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| sService.excludeKeysFromRestore(packageName, keys); |
| } catch (RemoteException e) { |
| Log.e(TAG, "excludeKeysFromRestore() couldn't connect"); |
| } |
| } |
| } |
| |
| /** |
| * Get an instance of {@link BackupRestoreEventLogger} to report B&R related events during an |
| * ongoing backup or restore operation. |
| * |
| * @param backupAgent the agent currently running a B&R operation. |
| * |
| * @return an instance of {@code BackupRestoreEventLogger} or {@code null} if the agent has not |
| * finished initialisation, i.e. {@link BackupAgent#onCreate()} has not been called yet. |
| * @throws IllegalStateException if called before the agent has finished initialisation. |
| * |
| * @hide |
| */ |
| @NonNull |
| @SystemApi |
| public BackupRestoreEventLogger getBackupRestoreEventLogger(@NonNull BackupAgent backupAgent) { |
| BackupRestoreEventLogger logger = backupAgent.getBackupRestoreEventLogger(); |
| if (logger == null) { |
| throw new IllegalStateException("Attempting to get logger on an uninitialised " |
| + "BackupAgent"); |
| } |
| return backupAgent.getBackupRestoreEventLogger(); |
| } |
| |
| /** |
| * Get an instance of {@link BackupRestoreEventLogger} to report B&R related events during a |
| * delayed restore operation. |
| * |
| * @return an instance of {@link BackupRestoreEventLogger}. |
| * |
| * @hide |
| */ |
| @NonNull |
| @SystemApi |
| public BackupRestoreEventLogger getDelayedRestoreLogger() { |
| return new BackupRestoreEventLogger(OperationType.RESTORE); |
| } |
| |
| /** |
| * Report B&R related events following a delayed restore operation. |
| * |
| * @param logger an instance of {@link BackupRestoreEventLogger} to which the corresponding |
| * events have been logged. |
| * |
| * @hide |
| */ |
| @SystemApi |
| public void reportDelayedRestoreResult(@NonNull BackupRestoreEventLogger logger) { |
| checkServiceBinder(); |
| if (sService != null) { |
| try { |
| sService.reportDelayedRestoreResult(mContext.getPackageName(), |
| logger.getLoggingResults()); |
| } catch (RemoteException e) { |
| Log.w(TAG, "reportDelayedRestoreResult() couldn't connect"); |
| } |
| } |
| } |
| |
| /* |
| * 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); |
| } |
| }); |
| } |
| } |
| } |
