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