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