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