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 com.android.internal.backup; 18 19 import android.app.backup.IBackupManagerMonitor; 20 import android.app.backup.RestoreDescription; 21 import android.app.backup.RestoreSet; 22 import android.content.Intent; 23 import android.content.pm.PackageInfo; 24 import android.os.ParcelFileDescriptor; 25 26 import com.android.internal.backup.ITransportStatusCallback; 27 import com.android.internal.infra.AndroidFuture; 28 29 /** {@hide} */ 30 oneway interface IBackupTransport { 31 /** 32 * Ask the transport for the String name under which it should be registered. This will 33 * typically be its host service's component name, but need not be. 34 * 35 * @param resultFuture an {@link AndroidFuture} that is completed with the {@code String} name 36 * of the transport. 37 */ name(in AndroidFuture<String> result)38 void name(in AndroidFuture<String> result); 39 40 /** 41 * Ask the transport for an Intent that can be used to launch any internal 42 * configuration Activity that it wishes to present. For example, the transport 43 * may offer a UI for allowing the user to supply login credentials for the 44 * transport's off-device backend. 45 * 46 * If the transport does not supply any user-facing configuration UI, it should 47 * return null from this method. 48 * 49 * @param resultFuture an {@link AndroidFuture} that is completed with an {@code Intent} that 50 * can be passed to Context.startActivity() in order to launch the transport's 51 * configuration UI. This future will complete with null if the transport does not 52 * offer any user-facing configuration UI. 53 */ configurationIntent(in AndroidFuture<Intent> resultFuture)54 void configurationIntent(in AndroidFuture<Intent> resultFuture); 55 56 /** 57 * Ask the transport for a one-line string that can be shown to the user that 58 * describes the current backend destination. For example, a transport that 59 * can potentially associate backup data with arbitrary user accounts should 60 * include the name of the currently-active account here. 61 * 62 * @param resultFuture an {@link AndroidFuture} that is completed with a {@code String} 63 * describing the destination to which the transport is currently sending data. 64 */ currentDestinationString(in AndroidFuture<String> resultFuture)65 void currentDestinationString(in AndroidFuture<String> resultFuture); 66 67 /** 68 * Ask the transport for an Intent that can be used to launch a more detailed 69 * secondary data management activity. For example, the configuration intent might 70 * be one for allowing the user to select which account they wish to associate 71 * their backups with, and the management intent might be one which presents a 72 * UI for managing the data on the backend. 73 * 74 * <p>In the Settings UI, the configuration intent will typically be invoked 75 * when the user taps on the preferences item labeled with the current 76 * destination string, and the management intent will be placed in an overflow 77 * menu labelled with the management label string. 78 * 79 * <p>If the transport does not supply any user-facing data management 80 * UI, then it should return {@code null} from this method. 81 * 82 * @param resultFuture an {@link AndroidFuture} that is completed with an {@code Intent} that 83 * can be passed to Context.startActivity() in order to launch the transport's 84 * data-management UI. The callback will supply {@code null} if the transport does not 85 * offer any user-facing data management UI. 86 */ dataManagementIntent(in AndroidFuture<Intent> resultFuture)87 void dataManagementIntent(in AndroidFuture<Intent> resultFuture); 88 89 /** 90 * Ask the transport for a short {@link CharSequence} that can be shown to the user as the label 91 * on an overflow menu item used to invoke the data management UI. 92 * 93 * @param resultFuture an {@link AndroidFuture} that is completed with a {@code CharSequence} 94 * to be used as the label for the transport's data management affordance. If the 95 * transport supplies a data management Intent via {@link #dataManagementIntent}, 96 * this method must not return {@code null}. 97 */ dataManagementIntentLabel(in AndroidFuture<CharSequence> resultFuture)98 void dataManagementIntentLabel(in AndroidFuture<CharSequence> resultFuture); 99 100 /** 101 * Ask the transport where, on local device storage, to keep backup state blobs. 102 * This is per-transport so that mock transports used for testing can coexist with 103 * "live" backup services without interfering with the live bookkeeping. The 104 * returned string should be a name that is expected to be unambiguous among all 105 * available backup transports; the name of the class implementing the transport 106 * is a good choice. This MUST be constant. 107 * 108 * @param resultFuture an {@link AndroidFuture} that is completed with a unique {@code String} 109 * name, suitable for use as a file or directory name, that the Backup Manager could use 110 * to disambiguate state files associated with different backup transports. 111 */ transportDirName(in AndroidFuture<String> resultFuture)112 void transportDirName(in AndroidFuture<String> resultFuture); 113 114 /** 115 * Verify that this is a suitable time for a backup pass. This should return zero 116 * if a backup is reasonable right now, some positive value otherwise. This method 117 * will be called outside of the {@link #startSession}/{@link #endSession} pair. 118 * 119 * <p>If this is not a suitable time for a backup, the transport should return a 120 * backoff delay, in milliseconds, after which the Backup Manager should try again. 121 * 122 * @param resultFuture an {@link AndroidFuture} that is completed with {@code int}: zero if 123 * this is a suitable time for a backup pass, or a positive time delay in milliseconds 124 * to suggest deferring the backup pass for a while. 125 */ requestBackupTime(in AndroidFuture<long> resultFuture)126 void requestBackupTime(in AndroidFuture<long> resultFuture); 127 128 /** 129 * Initialize the server side storage for this device, erasing all stored data. 130 * The transport may send the request immediately, or may buffer it. After 131 * this is called, {@link #finishBackup} must be called to ensure the request 132 * is sent and received successfully. 133 * 134 * @param callback a callback that is completed with a {@code int} which is one 135 * of {@link BackupConstants#TRANSPORT_OK} (OK so far) or 136 * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure). 137 */ initializeDevice(in ITransportStatusCallback callback)138 void initializeDevice(in ITransportStatusCallback callback); 139 140 /** 141 * Send one application's data to the backup destination. The transport may send 142 * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 143 * must be called to ensure the data is sent and recorded successfully. 144 * 145 * @param packageInfo The identity of the application whose data is being backed up. 146 * This specifically includes the signature list for the package. 147 * @param inFd Descriptor of file with data that resulted from invoking the application's 148 * BackupService.doBackup() method. This may be a pipe rather than a file on 149 * persistent media, so it may not be seekable. 150 * @param flags Some of {@link BackupTransport#FLAG_USER_INITIATED}. 151 * @param callback a callback that is completed with a {@code int} which is one 152 * of {@link BackupConstants#TRANSPORT_OK}(OK so far), {@link BackupConstants#TRANSPORT_ERROR} 153 * (on network error or other failure), or {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} 154 * (if the backend dataset has become lost due to inactive expiry or some other reason and 155 * needs re-initializing). 156 */ performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd, int flags, in ITransportStatusCallback callback)157 void performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd, int flags, 158 in ITransportStatusCallback callback); 159 160 /** 161 * Erase the give application's data from the backup destination. This clears 162 * out the given package's data from the current backup set, making it as though 163 * the app had never yet been backed up. After this is called, {@link finishBackup} 164 * must be called to ensure that the operation is recorded successfully. 165 * 166 * @param callback a callback that is completed with the same error codes as 167 * {@link #performBackup}. 168 */ clearBackupData(in PackageInfo packageInfo, in ITransportStatusCallback callback)169 void clearBackupData(in PackageInfo packageInfo, in ITransportStatusCallback callback); 170 171 /** 172 * Finish sending application data to the backup destination. This must be 173 * called after {@link #performBackup} or {@link clearBackupData} to ensure that 174 * all data is sent. Only when this method returns true can a backup be assumed 175 * to have succeeded. 176 * 177 * @param callback a callback that is completed with the same error codes as 178 * {@link #performBackup}. 179 */ finishBackup(in ITransportStatusCallback callback)180 void finishBackup(in ITransportStatusCallback callback); 181 182 /** 183 * Get the set of all backups currently available over this transport. 184 * 185 * @param resultFuture an {@link AndroidFuture} that is completed with {@code List<RestoreSet>}: 186 * the descriptions of a set of restore images available for this device, or null if an 187 * error occurred (the attempt should be rescheduled). 188 **/ getAvailableRestoreSets(in AndroidFuture<List<RestoreSet>> resultFuture)189 void getAvailableRestoreSets(in AndroidFuture<List<RestoreSet>> resultFuture); 190 191 /** 192 * Get the identifying token of the backup set currently being stored from 193 * this device. This is used in the case of applications wishing to restore 194 * their last-known-good data. 195 * 196 * @param resultFuture an {@link AndroidFuture} that is completed with a {@code long}: a token 197 * that can be passed to {@link #startRestore}, or 0 if there is no backup set available 198 * corresponding to the current device state. 199 */ getCurrentRestoreSet(in AndroidFuture<long> resultFuture)200 void getCurrentRestoreSet(in AndroidFuture<long> resultFuture); 201 202 /** 203 * Start restoring application data from backup. After calling this function, 204 * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 205 * to walk through the actual application data. 206 * 207 * @param token A backup token as returned by {@link #getAvailableRestoreSets} 208 * or {@link #getCurrentRestoreSet}. 209 * @param packages List of applications to restore (if data is available). 210 * Application data will be restored in the order given. 211 * @param callback a callback that is completed with one of 212 * {@link BackupConstants#TRANSPORT_OK} (OK so far, call {@link #nextRestorePackage}) or 213 * {@link BackupConstants#TRANSPORT_ERROR} (an error occurred, the restore should be aborted 214 * and rescheduled). 215 */ startRestore(long token, in PackageInfo[] packages, in ITransportStatusCallback callback)216 void startRestore(long token, in PackageInfo[] packages, in ITransportStatusCallback callback); 217 218 /** 219 * Get the package name of the next application with data in the backup store, plus 220 * a description of the structure of the restored archive: either TYPE_KEY_VALUE for 221 * an original-API key/value dataset, or TYPE_FULL_STREAM for a tarball-type archive stream. 222 * 223 * <p>If the package name in the returned RestoreDescription object is the singleton 224 * {@link RestoreDescription#NO_MORE_PACKAGES}, it indicates that no further data is available 225 * in the current restore session: all packages described in startRestore() have been 226 * processed. 227 * 228 * <p>If this method returns {@code null}, it means that a transport-level error has 229 * occurred and the entire restore operation should be abandoned. 230 * 231 * @param resultFuture an {@link AndroidFuture} that is completed with a 232 * {@link RestoreDescription} object containing the name of one of the packages supplied to 233 * {@link #startRestore} plus an indicator of the data type of that restore data; or 234 * {@link RestoreDescription#NO_MORE_PACKAGES} to indicate that no more packages can be 235 * restored in this session; or {@code null} to indicate a transport-level error. 236 */ nextRestorePackage(in AndroidFuture<RestoreDescription> resultFuture)237 void nextRestorePackage(in AndroidFuture<RestoreDescription> resultFuture); 238 239 /** 240 * Get the data for the application returned by {@link #nextRestorePackage}. 241 * @param data An open, writable file into which the backup data should be stored. 242 * 243 * @param callback a callback that is completed with the same error codes as 244 * {@link #startRestore}. 245 */ getRestoreData(in ParcelFileDescriptor outFd, in ITransportStatusCallback callback)246 void getRestoreData(in ParcelFileDescriptor outFd, in ITransportStatusCallback callback); 247 248 /** 249 * End a restore session (aborting any in-process data transfer as necessary), 250 * freeing any resources and connections used during the restore process. 251 * 252 * @param callback a callback to signal that restore has been finished on transport side. 253 */ finishRestore(in ITransportStatusCallback callback)254 void finishRestore(in ITransportStatusCallback callback); 255 256 // full backup stuff 257 258 /** 259 * Verify that this is a suitable time for a full-data backup pass. 260 * 261 * @param resultFuture an {@link AndroidFuture} that is completed with {@code long}: 0 if this 262 * is a suitable time for a backup pass, or a positive time delay in milliseconds to 263 * suggest deferring the backup pass for a while. 264 */ requestFullBackupTime(in AndroidFuture<long> resultFuture)265 void requestFullBackupTime(in AndroidFuture<long> resultFuture); 266 267 /** 268 * Begin the process of sending an application's full-data archive to the backend. 269 * 270 * @param targetPackage The package whose data is to follow. 271 * @param socket The socket file descriptor through which the data will be provided. 272 * @param flags {@link BackupTransport#FLAG_USER_INITIATED} or 0. 273 * @param callback callback to return a {@code int} which is one of: 274 * {@link BackupTransport#TRANSPORT_PACKAGE_REJECTED} to indicate that the stated 275 * application is not to be backed up; {@link BackupTransport#TRANSPORT_OK} to indicate 276 * that the OS may proceed with delivering backup data; 277 * {@link BackupTransport#TRANSPORT_ERROR to indicate a fatal error condition that 278 * precludes performing a backup at this time. 279 */ performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket, int flags, in ITransportStatusCallback callback)280 void performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket, int flags, 281 in ITransportStatusCallback callback); 282 283 /** 284 * Called after {@link #performFullBackup} to make sure that the transport is willing to 285 * handle a full-data backup operation of the specified size on the current package. 286 * 287 * @param size The estimated size of the full-data payload for this app. This includes 288 * manifest and archive format overhead, but is not guaranteed to be precise. 289 * @param callback a callback that is completed with a {@code int} which is 290 * one of: {@link BackupTransport#TRANSPORT_OK} if the platform is to proceed with the 291 * full-data {@link BackupTransport#TRANSPORT_PACKAGE_REJECTED} if the proposed payload 292 * size is backup, too large for the transport to handle, or 293 * {@link BackupTransport#TRANSPORT_ERROR} to indicate a fatal error condition that 294 * means the platform cannot perform a backup at this time. 295 */ checkFullBackupSize(long size, in ITransportStatusCallback callback)296 void checkFullBackupSize(long size, in ITransportStatusCallback callback); 297 298 /** 299 * Tells the transport to read {@code numBytes} bytes of data from the socket file 300 * descriptor provided in the {@link #performFullBackup(PackageInfo, ParcelFileDescriptor)} 301 * call, and deliver those bytes to the datastore. 302 * 303 * @param numBytes The number of bytes of tarball data available to be read from the 304 * socket. 305 * @param callback a callback that is completed with a {@code int} which is 306 * one of: {@link BackupTransport#TRANSPORT_OK} on successful processing of the data, 307 * {@link BackupTransport#TRANSPORT_ERROR} to indicate a fatal error situation. If an 308 * error is returned, the system will call finishBackup() and stop attempting backups 309 * until after a backoff and retry interval. 310 */ sendBackupData(int numBytes, in ITransportStatusCallback callback)311 void sendBackupData(int numBytes, in ITransportStatusCallback callback); 312 313 /** 314 * Tells the transport to cancel the currently-ongoing full backup operation. 315 * 316 * @param callback a callback to indicate that transport has cancelled the operation, 317 * does not return any value (see {@link ITransportCallback#onVoidReceived}). 318 */ cancelFullBackup(in ITransportStatusCallback callback)319 void cancelFullBackup(in ITransportStatusCallback callback); 320 321 /** 322 * Ask the transport whether this app is eligible for backup. 323 * 324 * @param targetPackage The identity of the application. 325 * @param isFullBackup If set, transport should check if app is eligible for full data backup, 326 * otherwise to check if eligible for key-value backup. 327 * @param resultFuture an {@link AndroidFuture} that is completed with a {@code boolean} 328 * indicating whether this app is eligible for backup. 329 */ isAppEligibleForBackup(in PackageInfo targetPackage, boolean isFullBackup, in AndroidFuture<boolean> resultFuture)330 void isAppEligibleForBackup(in PackageInfo targetPackage, boolean isFullBackup, 331 in AndroidFuture<boolean> resultFuture); 332 333 /** 334 * Ask the transport about current quota for backup size of the package. 335 * 336 * @param packageName ID of package to provide the quota. 337 * @param isFullBackup If set, transport should return limit for full data backup, otherwise 338 * for key-value backup. 339 * @param resultFuture an {@link AndroidFuture} that is completed with a {@code long}: current 340 * limit on full data backup size in bytes. 341 */ getBackupQuota(String packageName, boolean isFullBackup, in AndroidFuture<long> resultFuture)342 void getBackupQuota(String packageName, boolean isFullBackup, 343 in AndroidFuture<long> resultFuture); 344 345 // full restore stuff 346 347 /** 348 * Ask the transport to provide data for the "current" package being restored. This 349 * is the package that was just reported by {@link #nextRestorePackage()} as having 350 * {@link RestoreDescription#TYPE_FULL_STREAM} data. 351 * 352 * The transport writes some data to the socket supplied to this call, and returns 353 * the number of bytes written. The system will then read that many bytes and 354 * stream them to the application's agent for restore, then will call this method again 355 * to receive the next chunk of the archive. This sequence will be repeated until the 356 * transport returns zero indicating that all of the package's data has been delivered 357 * (or returns a negative value indicating some sort of hard error condition at the 358 * transport level). 359 * 360 * <p>After this method returns zero, the system will then call 361 * {@link #getNextFullRestorePackage()} to begin the restore process for the next 362 * application, and the sequence begins again. 363 * 364 * <p>The transport should always close this socket when returning from this method. 365 * Do not cache this socket across multiple calls or you may leak file descriptors. 366 * 367 * @param socket The file descriptor that the transport will use for delivering the 368 * streamed archive. The transport must close this socket in all cases when returning 369 * from this method. 370 * @param callback a callback that is completed with an {@code int}: 0 when 371 * no more data for the current package is available. A positive value indicates the 372 * presence of that many bytes to be delivered to the app. Any negative return value is 373 * treated as equivalent to {@link BackupTransport#TRANSPORT_ERROR}, indicating a fatal error 374 * condition that precludes further restore operations on the current dataset. 375 */ getNextFullRestoreDataChunk(in ParcelFileDescriptor socket, in ITransportStatusCallback callback)376 void getNextFullRestoreDataChunk(in ParcelFileDescriptor socket, 377 in ITransportStatusCallback callback); 378 379 /** 380 * If the OS encounters an error while processing {@link RestoreDescription#TYPE_FULL_STREAM} 381 * data for restore, it will invoke this method to tell the transport that it should 382 * abandon the data download for the current package. The OS will then either call 383 * {@link #nextRestorePackage()} again to move on to restoring the next package in the 384 * set being iterated over, or will call {@link #finishRestore()} to shut down the restore 385 * operation. 386 * 387 * @param callback a callback that is completed with {@code int}, which is 388 * one of: {@link #TRANSPORT_OK} if the transport was successful in shutting down the current 389 * stream cleanly, or {@link #TRANSPORT_ERROR} to indicate a serious transport-level failure. 390 * If the transport reports an error here, the entire restore operation will immediately be 391 * finished with no further attempts to restore app data. 392 */ abortFullRestore(in ITransportStatusCallback callback)393 void abortFullRestore(in ITransportStatusCallback callback); 394 395 /** 396 * @param resultFuture an {@link AndroidFuture} that is completed with an {@code int}: flags 397 * with additional information about the transport, which is accessible to the 398 * {@link android.app.backup.BackupAgent}. This allows the agent to decide what to backup or 399 * restore based on properties of the transport. 400 * 401 * <p>For supported flags see {@link android.app.backup.BackupAgent}. 402 */ getTransportFlags(in AndroidFuture<int> resultFuture)403 void getTransportFlags(in AndroidFuture<int> resultFuture); 404 405 /** 406 * Ask the transport for a {@link IBackupManagerMonitor} instance which will be used by the 407 * framework to report logging events back to the transport. 408 * 409 * Backups requested from outside the framework may pass in a monitor with the request, 410 * however backups initiated by the framework will call this method to retrieve one. 411 */ getBackupManagerMonitor(in AndroidFuture<IBackupManagerMonitor> resultFuture)412 void getBackupManagerMonitor(in AndroidFuture<IBackupManagerMonitor> resultFuture); 413 } 414