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.IFullBackupRestoreObserver; 21 import android.app.backup.IRestoreSession; 22 import android.os.ParcelFileDescriptor; 23 import android.content.Intent; 24 25 /** 26 * Direct interface to the Backup Manager Service that applications invoke on. The only 27 * operation currently needed is a simple notification that the app has made changes to 28 * data it wishes to back up, so the system should run a backup pass. 29 * 30 * Apps will use the {@link android.app.backup.BackupManager} class rather than going through 31 * this Binder interface directly. 32 * 33 * {@hide} 34 */ 35 interface IBackupManager { 36 /** 37 * Tell the system service that the caller has made changes to its 38 * data, and therefore needs to undergo an incremental backup pass. 39 * 40 * Any application can invoke this method for its own package, but 41 * only callers who hold the android.permission.BACKUP permission 42 * may invoke it for arbitrary packages. 43 */ dataChanged(String packageName)44 void dataChanged(String packageName); 45 46 /** 47 * Erase all backed-up data for the given package from the given storage 48 * destination. 49 * 50 * Any application can invoke this method for its own package, but 51 * only callers who hold the android.permission.BACKUP permission 52 * may invoke it for arbitrary packages. 53 */ clearBackupData(String transportName, String packageName)54 void clearBackupData(String transportName, String packageName); 55 56 /** 57 * Notifies the Backup Manager Service that an agent has become available. This 58 * method is only invoked by the Activity Manager. 59 */ agentConnected(String packageName, IBinder agent)60 void agentConnected(String packageName, IBinder agent); 61 62 /** 63 * Notify the Backup Manager Service that an agent has unexpectedly gone away. 64 * This method is only invoked by the Activity Manager. 65 */ agentDisconnected(String packageName)66 void agentDisconnected(String packageName); 67 68 /** 69 * Notify the Backup Manager Service that an application being installed will 70 * need a data-restore pass. This method is only invoked by the Package Manager. 71 */ restoreAtInstall(String packageName, int token)72 void restoreAtInstall(String packageName, int token); 73 74 /** 75 * Enable/disable the backup service entirely. When disabled, no backup 76 * or restore operations will take place. Data-changed notifications will 77 * still be observed and collected, however, so that changes made while the 78 * mechanism was disabled will still be backed up properly if it is enabled 79 * at some point in the future. 80 * 81 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 82 */ setBackupEnabled(boolean isEnabled)83 void setBackupEnabled(boolean isEnabled); 84 85 /** 86 * Enable/disable automatic restore of application data at install time. When 87 * enabled, installation of any package will involve the Backup Manager. If data 88 * exists for the newly-installed package, either from the device's current [enabled] 89 * backup dataset or from the restore set used in the last wholesale restore operation, 90 * that data will be supplied to the new package's restore agent before the package 91 * is made generally available for launch. 92 * 93 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 94 * 95 * @param doAutoRestore When true, enables the automatic app-data restore facility. When 96 * false, this facility will be disabled. 97 */ setAutoRestore(boolean doAutoRestore)98 void setAutoRestore(boolean doAutoRestore); 99 100 /** 101 * Indicate that any necessary one-time provisioning has occurred. 102 * 103 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 104 */ setBackupProvisioned(boolean isProvisioned)105 void setBackupProvisioned(boolean isProvisioned); 106 107 /** 108 * Report whether the backup mechanism is currently enabled. 109 * 110 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 111 */ isBackupEnabled()112 boolean isBackupEnabled(); 113 114 /** 115 * Set the device's backup password. Returns {@code true} if the password was set 116 * successfully, {@code false} otherwise. Typically a failure means that an incorrect 117 * current password was supplied. 118 * 119 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 120 */ setBackupPassword(in String currentPw, in String newPw)121 boolean setBackupPassword(in String currentPw, in String newPw); 122 123 /** 124 * Reports whether a backup password is currently set. If not, then a null or empty 125 * "current password" argument should be passed to setBackupPassword(). 126 * 127 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 128 */ hasBackupPassword()129 boolean hasBackupPassword(); 130 131 /** 132 * Schedule an immediate backup attempt for all pending updates. This is 133 * primarily intended for transports to use when they detect a suitable 134 * opportunity for doing a backup pass. If there are no pending updates to 135 * be sent, no action will be taken. Even if some updates are pending, the 136 * transport will still be asked to confirm via the usual requestBackupTime() 137 * method. 138 * 139 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 140 */ backupNow()141 void backupNow(); 142 143 /** 144 * Write a full backup of the given package to the supplied file descriptor. 145 * The fd may be a socket or other non-seekable destination. If no package names 146 * are supplied, then every application on the device will be backed up to the output. 147 * 148 * <p>This method is <i>synchronous</i> -- it does not return until the backup has 149 * completed. 150 * 151 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 152 * 153 * @param fd The file descriptor to which a 'tar' file stream is to be written 154 * @param includeApks If <code>true</code>, the resulting tar stream will include the 155 * application .apk files themselves as well as their data. 156 * @param includeObbs If <code>true</code>, the resulting tar stream will include any 157 * application expansion (OBB) files themselves belonging to each application. 158 * @param includeShared If <code>true</code>, the resulting tar stream will include 159 * the contents of the device's shared storage (SD card or equivalent). 160 * @param allApps If <code>true</code>, the resulting tar stream will include all 161 * installed applications' data, not just those named in the <code>packageNames</code> 162 * parameter. 163 * @param allIncludesSystem If {@code true}, then {@code allApps} will be interpreted 164 * as including packages pre-installed as part of the system. If {@code false}, 165 * then setting {@code allApps} to {@code true} will mean only that all 3rd-party 166 * applications will be included in the dataset. 167 * @param packageNames The package names of the apps whose data (and optionally .apk files) 168 * are to be backed up. The <code>allApps</code> parameter supersedes this. 169 */ fullBackup(in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, boolean doCompress, in String[] packageNames)170 void fullBackup(in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs, 171 boolean includeShared, boolean doWidgets, boolean allApps, boolean allIncludesSystem, 172 boolean doCompress, in String[] packageNames); 173 174 /** 175 * Perform a full-dataset backup of the given applications via the currently active 176 * transport. 177 * 178 * @param packageNames The package names of the apps whose data are to be backed up. 179 */ fullTransportBackup(in String[] packageNames)180 void fullTransportBackup(in String[] packageNames); 181 182 /** 183 * Restore device content from the data stream passed through the given socket. The 184 * data stream must be in the format emitted by fullBackup(). 185 * 186 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 187 */ fullRestore(in ParcelFileDescriptor fd)188 void fullRestore(in ParcelFileDescriptor fd); 189 190 /** 191 * Confirm that the requested full backup/restore operation can proceed. The system will 192 * not actually perform the operation described to fullBackup() / fullRestore() unless the 193 * UI calls back into the Backup Manager to confirm, passing the correct token. At 194 * the same time, the UI supplies a callback Binder for progress notifications during 195 * the operation. 196 * 197 * <p>The password passed by the confirming entity must match the saved backup or 198 * full-device encryption password in order to perform a backup. If a password is 199 * supplied for restore, it must match the password used when creating the full 200 * backup dataset being used for restore. 201 * 202 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 203 */ acknowledgeFullBackupOrRestore(int token, boolean allow, in String curPassword, in String encryptionPassword, IFullBackupRestoreObserver observer)204 void acknowledgeFullBackupOrRestore(int token, boolean allow, 205 in String curPassword, in String encryptionPassword, 206 IFullBackupRestoreObserver observer); 207 208 /** 209 * Identify the currently selected transport. Callers must hold the 210 * android.permission.BACKUP permission to use this method. 211 */ getCurrentTransport()212 String getCurrentTransport(); 213 214 /** 215 * Request a list of all available backup transports' names. Callers must 216 * hold the android.permission.BACKUP permission to use this method. 217 */ listAllTransports()218 String[] listAllTransports(); 219 220 /** 221 * Retrieve the list of whitelisted transport components. Callers do </i>not</i> need 222 * any special permission. 223 * 224 * @return The names of all whitelisted transport components defined by the system. 225 */ getTransportWhitelist()226 String[] getTransportWhitelist(); 227 228 /** 229 * Specify the current backup transport. Callers must hold the 230 * android.permission.BACKUP permission to use this method. 231 * 232 * @param transport The name of the transport to select. This should be one 233 * of {@link BackupManager.TRANSPORT_GOOGLE} or {@link BackupManager.TRANSPORT_ADB}. 234 * @return The name of the previously selected transport. If the given transport 235 * name is not one of the currently available transports, no change is made to 236 * the current transport setting and the method returns null. 237 */ selectBackupTransport(String transport)238 String selectBackupTransport(String transport); 239 240 /** 241 * Get the configuration Intent, if any, from the given transport. Callers must 242 * hold the android.permission.BACKUP permission in order to use this method. 243 * 244 * @param transport The name of the transport to query. 245 * @return An Intent to use with Activity#startActivity() to bring up the configuration 246 * UI supplied by the transport. If the transport has no configuration UI, it should 247 * return {@code null} here. 248 */ getConfigurationIntent(String transport)249 Intent getConfigurationIntent(String transport); 250 251 /** 252 * Get the destination string supplied by the given transport. Callers must 253 * hold the android.permission.BACKUP permission in order to use this method. 254 * 255 * @param transport The name of the transport to query. 256 * @return A string describing the current backup destination. This string is used 257 * verbatim by the Settings UI as the summary text of the "configure..." item. 258 */ getDestinationString(String transport)259 String getDestinationString(String transport); 260 261 /** 262 * Get the manage-data UI intent, if any, from the given transport. Callers must 263 * hold the android.permission.BACKUP permission in order to use this method. 264 */ getDataManagementIntent(String transport)265 Intent getDataManagementIntent(String transport); 266 267 /** 268 * Get the manage-data menu label, if any, from the given transport. Callers must 269 * hold the android.permission.BACKUP permission in order to use this method. 270 */ getDataManagementLabel(String transport)271 String getDataManagementLabel(String transport); 272 273 /** 274 * Begin a restore session. Either or both of packageName and transportID 275 * may be null. If packageName is non-null, then only the given package will be 276 * considered for restore. If transportID is null, then the restore will use 277 * the current active transport. 278 * <p> 279 * This method requires the android.permission.BACKUP permission <i>except</i> 280 * when transportID is null and packageName is the name of the caller's own 281 * package. In that case, the restore session returned is suitable for supporting 282 * the BackupManager.requestRestore() functionality via RestoreSession.restorePackage() 283 * without requiring the app to hold any special permission. 284 * 285 * @param packageName The name of the single package for which a restore will 286 * be requested. May be null, in which case all packages in the restore 287 * set can be restored. 288 * @param transportID The name of the transport to use for the restore operation. 289 * May be null, in which case the current active transport is used. 290 * @return An interface to the restore session, or null on error. 291 */ beginRestoreSession(String packageName, String transportID)292 IRestoreSession beginRestoreSession(String packageName, String transportID); 293 294 /** 295 * Notify the backup manager that a BackupAgent has completed the operation 296 * corresponding to the given token. 297 * 298 * @param token The transaction token passed to the BackupAgent method being 299 * invoked. 300 * @param result In the case of a full backup measure operation, the estimated 301 * total file size that would result from the operation. Unused in all other 302 * cases. 303 * {@hide} 304 */ opComplete(int token, long result)305 void opComplete(int token, long result); 306 307 /** 308 * Make the device's backup and restore machinery (in)active. When it is inactive, 309 * the device will not perform any backup operations, nor will it deliver data for 310 * restore, although clients can still safely call BackupManager methods. 311 * 312 * @param whichUser User handle of the defined user whose backup active state 313 * is to be adjusted. 314 * @param makeActive {@code true} when backup services are to be made active; 315 * {@code false} otherwise. 316 */ setBackupServiceActive(int whichUser, boolean makeActive)317 void setBackupServiceActive(int whichUser, boolean makeActive); 318 319 /** 320 * Queries the activity status of backup service as set by {@link #setBackupServiceActive}. 321 * @param whichUser User handle of the defined user whose backup active state 322 * is being queried. 323 */ isBackupServiceActive(int whichUser)324 boolean isBackupServiceActive(int whichUser); 325 326 /** 327 * Ask the framework which dataset, if any, the given package's data would be 328 * restored from if we were to install it right now. 329 * 330 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 331 * 332 * @param packageName The name of the package whose most-suitable dataset we 333 * wish to look up 334 * @return The dataset token from which a restore should be attempted, or zero if 335 * no suitable data is available. 336 */ getAvailableRestoreToken(String packageName)337 long getAvailableRestoreToken(String packageName); 338 339 /** 340 * Ask the framework whether this app is eligible for backup. 341 * 342 * <p>Callers must hold the android.permission.BACKUP permission to use this method. 343 * 344 * @param packageName The name of the package. 345 * @return Whether this app is eligible for backup. 346 */ isAppEligibleForBackup(String packageName)347 boolean isAppEligibleForBackup(String packageName); 348 349 /** 350 * Request an immediate backup, providing an observer to which results of the backup operation 351 * will be published. The Android backup system will decide for each package whether it will 352 * be full app data backup or key/value-pair-based backup. 353 * 354 * <p>If this method returns zero (meaning success), the OS will attempt to backup all provided 355 * packages using the remote transport. 356 * 357 * @param observer The {@link BackupObserver} to receive callbacks during the backup 358 * operation. 359 * 360 * @return Zero on success; nonzero on error. 361 */ requestBackup(in String[] packages, IBackupObserver observer)362 int requestBackup(in String[] packages, IBackupObserver observer); 363 } 364