IBackupManager.aidl revision 9ff53a7100b1a40f5d2df3eb19a2f3f2fff39a46
12c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer/* 22c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Copyright (C) 2009 The Android Open Source Project 32c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 42c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Licensed under the Apache License, Version 2.0 (the "License"); 52c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * you may not use this file except in compliance with the License. 62c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * You may obtain a copy of the License at 72c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 82c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * http://www.apache.org/licenses/LICENSE-2.0 92c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 102c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Unless required by applicable law or agreed to in writing, software 112c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * distributed under the License is distributed on an "AS IS" BASIS, 122c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 132c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * See the License for the specific language governing permissions and 142c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * limitations under the License. 152c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 162c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 172c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerpackage android.app.backup; 182c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 192c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerimport android.app.backup.IFullBackupRestoreObserver; 202c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerimport android.app.backup.IRestoreSession; 212c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerimport android.os.ParcelFileDescriptor; 222c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerimport android.content.Intent; 232c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 242c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer/** 252c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Direct interface to the Backup Manager Service that applications invoke on. The only 262c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * operation currently needed is a simple notification that the app has made changes to 272c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * data it wishes to back up, so the system should run a backup pass. 282c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 292c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Apps will use the {@link android.app.backup.BackupManager} class rather than going through 302c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * this Binder interface directly. 312c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 322c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * {@hide} 332c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 342c9394097967d01f79f76148bbaebed5324a529fRakesh Iyerinterface IBackupManager { 352c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 362c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Tell the system service that the caller has made changes to its 372c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * data, and therefore needs to undergo an incremental backup pass. 382c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 392c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Any application can invoke this method for its own package, but 402c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * only callers who hold the android.permission.BACKUP permission 412c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * may invoke it for arbitrary packages. 422c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 432c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void dataChanged(String packageName); 442c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 452c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 462c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Erase all backed-up data for the given package from the given storage 472c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * destination. 482c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 492c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Any application can invoke this method for its own package, but 502c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * only callers who hold the android.permission.BACKUP permission 512c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * may invoke it for arbitrary packages. 522c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 532c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void clearBackupData(String transportName, String packageName); 542c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 552c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 562c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Notifies the Backup Manager Service that an agent has become available. This 572c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * method is only invoked by the Activity Manager. 582c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 592c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void agentConnected(String packageName, IBinder agent); 602c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 612c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 622c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Notify the Backup Manager Service that an agent has unexpectedly gone away. 632c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * This method is only invoked by the Activity Manager. 642c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 652c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void agentDisconnected(String packageName); 662c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 672c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 682c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Notify the Backup Manager Service that an application being installed will 692c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * need a data-restore pass. This method is only invoked by the Package Manager. 702c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 712c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void restoreAtInstall(String packageName, int token); 722c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 732c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 742c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Enable/disable the backup service entirely. When disabled, no backup 752c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * or restore operations will take place. Data-changed notifications will 762c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * still be observed and collected, however, so that changes made while the 772c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * mechanism was disabled will still be backed up properly if it is enabled 782c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * at some point in the future. 792c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 802c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 812c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 822c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void setBackupEnabled(boolean isEnabled); 832c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 842c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 852c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Enable/disable automatic restore of application data at install time. When 862c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * enabled, installation of any package will involve the Backup Manager. If data 872c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * exists for the newly-installed package, either from the device's current [enabled] 882c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * backup dataset or from the restore set used in the last wholesale restore operation, 892c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * that data will be supplied to the new package's restore agent before the package 902c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * is made generally available for launch. 912c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 922c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 932c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 942c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * @param doAutoRestore When true, enables the automatic app-data restore facility. When 952c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * false, this facility will be disabled. 962c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 972c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void setAutoRestore(boolean doAutoRestore); 982c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 992c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 1002c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Indicate that any necessary one-time provisioning has occurred. 1012c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 1022c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 1032c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 1042c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer void setBackupProvisioned(boolean isProvisioned); 1052c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 1062c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 1072c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Report whether the backup mechanism is currently enabled. 1082c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 1092c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 1102c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 1112c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer boolean isBackupEnabled(); 1122c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 1132c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 1142c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Set the device's backup password. Returns {@code true} if the password was set 1152c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * successfully, {@code false} otherwise. Typically a failure means that an incorrect 1162c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * current password was supplied. 1172c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 1182c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 1192c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 1202c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer boolean setBackupPassword(in String currentPw, in String newPw); 1212c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 1222c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 1232c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Reports whether a backup password is currently set. If not, then a null or empty 1242c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * "current password" argument should be passed to setBackupPassword(). 1252c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 1262c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 1272c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 1282c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer boolean hasBackupPassword(); 1292c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 1302c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer /** 1312c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * Schedule an immediate backup attempt for all pending updates. This is 1322c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * primarily intended for transports to use when they detect a suitable 1332c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * opportunity for doing a backup pass. If there are no pending updates to 1342c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * be sent, no action will be taken. Even if some updates are pending, the 1352c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * transport will still be asked to confirm via the usual requestBackupTime() 1362c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * method. 1372c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * 1382c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer * <p>Callers must hold the android.permission.BACKUP permission to use this method. 1392c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer */ 1402c9394097967d01f79f76148bbaebed5324a529fRakesh Iyer 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 250 String getDestinationString(String transport); 251 252 /** 253 * Begin a restore session. Either or both of packageName and transportID 254 * may be null. If packageName is non-null, then only the given package will be 255 * considered for restore. If transportID is null, then the restore will use 256 * the current active transport. 257 * <p> 258 * This method requires the android.permission.BACKUP permission <i>except</i> 259 * when transportID is null and packageName is the name of the caller's own 260 * package. In that case, the restore session returned is suitable for supporting 261 * the BackupManager.requestRestore() functionality via RestoreSession.restorePackage() 262 * without requiring the app to hold any special permission. 263 * 264 * @param packageName The name of the single package for which a restore will 265 * be requested. May be null, in which case all packages in the restore 266 * set can be restored. 267 * @param transportID The name of the transport to use for the restore operation. 268 * May be null, in which case the current active transport is used. 269 * @return An interface to the restore session, or null on error. 270 */ 271 IRestoreSession beginRestoreSession(String packageName, String transportID); 272 273 /** 274 * Notify the backup manager that a BackupAgent has completed the operation 275 * corresponding to the given token. 276 * 277 * @param token The transaction token passed to a BackupAgent's doBackup() or 278 * doRestore() method. 279 * {@hide} 280 */ 281 void opComplete(int token); 282} 283