/* * 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.SystemApi; import android.app.backup.RestoreSession; import android.app.backup.IBackupManager; import android.app.backup.IRestoreSession; import android.content.Context; import android.os.RemoteException; import android.os.ServiceManager; import android.util.Log; /** * 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 {@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. *

* 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. *

* 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 */ public class BackupManager { private static final String TAG = "BackupManager"; 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. * * @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. */ 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. * * @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"); } } } /** * 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 * {@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. * * @return Zero on success; nonzero on error. */ public int requestRestore(RestoreObserver observer) { int result = -1; checkServiceBinder(); if (sService != null) { RestoreSession session = null; try { IRestoreSession binder = sService.beginRestoreSession(mContext.getPackageName(), null); if (binder != null) { session = new RestoreSession(mContext, binder); result = session.restorePackage(mContext.getPackageName(), observer); } } catch (RemoteException e) { Log.e(TAG, "restoreSelf() unable to contact service"); } finally { if (session != null) { session.endRestoreSession(); } } } return result; } // system APIs start here /** * Begin the process of restoring data from backup. See the * {@link android.app.backup.RestoreSession} class for documentation on that process. * @hide */ @SystemApi 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. * *

Callers must hold the android.permission.BACKUP permission to use this method. * * @hide */ @SystemApi 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. * *

Callers must hold the android.permission.BACKUP permission to use this method. * * @hide */ @SystemApi public boolean isBackupEnabled() { checkServiceBinder(); if (sService != null) { try { return sService.isBackupEnabled(); } 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. * *

Callers must hold the android.permission.BACKUP permission to use this method. * * @hide */ @SystemApi 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. Callers must hold the * android.permission.BACKUP permission to use this method. * @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 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. Callers must * hold the android.permission.BACKUP permission to use this method. * * @hide */ @SystemApi public String[] listAllTransports() { checkServiceBinder(); if (sService != null) { try { return sService.listAllTransports(); } catch (RemoteException e) { Log.e(TAG, "listAllTransports() couldn't connect"); } } return null; } /** * Specify the current backup transport. Callers must hold the * android.permission.BACKUP permission to use this method. * * @param transport The name of the transport to select. This should be one * of the names returned by {@link #listAllTransports()}. * @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 */ @SystemApi 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; } /** * 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. * *

Callers must hold the android.permission.BACKUP permission to use this method. * * @hide */ @SystemApi public void backupNow() { checkServiceBinder(); if (sService != null) { try { sService.backupNow(); } catch (RemoteException e) { Log.e(TAG, "backupNow() couldn't connect"); } } } }