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