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