/*
* 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.
* <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";
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.
* <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");
}
}
}
/**
* 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.
*
* @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.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p>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");
}
}
}
/**
* Ask the framework which dataset, if any, the given package's data would be
* restored from if we were to install it right now.
*
* <p>Callers must hold the android.permission.BACKUP permission to use this method.
*
* @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
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;
}
}