BackupManager.java revision cc84c69726507a85116f5664e20e2ebfac76edbe
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.app.backup; 18 19import android.app.backup.RestoreSession; 20import android.app.backup.IBackupManager; 21import android.app.backup.IRestoreSession; 22import android.content.Context; 23import android.os.RemoteException; 24import android.os.ServiceManager; 25import android.util.Log; 26 27/** 28 * BackupManager is the interface to the system's backup service. Applications 29 * simply instantiate one, and then use that instance to communicate with the 30 * backup infrastructure. 31 * <p> 32 * When an application has made changes to data which should be backed up, a 33 * call to {@link #dataChanged()} will notify the backup service. The system 34 * will then schedule a backup operation to occur in the near future. Repeated 35 * calls to {@link #dataChanged()} have no further effect until the backup 36 * operation actually occurs. 37 * <p> 38 * The backup operation itself begins with the system launching the 39 * {@link android.app.backup.BackupAgent} subclass declared in your manifest. See the 40 * documentation for {@link android.app.backup.BackupAgent} for a detailed description 41 * of how the backup then proceeds. 42 * <p> 43 * A simple implementation of a BackupAgent useful for backing up Preferences 44 * and files is available by using {@link android.app.backup.BackupAgentHelper}. 45 * <p> 46 * STOPSHIP: more documentation! 47 * <p> 48 * <b>XML attributes</b> 49 * <p> 50 * See {@link android.R.styleable#AndroidManifestApplication 51 * AndroidManifest.xml's application attributes} 52 * 53 * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup 54 * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent 55 * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore 56 */ 57public class BackupManager { 58 private static final String TAG = "BackupManager"; 59 60 private Context mContext; 61 private static IBackupManager sService; 62 63 private static void checkServiceBinder() { 64 if (sService == null) { 65 sService = IBackupManager.Stub.asInterface( 66 ServiceManager.getService(Context.BACKUP_SERVICE)); 67 } 68 } 69 70 /** 71 * Constructs a BackupManager object through which the application can 72 * communicate with the Android backup system. 73 * 74 * @param context The {@link android.content.Context} that was provided when 75 * one of your application's {@link android.app.Activity Activities} 76 * was created. 77 */ 78 public BackupManager(Context context) { 79 mContext = context; 80 } 81 82 /** 83 * Notifies the Android backup system that your application wishes to back up 84 * new changes to its data. A backup operation using your application's 85 * {@link android.app.backup.BackupAgent} subclass will be scheduled when you call this method. 86 */ 87 public void dataChanged() { 88 checkServiceBinder(); 89 if (sService != null) { 90 try { 91 sService.dataChanged(mContext.getPackageName()); 92 } catch (RemoteException e) { 93 Log.d(TAG, "dataChanged() couldn't connect"); 94 } 95 } 96 } 97 98 /** 99 * Convenience method for callers who need to indicate that some other package 100 * needs a backup pass. This can be relevant in the case of groups of packages 101 * that share a uid, for example. 102 * 103 * This method requires that the application hold the "android.permission.BACKUP" 104 * permission if the package named in the argument is not the caller's own. 105 */ 106 public static void dataChanged(String packageName) { 107 checkServiceBinder(); 108 if (sService != null) { 109 try { 110 sService.dataChanged(packageName); 111 } catch (RemoteException e) { 112 Log.d(TAG, "dataChanged(pkg) couldn't connect"); 113 } 114 } 115 } 116 117 /** 118 * Restore the calling application from backup. The data will be restored from the 119 * current backup dataset if the application has stored data there, or from 120 * the dataset used during the last full device setup operation if the current 121 * backup dataset has no matching data. If no backup data exists for this application 122 * in either source, a nonzero value will be returned. 123 * 124 * <p>If this method returns zero (meaning success), the OS will attempt to retrieve 125 * a backed-up dataset from the remote transport, instantiate the application's 126 * backup agent, and pass the dataset to the agent's 127 * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()} 128 * method. 129 * 130 * @return Zero on success; nonzero on error. 131 */ 132 public int requestRestore(RestoreObserver observer) { 133 int result = -1; 134 checkServiceBinder(); 135 if (sService != null) { 136 RestoreSession session = null; 137 try { 138 String transport = sService.getCurrentTransport(); 139 IRestoreSession binder = sService.beginRestoreSession(transport); 140 session = new RestoreSession(mContext, binder); 141 result = session.restorePackage(mContext.getPackageName(), observer); 142 } catch (RemoteException e) { 143 Log.w(TAG, "restoreSelf() unable to contact service"); 144 } finally { 145 if (session != null) { 146 session.endRestoreSession(); 147 } 148 } 149 } 150 return result; 151 } 152 153 /** 154 * Begin the process of restoring data from backup. See the 155 * {@link android.app.backup.RestoreSession} class for documentation on that process. 156 * @hide 157 */ 158 public RestoreSession beginRestoreSession() { 159 RestoreSession session = null; 160 checkServiceBinder(); 161 if (sService != null) { 162 try { 163 String transport = sService.getCurrentTransport(); 164 IRestoreSession binder = sService.beginRestoreSession(transport); 165 session = new RestoreSession(mContext, binder); 166 } catch (RemoteException e) { 167 Log.w(TAG, "beginRestoreSession() couldn't connect"); 168 } 169 } 170 return session; 171 } 172} 173