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