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.BackupRestoreEventLogger.DataTypeResult; 20 import android.app.backup.IBackupObserver; 21 import android.app.backup.IBackupManagerMonitor; 22 import android.app.backup.IFullBackupRestoreObserver; 23 import android.app.backup.IRestoreSession; 24 import android.app.backup.ISelectBackupTransportCallback; 25 import android.os.ParcelFileDescriptor; 26 import android.os.UserHandle; 27 import android.content.Intent; 28 import android.content.ComponentName; 29 30 /** 31 * Direct interface to the Backup Manager Service that applications invoke on. The only 32 * operation currently needed is a simple notification that the app has made changes to 33 * data it wishes to back up, so the system should run a backup pass. 34 * 35 * Apps will use the {@link android.app.backup.BackupManager} class rather than going through 36 * this Binder interface directly. 37 * 38 * {@hide} 39 */ 40 interface IBackupManager { 41 /** 42 * Tell the system service that the caller has made changes to its 43 * data, and therefore needs to undergo an incremental backup pass. 44 * 45 * Any application can invoke this method for its own package, but 46 * only callers who hold the android.permission.BACKUP permission 47 * may invoke it for arbitrary packages. 48 * If {@code userId} is different from the calling user id, then the caller must hold the 49 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 50 * 51 * @param userId User id for which the caller has made changes to its data. 52 */ dataChangedForUser(int userId, String packageName)53 void dataChangedForUser(int userId, String packageName); 54 55 /** 56 * {@link android.app.backup.IBackupManager.dataChangedForUser} for the calling user id. 57 */ 58 @UnsupportedAppUsage dataChanged(String packageName)59 void dataChanged(String packageName); 60 61 /** 62 * Erase all backed-up data for the given package from the given storage 63 * destination. 64 * 65 * Any application can invoke this method for its own package, but 66 * only callers who hold the android.permission.BACKUP permission 67 * may invoke it for arbitrary packages. 68 * If {@code userId} is different from the calling user id, then the caller must hold the 69 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 70 * 71 * @param userId User id for which backup data should be erased. 72 */ clearBackupDataForUser(int userId, String transportName, String packageName)73 void clearBackupDataForUser(int userId, String transportName, String packageName); 74 75 /** 76 * {@link android.app.backup.IBackupManager.clearBackupDataForUser} for the calling user id. 77 */ 78 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) clearBackupData(String transportName, String packageName)79 void clearBackupData(String transportName, String packageName); 80 81 /** 82 * Run an initialize operation on the given transports. This will wipe all data from 83 * the backing data store and establish a clean starting point for all backup 84 * operations. 85 * 86 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 87 * If {@code userId} is different from the calling user id, then the caller must hold the 88 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 89 * 90 * @param userId User id for which the given transports should be initialized. 91 */ initializeTransportsForUser(int userId, in String[] transportNames, IBackupObserver observer)92 void initializeTransportsForUser(int userId, in String[] transportNames, 93 IBackupObserver observer); 94 95 /** 96 * Notify the Backup Manager Service that an application being installed will 97 * need a data-restore pass. This method is only invoked by the Package Manager. 98 * 99 * If {@code userId} is different from the calling user id, then the caller must hold the 100 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 101 * 102 * @param userId User id for which the application will need a data-restore pass. 103 */ restoreAtInstallForUser(int userId, String packageName, int token)104 void restoreAtInstallForUser(int userId, String packageName, int token); 105 106 /** 107 * {@link android.app.backup.IBackupManager.restoreAtInstallForUser} for the calling user id. 108 */ restoreAtInstall(String packageName, int token)109 void restoreAtInstall(String packageName, int token); 110 111 /** 112 * Enable/disable the backup service entirely. When disabled, no backup 113 * or restore operations will take place. Data-changed notifications will 114 * still be observed and collected, however, so that changes made while the 115 * mechanism was disabled will still be backed up properly if it is enabled 116 * at some point in the future. 117 * 118 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 119 * If {@code userId} is different from the calling user id, then the caller must hold the 120 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 121 * 122 * @param userId User id for which backup service should be enabled/disabled. 123 */ setBackupEnabledForUser(int userId, boolean isEnabled)124 void setBackupEnabledForUser(int userId, boolean isEnabled); 125 126 127 /** 128 * Enable/disable the framework backup scheduling entirely. When disabled, no Key/Value or Full 129 * backup jobs will be scheduled by the Android framework. 130 * 131 * <p>Note: This does not disable backups: only their scheduling is affected and backups can 132 * still be triggered manually. 133 * 134 * <p>Callers must hold the android.permission.BACKUP permission to use this method. If 135 * {@code userId} is different from the calling user id, then the caller must additionally hold 136 * the android.permission.INTERACT_ACROSS_USERS_FULL permission. 137 * 138 * @param userId The user for which backup scheduling should be enabled/disabled. 139 */ setFrameworkSchedulingEnabledForUser(int userId, boolean isEnabled)140 void setFrameworkSchedulingEnabledForUser(int userId, boolean isEnabled); 141 142 /** 143 * {@link android.app.backup.IBackupManager.setBackupEnabledForUser} for the calling user id. 144 */ 145 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) setBackupEnabled(boolean isEnabled)146 void setBackupEnabled(boolean isEnabled); 147 148 /** 149 * Enable/disable automatic restore of application data at install time. When 150 * enabled, installation of any package will involve the Backup Manager. If data 151 * exists for the newly-installed package, either from the device's current [enabled] 152 * backup dataset or from the restore set used in the last wholesale restore operation, 153 * that data will be supplied to the new package's restore agent before the package 154 * is made generally available for launch. 155 * 156 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 157 * If {@code userId} is different from the calling user id, then the caller must hold the 158 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 159 * 160 * @param userId User id for which automatic restore should be enabled/disabled. 161 * @param doAutoRestore When true, enables the automatic app-data restore facility. When 162 * false, this facility will be disabled. 163 */ setAutoRestoreForUser(int userId, boolean doAutoRestore)164 void setAutoRestoreForUser(int userId, boolean doAutoRestore); 165 166 /** 167 * {@link android.app.backup.IBackupManager.setAutoRestoreForUser} for the calling user id. 168 */ 169 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) setAutoRestore(boolean doAutoRestore)170 void setAutoRestore(boolean doAutoRestore); 171 172 /** 173 * Report whether the backup mechanism is currently enabled. 174 * 175 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 176 * If {@code userId} is different from the calling user id, then the caller must hold the 177 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 178 * 179 * @param userId User id for which the backup service status should be reported. 180 */ isBackupEnabledForUser(int userId)181 boolean isBackupEnabledForUser(int userId); 182 183 /** 184 * {@link android.app.backup.IBackupManager.isBackupEnabledForUser} for the calling user id. 185 */ 186 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) isBackupEnabled()187 boolean isBackupEnabled(); 188 189 /** 190 * Set the device's backup password. Returns {@code true} if the password was set 191 * successfully, {@code false} otherwise. Typically a failure means that an incorrect 192 * current password was supplied. 193 * 194 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 195 */ setBackupPassword(in String currentPw, in String newPw)196 boolean setBackupPassword(in String currentPw, in String newPw); 197 198 /** 199 * Reports whether a backup password is currently set. If not, then a null or empty 200 * "current password" argument should be passed to setBackupPassword(). 201 * 202 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 203 */ hasBackupPassword()204 boolean hasBackupPassword(); 205 206 /** 207 * Schedule an immediate backup attempt for all pending updates. This is 208 * primarily intended for transports to use when they detect a suitable 209 * opportunity for doing a backup pass. If there are no pending updates to 210 * be sent, no action will be taken. Even if some updates are pending, the 211 * transport will still be asked to confirm via the usual requestBackupTime() 212 * method. 213 * 214 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 215 * If {@code userId} is different from the calling user id, then the caller must hold the 216 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 217 * 218 * @param userId User id for which an immediate backup should be scheduled. 219 */ backupNowForUser(int userId)220 void backupNowForUser(int userId); 221 222 /** 223 * {@link android.app.backup.IBackupManager.backupNowForUser} for the calling user id. 224 */ backupNow()225 void backupNow(); 226 227 /** 228 * Write a backup of the given package to the supplied file descriptor. 229 * The fd may be a socket or other non-seekable destination. If no package names 230 * are supplied, then every application on the device will be backed up to the output. 231 * Currently only used by the 'adb backup' command. 232 * 233 * <p>This method is <i>synchronous</i> -- it does not return until the backup has 234 * completed. 235 * 236 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 237 * If the {@code userId} is different from the calling user id, then the caller must hold the 238 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 239 * 240 * @param userId User id for which backup should be performed. 241 * @param fd The file descriptor to which a 'tar' file stream is to be written. 242 * @param includeApks If <code>true</code>, the resulting tar stream will include the 243 * application .apk files themselves as well as their data. 244 * @param includeObbs If <code>true</code>, the resulting tar stream will include any 245 * application expansion (OBB) files themselves belonging to each application. 246 * @param includeShared If <code>true</code>, the resulting tar stream will include 247 * the contents of the device's shared storage (SD card or equivalent). 248 * @param allApps If <code>true</code>, the resulting tar stream will include all 249 * installed applications' data, not just those named in the <code>packageNames</code> 250 * parameter. 251 * @param allIncludesSystem If {@code true}, then {@code allApps} will be interpreted 252 * as including packages pre-installed as part of the system. If {@code false}, 253 * then setting {@code allApps} to {@code true} will mean only that all 3rd-party 254 * applications will be included in the dataset. 255 * @param doKeyValue If {@code true}, also packages supporting key-value backup will be backed 256 * up. If {@code false}, key-value packages will be skipped. 257 * @param packageNames The package names of the apps whose data (and optionally .apk files) 258 * are to be backed up. The <code>allApps</code> parameter supersedes this. 259 */ adbBackup(int userId, in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, boolean doCompress, boolean doKeyValue, in String[] packageNames)260 void adbBackup(int userId, in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, 261 boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, 262 boolean doCompress, boolean doKeyValue, in String[] packageNames); 263 264 /** 265 * Perform a full-dataset backup of the given applications via the currently active 266 * transport. 267 * 268 * If {@code userId} is different from the calling user id, then the caller must hold the 269 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 270 * 271 * @param userId User id for which the full-dataset backup should be performed. 272 * @param packageNames The package names of the apps whose data are to be backed up. 273 */ fullTransportBackupForUser(int userId, in String[] packageNames)274 void fullTransportBackupForUser(int userId, in String[] packageNames); 275 276 /** 277 * Restore device content from the data stream passed through the given socket. The 278 * data stream must be in the format emitted by adbBackup(). 279 * Currently only used by the 'adb restore' command. 280 * 281 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 282 * If the {@code userId} is different from the calling user id, then the caller must hold the 283 * android.permission.INTERACT_ACROSS_USERS_FULL. 284 * 285 * @param userId User id for which restore should be performed. 286 */ adbRestore(int userId, in ParcelFileDescriptor fd)287 void adbRestore(int userId, in ParcelFileDescriptor fd); 288 289 /** 290 * Confirm that the requested full backup/restore operation can proceed. The system will 291 * not actually perform the operation described to fullBackup() / fullRestore() unless the 292 * UI calls back into the Backup Manager to confirm, passing the correct token. At 293 * the same time, the UI supplies a callback Binder for progress notifications during 294 * the operation. 295 * 296 * <p>The password passed by the confirming entity must match the saved backup or 297 * full-device encryption password in order to perform a backup. If a password is 298 * supplied for restore, it must match the password used when creating the full 299 * backup dataset being used for restore. 300 * 301 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 302 * If {@code userId} is different from the calling user id, then the caller must hold the 303 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 304 * 305 * @param userId User id for which the requested backup/restore operation can proceed. 306 */ acknowledgeFullBackupOrRestoreForUser(int userId, int token, boolean allow, in String curPassword, in String encryptionPassword, IFullBackupRestoreObserver observer)307 void acknowledgeFullBackupOrRestoreForUser(int userId, int token, boolean allow, 308 in String curPassword, in String encryptionPassword, 309 IFullBackupRestoreObserver observer); 310 311 /** 312 * {@link android.app.backup.IBackupManager.acknowledgeFullBackupOrRestoreForUser} for the 313 * calling user id. 314 */ 315 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) acknowledgeFullBackupOrRestore(int token, boolean allow, in String curPassword, in String encryptionPassword, IFullBackupRestoreObserver observer)316 void acknowledgeFullBackupOrRestore(int token, boolean allow, 317 in String curPassword, in String encryptionPassword, 318 IFullBackupRestoreObserver observer); 319 320 /** 321 * Update the attributes of the transport identified by {@code transportComponent}. If the 322 * specified transport has not been bound at least once (for registration), this call will be 323 * ignored. Only the host process of the transport can change its description, otherwise a 324 * {@link SecurityException} will be thrown. 325 * If {@code userId} is different from the calling user id, then the caller must hold the 326 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 327 * 328 * @param userId User id for which the attributes of the transport should be updated. 329 * @param transportComponent The identity of the transport being described. 330 * @param name A {@link String} with the new name for the transport. This is NOT for 331 * identification. MUST NOT be {@code null}. 332 * @param configurationIntent An {@link Intent} that can be passed to 333 * {@link Context#startActivity} in order to launch the transport's configuration UI. It may 334 * be {@code null} if the transport does not offer any user-facing configuration UI. 335 * @param currentDestinationString A {@link String} describing the destination to which the 336 * transport is currently sending data. MUST NOT be {@code null}. 337 * @param dataManagementIntent An {@link Intent} that can be passed to 338 * {@link Context#startActivity} in order to launch the transport's data-management UI. It 339 * may be {@code null} if the transport does not offer any user-facing data 340 * management UI. 341 * @param dataManagementLabel A {@link CharSequence} to be used as the label for the transport's 342 * data management affordance. This MUST be {@code null} when dataManagementIntent is {@code 343 * null} and MUST NOT be {@code null} when dataManagementIntent is not {@code null}. 344 * @throws SecurityException If the UID of the calling process differs from the package UID of 345 * {@code transportComponent} or if the caller does NOT have BACKUP permission. 346 */ updateTransportAttributesForUser(int userId, in ComponentName transportComponent, in String name, in Intent configurationIntent, in String currentDestinationString, in Intent dataManagementIntent, in CharSequence dataManagementLabel)347 void updateTransportAttributesForUser(int userId, in ComponentName transportComponent, 348 in String name, 349 in Intent configurationIntent, in String currentDestinationString, 350 in Intent dataManagementIntent, in CharSequence dataManagementLabel); 351 352 /** 353 * Identify the currently selected transport. Callers must hold the 354 * android.permission.BACKUP permission to use this method. 355 * If {@code userId} is different from the calling user id, then the caller must hold the 356 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 357 * 358 * @param userId User id for which the currently selected transport should be identified. 359 */ getCurrentTransportForUser(int userId)360 String getCurrentTransportForUser(int userId); 361 362 /** 363 * {@link android.app.backup.IBackupManager.getCurrentTransportForUser} for the calling user id. 364 */ 365 @UnsupportedAppUsage getCurrentTransport()366 String getCurrentTransport(); 367 368 /** 369 * Returns the {@link ComponentName} of the host service of the selected transport or {@code 370 * null} if no transport selected or if the transport selected is not registered. Callers must 371 * hold the android.permission.BACKUP permission to use this method. 372 * If {@code userId} is different from the calling user id, then the caller must hold the 373 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 374 * 375 * @param userId User id for which the currently selected transport should be identified. 376 */ getCurrentTransportComponentForUser(int userId)377 ComponentName getCurrentTransportComponentForUser(int userId); 378 379 /** 380 * Request a list of all available backup transports' names. Callers must 381 * hold the android.permission.BACKUP permission to use this method. 382 * If {@code userId} is different from the calling user id, then the caller must hold the 383 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 384 * 385 * @param userId User id for which all available backup transports' names should be listed. 386 */ listAllTransportsForUser(int userId)387 String[] listAllTransportsForUser(int userId); 388 389 /** 390 * {@link android.app.backup.IBackupManager.listAllTransportsForUser} for the calling user id. 391 */ 392 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) listAllTransports()393 String[] listAllTransports(); 394 395 /** 396 * If {@code userId} is different from the calling user id, then the caller must hold the 397 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 398 * 399 * @param userId User id for which all available backup transports should be listed. 400 */ listAllTransportComponentsForUser(int userId)401 ComponentName[] listAllTransportComponentsForUser(int userId); 402 403 /** 404 * Retrieve the list of whitelisted transport components. Callers do </i>not</i> need 405 * any special permission. 406 * 407 * @return The names of all whitelisted transport components defined by the system. 408 */ getTransportWhitelist()409 String[] getTransportWhitelist(); 410 411 /** 412 * Specify the current backup transport. Callers must hold the 413 * android.permission.BACKUP permission to use this method. 414 * If {@code userId} is different from the calling user id, then the caller must hold the 415 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 416 * 417 * @param userId User id for which the transport should be selected. 418 * @param transport The name of the transport to select. This should be one 419 * of {@link BackupManager.TRANSPORT_GOOGLE} or {@link BackupManager.TRANSPORT_ADB}. 420 * @return The name of the previously selected transport. If the given transport 421 * name is not one of the currently available transports, no change is made to 422 * the current transport setting and the method returns null. 423 */ selectBackupTransportForUser(int userId, String transport)424 String selectBackupTransportForUser(int userId, String transport); 425 426 /** 427 * {@link android.app.backup.IBackupManager.selectBackupTransportForUser} for the calling user 428 * id. 429 */ 430 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) selectBackupTransport(String transport)431 String selectBackupTransport(String transport); 432 433 /** 434 * Specify the current backup transport and get notified when the transport is ready to be used. 435 * This method is async because BackupManager might need to bind to the specified transport 436 * which is in a separate process. 437 * 438 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 439 * If {@code userId} is different from the calling user id, then the caller must hold the 440 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 441 * 442 * @param userId User id for which the transport should be selected. 443 * @param transport ComponentName of the service hosting the transport. This is different from 444 * the transport's name that is returned by {@link BackupTransport#name()}. 445 * @param listener A listener object to get a callback on the transport being selected. 446 */ selectBackupTransportAsyncForUser(int userId, in ComponentName transport, ISelectBackupTransportCallback listener)447 void selectBackupTransportAsyncForUser(int userId, in ComponentName transport, 448 ISelectBackupTransportCallback listener); 449 450 /** 451 * Get the configuration Intent, if any, from the given transport. Callers must 452 * hold the android.permission.BACKUP permission in order to use this method. 453 * If {@code userId} is different from the calling user id, then the caller must hold the 454 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 455 * 456 * @param userId User id for which the configuration Intent should be reported. 457 * @param transport The name of the transport to query. 458 * @return An Intent to use with Activity#startActivity() to bring up the configuration 459 * UI supplied by the transport. If the transport has no configuration UI, it should 460 * return {@code null} here. 461 */ getConfigurationIntentForUser(int userId, String transport)462 Intent getConfigurationIntentForUser(int userId, String transport); 463 464 /** 465 * {@link android.app.backup.IBackupManager.getConfigurationIntentForUser} for the calling user 466 * id. 467 */ getConfigurationIntent(String transport)468 Intent getConfigurationIntent(String transport); 469 470 /** 471 * Get the destination string supplied by the given transport. Callers must 472 * hold the android.permission.BACKUP permission in order to use this method. 473 * If {@code userId} is different from the calling user id, then the caller must hold the 474 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 475 * 476 * @param userId User id for which the transport destination string should be reported. 477 * @param transport The name of the transport to query. 478 * @return A string describing the current backup destination. This string is used 479 * verbatim by the Settings UI as the summary text of the "configure..." item. 480 */ getDestinationStringForUser(int userId, String transport)481 String getDestinationStringForUser(int userId, String transport); 482 483 /** 484 * {@link android.app.backup.IBackupManager.getDestinationStringForUser} for the calling user 485 * id. 486 */ getDestinationString(String transport)487 String getDestinationString(String transport); 488 489 /** 490 * Get the manage-data UI intent, if any, from the given transport. Callers must 491 * hold the android.permission.BACKUP permission in order to use this method. 492 * If {@code userId} is different from the calling user id, then the caller must hold the 493 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 494 * 495 * @param userId User id for which the manage-data UI intent should be reported. 496 */ getDataManagementIntentForUser(int userId, String transport)497 Intent getDataManagementIntentForUser(int userId, String transport); 498 499 /** 500 * {@link android.app.backup.IBackupManager.getDataManagementIntentForUser} for the calling user 501 * id. 502 */ getDataManagementIntent(String transport)503 Intent getDataManagementIntent(String transport); 504 505 /** 506 * Get the manage-data menu label, if any, from the given transport. Callers must 507 * hold the android.permission.BACKUP permission in order to use this method. 508 * If {@code userId} is different from the calling user id, then the caller must hold the 509 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 510 * 511 * @param userId User id for which the manage-data menu label should be reported. 512 */ getDataManagementLabelForUser(int userId, String transport)513 CharSequence getDataManagementLabelForUser(int userId, String transport); 514 515 /** 516 * Begin a restore session. Either or both of packageName and transportID 517 * may be null. If packageName is non-null, then only the given package will be 518 * considered for restore. If transportID is null, then the restore will use 519 * the current active transport. 520 * <p> 521 * This method requires the android.permission.BACKUP permission <i>except</i> 522 * when transportID is null and packageName is the name of the caller's own 523 * package. In that case, the restore session returned is suitable for supporting 524 * the BackupManager.requestRestore() functionality via RestoreSession.restorePackage() 525 * without requiring the app to hold any special permission. 526 * If {@code userId} is different from the calling user id, then the caller must hold the 527 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 528 * 529 * @param userId User id for which a restore session should be begun. 530 * @param packageName The name of the single package for which a restore will 531 * be requested. May be null, in which case all packages in the restore 532 * set can be restored. 533 * @param transportID The name of the transport to use for the restore operation. 534 * May be null, in which case the current active transport is used. 535 * @return An interface to the restore session, or null on error. 536 */ beginRestoreSessionForUser(int userId, String packageName, String transportID)537 IRestoreSession beginRestoreSessionForUser(int userId, String packageName, String transportID); 538 539 /** 540 * Notify the backup manager that a BackupAgent has completed the operation 541 * corresponding to the given token and user id. 542 * 543 * @param userId User id for which the operation has been completed. 544 * @param token The transaction token passed to the BackupAgent method being 545 * invoked. 546 * @param result In the case of a full backup measure operation, the estimated 547 * total file size that would result from the operation. Unused in all other 548 * cases. 549 */ opCompleteForUser(int userId, int token, long result)550 void opCompleteForUser(int userId, int token, long result); 551 552 /** 553 * Notify the backup manager that a BackupAgent has completed the operation 554 * corresponding to the given token. 555 * 556 * @param token The transaction token passed to the BackupAgent method being 557 * invoked. 558 * @param result In the case of a full backup measure operation, the estimated 559 * total file size that would result from the operation. Unused in all other 560 * cases. 561 */ opComplete(int token, long result)562 void opComplete(int token, long result); 563 564 /** 565 * Make the device's backup and restore machinery (in)active. When it is inactive, 566 * the device will not perform any backup operations, nor will it deliver data for 567 * restore, although clients can still safely call BackupManager methods. 568 * 569 * @param whichUser User handle of the defined user whose backup active state 570 * is to be adjusted. 571 * @param makeActive {@code true} when backup services are to be made active; 572 * {@code false} otherwise. 573 */ setBackupServiceActive(int whichUser, boolean makeActive)574 void setBackupServiceActive(int whichUser, boolean makeActive); 575 576 /** 577 * Queries the activity status of backup service as set by {@link #setBackupServiceActive}. 578 * @param whichUser User handle of the defined user whose backup active state 579 * is being queried. 580 */ 581 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) isBackupServiceActive(int whichUser)582 boolean isBackupServiceActive(int whichUser); 583 584 /** 585 * Checks if the user is ready for backup or not. 586 * @param userId User id for which this operation should be performed. 587 */ isUserReadyForBackup(int userId)588 boolean isUserReadyForBackup(int userId); 589 590 /** 591 * Ask the framework which dataset, if any, the given package's data would be 592 * restored from if we were to install it right now. 593 * 594 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 595 * If {@code userId} is different from the calling user id, then the caller must hold the 596 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 597 * 598 * @param userId User id for which this operation should be performed. 599 * @param packageName The name of the package whose most-suitable dataset we 600 * wish to look up 601 * @return The dataset token from which a restore should be attempted, or zero if 602 * no suitable data is available. 603 */ getAvailableRestoreTokenForUser(int userId, String packageName)604 long getAvailableRestoreTokenForUser(int userId, String packageName); 605 606 /** 607 * Ask the framework whether this app is eligible for backup. 608 * 609 * <p>If you are calling this method multiple times, you should instead use 610 * {@link #filterAppsEligibleForBackup(String[])} to save resources. 611 * 612 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 613 * If {@code userId} is different from the calling user id, then the caller must hold the 614 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 615 * 616 * @param userId User id for which this operation should be performed. 617 * @param packageName The name of the package. 618 * @return Whether this app is eligible for backup. 619 */ isAppEligibleForBackupForUser(int userId, String packageName)620 boolean isAppEligibleForBackupForUser(int userId, String packageName); 621 622 /** 623 * Filter the packages that are eligible for backup and return the result. 624 * 625 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 626 * If {@code userId} is different from the calling user id, then the caller must hold the 627 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 628 * 629 * @param userId User id for which the filter should be performed. 630 * @param packages The list of packages to filter. 631 * @return The packages eligible for backup. 632 */ filterAppsEligibleForBackupForUser(int userId, in String[] packages)633 String[] filterAppsEligibleForBackupForUser(int userId, in String[] packages); 634 635 /** 636 * Request an immediate backup, providing an observer to which results of the backup operation 637 * will be published. The Android backup system will decide for each package whether it will 638 * be full app data backup or key/value-pair-based backup. 639 * 640 * <p>If this method returns zero (meaning success), the OS will attempt to backup all provided 641 * packages using the remote transport. 642 * 643 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 644 * If {@code userId} is different from the calling user id, then the caller must hold the 645 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 646 * 647 * @param userId User id for which an immediate backup should be requested. 648 649 * @param observer The {@link BackupObserver} to receive callbacks during the backup 650 * operation. 651 * 652 * @param monitor the {@link BackupManagerMonitor} to receive callbacks about important events 653 * during the backup operation. 654 * 655 * @param flags {@link BackupManager#FLAG_NON_INCREMENTAL_BACKUP}. 656 * 657 * @return Zero on success; nonzero on error. 658 */ requestBackupForUser(int userId, in String[] packages, IBackupObserver observer, IBackupManagerMonitor monitor, int flags)659 int requestBackupForUser(int userId, in String[] packages, IBackupObserver observer, 660 IBackupManagerMonitor monitor, int flags); 661 662 /** 663 * {@link android.app.backup.IBackupManager.requestBackupForUser} for the calling user id. 664 */ requestBackup(in String[] packages, IBackupObserver observer, IBackupManagerMonitor monitor, int flags)665 int requestBackup(in String[] packages, IBackupObserver observer, IBackupManagerMonitor monitor, 666 int flags); 667 668 /** 669 * Cancel all running backups. After this call returns, no currently running backups will 670 * interact with the selected transport. 671 * 672 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 673 * If {@code userId} is different from the calling user id, then the caller must hold the 674 * android.permission.INTERACT_ACROSS_USERS_FULL permission. 675 * 676 * @param userId User id for which backups should be cancelled. 677 */ cancelBackupsForUser(int userId)678 void cancelBackupsForUser(int userId); 679 680 /** 681 * {@link android.app.backup.IBackupManager.cancelBackups} for the calling user id. 682 */ cancelBackups()683 void cancelBackups(); 684 685 /** 686 * Returns a {@link UserHandle} for the user that has {@code ancestralSerialNumber} as the serial 687 * number of the it's ancestral work profile. 688 * 689 * <p> The ancestral work profile is set by {@link #setAncestralSerialNumber(long)} 690 * and it corresponds to the profile that was used to restore to the callers profile. 691 */ getUserForAncestralSerialNumber(in long ancestralSerialNumber)692 UserHandle getUserForAncestralSerialNumber(in long ancestralSerialNumber); 693 694 /** 695 * Sets the ancestral work profile for the calling user. 696 * 697 * <p> The ancestral work profile corresponds to the profile that was used to restore to the 698 * callers profile. 699 * 700 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 701 */ setAncestralSerialNumber(in long ancestralSerialNumber)702 void setAncestralSerialNumber(in long ancestralSerialNumber); 703 704 /** 705 * Excludes keys from KV restore for a given package. The corresponding data will be excluded 706 * from the data set available the backup agent during restore. However, final list of keys 707 * that have been excluded will be passed to the agent to make it aware of the exclusions. 708 */ excludeKeysFromRestore(String packageName, in List<String> keys)709 void excludeKeysFromRestore(String packageName, in List<String> keys); 710 reportDelayedRestoreResult(in String packageName, in List<DataTypeResult> results)711 void reportDelayedRestoreResult(in String packageName, in List<DataTypeResult> results); 712 } 713