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 data The data stream 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 wipeAllFirst When true, <i>all</i> backed-up data for the current device/account 140 * will be erased prior to the storage of the data provided here. The purpose of this 141 * is to provide a guarantee that no stale data exists in the restore set when the 142 * device begins providing backups. 143 * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far), 144 * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or 145 * {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has 146 * become lost due to inactive expiry or some other reason and needs re-initializing) 147 */ performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd)148 int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 149 150 /** 151 * Erase the give application's data from the backup destination. This clears 152 * out the given package's data from the current backup set, making it as though 153 * the app had never yet been backed up. After this is called, {@link finishBackup} 154 * must be called to ensure that the operation is recorded successfully. 155 * 156 * @return the same error codes as {@link #performBackup}. 157 */ clearBackupData(in PackageInfo packageInfo)158 int clearBackupData(in PackageInfo packageInfo); 159 160 /** 161 * Finish sending application data to the backup destination. This must be 162 * called after {@link #performBackup} or {@link clearBackupData} to ensure that 163 * all data is sent. Only when this method returns true can a backup be assumed 164 * to have succeeded. 165 * 166 * @return the same error codes as {@link #performBackup}. 167 */ finishBackup()168 int finishBackup(); 169 170 /** 171 * Get the set of all backups currently available over this transport. 172 * 173 * @return Descriptions of the set of restore images available for this device, 174 * or null if an error occurred (the attempt should be rescheduled). 175 **/ getAvailableRestoreSets()176 RestoreSet[] getAvailableRestoreSets(); 177 178 /** 179 * Get the identifying token of the backup set currently being stored from 180 * this device. This is used in the case of applications wishing to restore 181 * their last-known-good data. 182 * 183 * @return A token that can be passed to {@link #startRestore}, or 0 if there 184 * is no backup set available corresponding to the current device state. 185 */ getCurrentRestoreSet()186 long getCurrentRestoreSet(); 187 188 /** 189 * Start restoring application data from backup. After calling this function, 190 * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 191 * to walk through the actual application data. 192 * 193 * @param token A backup token as returned by {@link #getAvailableRestoreSets} 194 * or {@link #getCurrentRestoreSet}. 195 * @param packages List of applications to restore (if data is available). 196 * Application data will be restored in the order given. 197 * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call 198 * {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR} 199 * (an error occurred, the restore should be aborted and rescheduled). 200 */ startRestore(long token, in PackageInfo[] packages)201 int startRestore(long token, in PackageInfo[] packages); 202 203 /** 204 * Get the package name of the next application with data in the backup store, plus 205 * a description of the structure of the restored archive: either TYPE_KEY_VALUE for 206 * an original-API key/value dataset, or TYPE_FULL_STREAM for a tarball-type archive stream. 207 * 208 * <p>If the package name in the returned RestoreDescription object is the singleton 209 * {@link RestoreDescription#NO_MORE_PACKAGES}, it indicates that no further data is available 210 * in the current restore session: all packages described in startRestore() have been 211 * processed. 212 * 213 * <p>If this method returns {@code null}, it means that a transport-level error has 214 * occurred and the entire restore operation should be abandoned. 215 * 216 * @return A RestoreDescription object containing the name of one of the packages 217 * supplied to {@link #startRestore} plus an indicator of the data type of that 218 * restore data; or {@link RestoreDescription#NO_MORE_PACKAGES} to indicate that 219 * no more packages can be restored in this session; or {@code null} to indicate 220 * a transport-level error. 221 */ nextRestorePackage()222 RestoreDescription nextRestorePackage(); 223 224 /** 225 * Get the data for the application returned by {@link #nextRestorePackage}. 226 * @param data An open, writable file into which the backup data should be stored. 227 * @return the same error codes as {@link #startRestore}. 228 */ getRestoreData(in ParcelFileDescriptor outFd)229 int getRestoreData(in ParcelFileDescriptor outFd); 230 231 /** 232 * End a restore session (aborting any in-process data transfer as necessary), 233 * freeing any resources and connections used during the restore process. 234 */ finishRestore()235 void finishRestore(); 236 237 // full backup stuff 238 requestFullBackupTime()239 long requestFullBackupTime(); performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket)240 int performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket); checkFullBackupSize(long size)241 int checkFullBackupSize(long size); sendBackupData(int numBytes)242 int sendBackupData(int numBytes); cancelFullBackup()243 void cancelFullBackup(); 244 245 // full restore stuff 246 247 /** 248 * Ask the transport to provide data for the "current" package being restored. This 249 * is the package that was just reported by {@link #nextRestorePackage()} as having 250 * {@link RestoreDescription#TYPE_FULL_STREAM} data. 251 * 252 * The transport writes some data to the socket supplied to this call, and returns 253 * the number of bytes written. The system will then read that many bytes and 254 * stream them to the application's agent for restore, then will call this method again 255 * to receive the next chunk of the archive. This sequence will be repeated until the 256 * transport returns zero indicating that all of the package's data has been delivered 257 * (or returns a negative value indicating some sort of hard error condition at the 258 * transport level). 259 * 260 * <p>After this method returns zero, the system will then call 261 * {@link #getNextFullRestorePackage()} to begin the restore process for the next 262 * application, and the sequence begins again. 263 * 264 * <p>The transport should always close this socket when returning from this method. 265 * Do not cache this socket across multiple calls or you may leak file descriptors. 266 * 267 * @param socket The file descriptor that the transport will use for delivering the 268 * streamed archive. The transport must close this socket in all cases when returning 269 * from this method. 270 * @return 0 when no more data for the current package is available. A positive value 271 * indicates the presence of that many bytes to be delivered to the app. Any negative 272 * return value is treated as equivalent to {@link BackupTransport#TRANSPORT_ERROR}, 273 * indicating a fatal error condition that precludes further restore operations 274 * on the current dataset. 275 */ getNextFullRestoreDataChunk(in ParcelFileDescriptor socket)276 int getNextFullRestoreDataChunk(in ParcelFileDescriptor socket); 277 278 /** 279 * If the OS encounters an error while processing {@link RestoreDescription#TYPE_FULL_STREAM} 280 * data for restore, it will invoke this method to tell the transport that it should 281 * abandon the data download for the current package. The OS will then either call 282 * {@link #nextRestorePackage()} again to move on to restoring the next package in the 283 * set being iterated over, or will call {@link #finishRestore()} to shut down the restore 284 * operation. 285 * 286 * @return {@link #TRANSPORT_OK} if the transport was successful in shutting down the 287 * current stream cleanly, or {@link #TRANSPORT_ERROR} to indicate a serious 288 * transport-level failure. If the transport reports an error here, the entire restore 289 * operation will immediately be finished with no further attempts to restore app data. 290 */ abortFullRestore()291 int abortFullRestore(); 292 293 } 294