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 17 package android.app.backup; 18 19 import android.app.backup.IBackupObserver; 20 import android.app.backup.IBackupManagerMonitor; 21 import android.app.backup.IFullBackupRestoreObserver; 22 import android.app.backup.IRestoreSession; 23 import android.app.backup.ISelectBackupTransportCallback; 24 import android.os.ParcelFileDescriptor; 25 import android.content.Intent; 26 import android.content.ComponentName; 27 28 /** 29 * Direct interface to the Backup Manager Service that applications invoke on. The only 30 * operation currently needed is a simple notification that the app has made changes to 31 * data it wishes to back up, so the system should run a backup pass. 32 * 33 * Apps will use the {@link android.app.backup.BackupManager} class rather than going through 34 * this Binder interface directly. 35 * 36 * {@hide} 37 */ 38 interface IBackupManager { 39 /** 40 * Tell the system service that the caller has made changes to its 41 * data, and therefore needs to undergo an incremental backup pass. 42 * 43 * Any application can invoke this method for its own package, but 44 * only callers who hold the android.permission.BACKUP permission 45 * may invoke it for arbitrary packages. 46 */ dataChanged(String packageName)47 void dataChanged(String packageName); 48 49 /** 50 * Erase all backed-up data for the given package from the given storage 51 * destination. 52 * 53 * Any application can invoke this method for its own package, but 54 * only callers who hold the android.permission.BACKUP permission 55 * may invoke it for arbitrary packages. 56 */ clearBackupData(String transportName, String packageName)57 void clearBackupData(String transportName, String packageName); 58 59 /** 60 * Notifies the Backup Manager Service that an agent has become available. This 61 * method is only invoked by the Activity Manager. 62 */ agentConnected(String packageName, IBinder agent)63 void agentConnected(String packageName, IBinder agent); 64 65 /** 66 * Notify the Backup Manager Service that an agent has unexpectedly gone away. 67 * This method is only invoked by the Activity Manager. 68 */ agentDisconnected(String packageName)69 void agentDisconnected(String packageName); 70 71 /** 72 * Notify the Backup Manager Service that an application being installed will 73 * need a data-restore pass. This method is only invoked by the Package Manager. 74 */ restoreAtInstall(String packageName, int token)75 void restoreAtInstall(String packageName, int token); 76 77 /** 78 * Enable/disable the backup service entirely. When disabled, no backup 79 * or restore operations will take place. Data-changed notifications will 80 * still be observed and collected, however, so that changes made while the 81 * mechanism was disabled will still be backed up properly if it is enabled 82 * at some point in the future. 83 * 84 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 85 */ setBackupEnabled(boolean isEnabled)86 void setBackupEnabled(boolean isEnabled); 87 88 /** 89 * Enable/disable automatic restore of application data at install time. When 90 * enabled, installation of any package will involve the Backup Manager. If data 91 * exists for the newly-installed package, either from the device's current [enabled] 92 * backup dataset or from the restore set used in the last wholesale restore operation, 93 * that data will be supplied to the new package's restore agent before the package 94 * is made generally available for launch. 95 * 96 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 97 * 98 * @param doAutoRestore When true, enables the automatic app-data restore facility. When 99 * false, this facility will be disabled. 100 */ setAutoRestore(boolean doAutoRestore)101 void setAutoRestore(boolean doAutoRestore); 102 103 /** 104 * Indicate that any necessary one-time provisioning has occurred. 105 * 106 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 107 */ setBackupProvisioned(boolean isProvisioned)108 void setBackupProvisioned(boolean isProvisioned); 109 110 /** 111 * Report whether the backup mechanism is currently enabled. 112 * 113 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 114 */ isBackupEnabled()115 boolean isBackupEnabled(); 116 117 /** 118 * Set the device's backup password. Returns {@code true} if the password was set 119 * successfully, {@code false} otherwise. Typically a failure means that an incorrect 120 * current password was supplied. 121 * 122 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 123 */ setBackupPassword(in String currentPw, in String newPw)124 boolean setBackupPassword(in String currentPw, in String newPw); 125 126 /** 127 * Reports whether a backup password is currently set. If not, then a null or empty 128 * "current password" argument should be passed to setBackupPassword(). 129 * 130 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 131 */ hasBackupPassword()132 boolean hasBackupPassword(); 133 134 /** 135 * Schedule an immediate backup attempt for all pending updates. This is 136 * primarily intended for transports to use when they detect a suitable 137 * opportunity for doing a backup pass. If there are no pending updates to 138 * be sent, no action will be taken. Even if some updates are pending, the 139 * transport will still be asked to confirm via the usual requestBackupTime() 140 * method. 141 * 142 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 143 */ backupNow()144 void backupNow(); 145 146 /** 147 * Write a backup of the given package to the supplied file descriptor. 148 * The fd may be a socket or other non-seekable destination. If no package names 149 * are supplied, then every application on the device will be backed up to the output. 150 * Currently only used by the 'adb backup' command. 151 * 152 * <p>This method is <i>synchronous</i> -- it does not return until the backup has 153 * completed. 154 * 155 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 156 * 157 * @param fd The file descriptor to which a 'tar' file stream is to be written 158 * @param includeApks If <code>true</code>, the resulting tar stream will include the 159 * application .apk files themselves as well as their data. 160 * @param includeObbs If <code>true</code>, the resulting tar stream will include any 161 * application expansion (OBB) files themselves belonging to each application. 162 * @param includeShared If <code>true</code>, the resulting tar stream will include 163 * the contents of the device's shared storage (SD card or equivalent). 164 * @param allApps If <code>true</code>, the resulting tar stream will include all 165 * installed applications' data, not just those named in the <code>packageNames</code> 166 * parameter. 167 * @param allIncludesSystem If {@code true}, then {@code allApps} will be interpreted 168 * as including packages pre-installed as part of the system. If {@code false}, 169 * then setting {@code allApps} to {@code true} will mean only that all 3rd-party 170 * applications will be included in the dataset. 171 * @param doKeyValue If {@code true}, also packages supporting key-value backup will be backed 172 * up. If {@code false}, key-value packages will be skipped. 173 * @param packageNames The package names of the apps whose data (and optionally .apk files) 174 * are to be backed up. The <code>allApps</code> parameter supersedes this. 175 */ adbBackup(in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, boolean doCompress, boolean doKeyValue, in String[] packageNames)176 void adbBackup(in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, 177 boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, 178 boolean doCompress, boolean doKeyValue, in String[] packageNames); 179 180 /** 181 * Perform a full-dataset backup of the given applications via the currently active 182 * transport. 183 * 184 * @param packageNames The package names of the apps whose data are to be backed up. 185 */ fullTransportBackup(in String[] packageNames)186 void fullTransportBackup(in String[] packageNames); 187 188 /** 189 * Restore device content from the data stream passed through the given socket. The 190 * data stream must be in the format emitted by adbBackup(). 191 * Currently only used by the 'adb restore' command. 192 * 193 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 194 */ adbRestore(in ParcelFileDescriptor fd)195 void adbRestore(in ParcelFileDescriptor fd); 196 197 /** 198 * Confirm that the requested full backup/restore operation can proceed. The system will 199 * not actually perform the operation described to fullBackup() / fullRestore() unless the 200 * UI calls back into the Backup Manager to confirm, passing the correct token. At 201 * the same time, the UI supplies a callback Binder for progress notifications during 202 * the operation. 203 * 204 * <p>The password passed by the confirming entity must match the saved backup or 205 * full-device encryption password in order to perform a backup. If a password is 206 * supplied for restore, it must match the password used when creating the full 207 * backup dataset being used for restore. 208 * 209 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 210 */ acknowledgeFullBackupOrRestore(int token, boolean allow, in String curPassword, in String encryptionPassword, IFullBackupRestoreObserver observer)211 void acknowledgeFullBackupOrRestore(int token, boolean allow, 212 in String curPassword, in String encryptionPassword, 213 IFullBackupRestoreObserver observer); 214 215 /** 216 * Identify the currently selected transport. Callers must hold the 217 * android.permission.BACKUP permission to use this method. 218 */ getCurrentTransport()219 String getCurrentTransport(); 220 221 /** 222 * Request a list of all available backup transports' names. Callers must 223 * hold the android.permission.BACKUP permission to use this method. 224 */ listAllTransports()225 String[] listAllTransports(); 226 listAllTransportComponents()227 ComponentName[] listAllTransportComponents(); 228 229 /** 230 * Retrieve the list of whitelisted transport components. Callers do </i>not</i> need 231 * any special permission. 232 * 233 * @return The names of all whitelisted transport components defined by the system. 234 */ getTransportWhitelist()235 String[] getTransportWhitelist(); 236 237 /** 238 * Specify the current backup transport. Callers must hold the 239 * android.permission.BACKUP permission to use this method. 240 * 241 * @param transport The name of the transport to select. This should be one 242 * of {@link BackupManager.TRANSPORT_GOOGLE} or {@link BackupManager.TRANSPORT_ADB}. 243 * @return The name of the previously selected transport. If the given transport 244 * name is not one of the currently available transports, no change is made to 245 * the current transport setting and the method returns null. 246 */ selectBackupTransport(String transport)247 String selectBackupTransport(String transport); 248 249 /** 250 * Specify the current backup transport and get notified when the transport is ready to be used. 251 * This method is async because BackupManager might need to bind to the specified transport 252 * which is in a separate process. 253 * 254 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 255 * 256 * @param transport ComponentName of the service hosting the transport. This is different from 257 * the transport's name that is returned by {@link BackupTransport#name()}. 258 * @param listener A listener object to get a callback on the transport being selected. 259 * 260 * @hide 261 */ selectBackupTransportAsync(in ComponentName transport, ISelectBackupTransportCallback listener)262 void selectBackupTransportAsync(in ComponentName transport, ISelectBackupTransportCallback listener); 263 264 /** 265 * Get the configuration Intent, if any, from the given transport. Callers must 266 * hold the android.permission.BACKUP permission in order to use this method. 267 * 268 * @param transport The name of the transport to query. 269 * @return An Intent to use with Activity#startActivity() to bring up the configuration 270 * UI supplied by the transport. If the transport has no configuration UI, it should 271 * return {@code null} here. 272 */ getConfigurationIntent(String transport)273 Intent getConfigurationIntent(String transport); 274 275 /** 276 * Get the destination string supplied by the given transport. Callers must 277 * hold the android.permission.BACKUP permission in order to use this method. 278 * 279 * @param transport The name of the transport to query. 280 * @return A string describing the current backup destination. This string is used 281 * verbatim by the Settings UI as the summary text of the "configure..." item. 282 */ getDestinationString(String transport)283 String getDestinationString(String transport); 284 285 /** 286 * Get the manage-data UI intent, if any, from the given transport. Callers must 287 * hold the android.permission.BACKUP permission in order to use this method. 288 */ getDataManagementIntent(String transport)289 Intent getDataManagementIntent(String transport); 290 291 /** 292 * Get the manage-data menu label, if any, from the given transport. Callers must 293 * hold the android.permission.BACKUP permission in order to use this method. 294 */ getDataManagementLabel(String transport)295 String getDataManagementLabel(String transport); 296 297 /** 298 * Begin a restore session. Either or both of packageName and transportID 299 * may be null. If packageName is non-null, then only the given package will be 300 * considered for restore. If transportID is null, then the restore will use 301 * the current active transport. 302 * <p> 303 * This method requires the android.permission.BACKUP permission <i>except</i> 304 * when transportID is null and packageName is the name of the caller's own 305 * package. In that case, the restore session returned is suitable for supporting 306 * the BackupManager.requestRestore() functionality via RestoreSession.restorePackage() 307 * without requiring the app to hold any special permission. 308 * 309 * @param packageName The name of the single package for which a restore will 310 * be requested. May be null, in which case all packages in the restore 311 * set can be restored. 312 * @param transportID The name of the transport to use for the restore operation. 313 * May be null, in which case the current active transport is used. 314 * @return An interface to the restore session, or null on error. 315 */ beginRestoreSession(String packageName, String transportID)316 IRestoreSession beginRestoreSession(String packageName, String transportID); 317 318 /** 319 * Notify the backup manager that a BackupAgent has completed the operation 320 * corresponding to the given token. 321 * 322 * @param token The transaction token passed to the BackupAgent method being 323 * invoked. 324 * @param result In the case of a full backup measure operation, the estimated 325 * total file size that would result from the operation. Unused in all other 326 * cases. 327 * {@hide} 328 */ opComplete(int token, long result)329 void opComplete(int token, long result); 330 331 /** 332 * Make the device's backup and restore machinery (in)active. When it is inactive, 333 * the device will not perform any backup operations, nor will it deliver data for 334 * restore, although clients can still safely call BackupManager methods. 335 * 336 * @param whichUser User handle of the defined user whose backup active state 337 * is to be adjusted. 338 * @param makeActive {@code true} when backup services are to be made active; 339 * {@code false} otherwise. 340 */ setBackupServiceActive(int whichUser, boolean makeActive)341 void setBackupServiceActive(int whichUser, boolean makeActive); 342 343 /** 344 * Queries the activity status of backup service as set by {@link #setBackupServiceActive}. 345 * @param whichUser User handle of the defined user whose backup active state 346 * is being queried. 347 */ isBackupServiceActive(int whichUser)348 boolean isBackupServiceActive(int whichUser); 349 350 /** 351 * Ask the framework which dataset, if any, the given package's data would be 352 * restored from if we were to install it right now. 353 * 354 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 355 * 356 * @param packageName The name of the package whose most-suitable dataset we 357 * wish to look up 358 * @return The dataset token from which a restore should be attempted, or zero if 359 * no suitable data is available. 360 */ getAvailableRestoreToken(String packageName)361 long getAvailableRestoreToken(String packageName); 362 363 /** 364 * Ask the framework whether this app is eligible for backup. 365 * 366 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 367 * 368 * @param packageName The name of the package. 369 * @return Whether this app is eligible for backup. 370 */ isAppEligibleForBackup(String packageName)371 boolean isAppEligibleForBackup(String packageName); 372 373 /** 374 * Request an immediate backup, providing an observer to which results of the backup operation 375 * will be published. The Android backup system will decide for each package whether it will 376 * be full app data backup or key/value-pair-based backup. 377 * 378 * <p>If this method returns zero (meaning success), the OS will attempt to backup all provided 379 * packages using the remote transport. 380 * 381 * @param observer The {@link BackupObserver} to receive callbacks during the backup 382 * operation. 383 * 384 * @param monitor the {@link BackupManagerMonitor} to receive callbacks about important events 385 * during the backup operation. 386 * 387 * @param flags {@link BackupManager#FLAG_NON_INCREMENTAL_BACKUP}. 388 * 389 * @return Zero on success; nonzero on error. 390 */ requestBackup(in String[] packages, IBackupObserver observer, IBackupManagerMonitor monitor, int flags)391 int requestBackup(in String[] packages, IBackupObserver observer, IBackupManagerMonitor monitor, 392 int flags); 393 394 /** 395 * Cancel all running backups. After this call returns, no currently running backups will 396 * interact with the selected transport. 397 */ cancelBackups()398 void cancelBackups(); 399 } 400