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