Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 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 | |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 19 | import android.app.backup.RestoreDescription; |
Christopher Tate | 4528186 | 2010-03-05 15:46:30 -0800 | [diff] [blame] | 20 | import android.app.backup.RestoreSet; |
Chris Tate | a8ddef3 | 2010-11-10 11:53:26 -0800 | [diff] [blame] | 21 | import android.content.Intent; |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 22 | import android.content.pm.PackageInfo; |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 23 | import android.os.ParcelFileDescriptor; |
| 24 | |
Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 25 | /** {@hide} */ |
| 26 | interface IBackupTransport { |
Christopher Tate | cefba58 | 2013-11-14 18:10:35 -0800 | [diff] [blame] | 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 | */ |
| 31 | String name(); |
| 32 | |
Chris Tate | a8ddef3 | 2010-11-10 11:53:26 -0800 | [diff] [blame] | 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 | */ |
| 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 | */ |
| 57 | String currentDestinationString(); |
| 58 | |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 59 | /** |
Christopher Tate | 9679410 | 2014-07-27 20:21:55 -0700 | [diff] [blame] | 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 | */ |
| 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 | */ |
| 89 | String dataManagementLabel(); |
| 90 | |
| 91 | /** |
Christopher Tate | 5cb400b | 2009-06-25 16:03:14 -0700 | [diff] [blame] | 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 |
Bernardo Rufino | ab95333 | 2017-11-22 22:10:32 +0000 | [diff] [blame] | 97 | * is a good choice. This MUST be constant. |
Christopher Tate | 5cb400b | 2009-06-25 16:03:14 -0700 | [diff] [blame] | 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 | */ |
| 103 | String transportDirName(); |
| 104 | |
| 105 | /** |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 106 | * Verify that this is a suitable time for a backup pass. This should return zero |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 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. |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 109 | * |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 110 | * <p>If this is not a suitable time for a backup, the transport should return a |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 111 | * backoff delay, in milliseconds, after which the Backup Manager should try again. |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 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. |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 115 | */ |
| 116 | long requestBackupTime(); |
| 117 | |
| 118 | /** |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 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 | */ |
| 127 | int initializeDevice(); |
| 128 | |
| 129 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 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. |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 133 | * |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 134 | * @param packageInfo The identity of the application whose data is being backed up. |
| 135 | * This specifically includes the signature list for the package. |
Sergey Poromov | fe06bf6 | 2015-12-15 16:26:23 +0100 | [diff] [blame] | 136 | * @param inFd Descriptor of file with data that resulted from invoking the application's |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 137 | * BackupService.doBackup() method. This may be a pipe rather than a file on |
| 138 | * persistent media, so it may not be seekable. |
Sergey Poromov | fe06bf6 | 2015-12-15 16:26:23 +0100 | [diff] [blame] | 139 | * @param flags Some of {@link BackupTransport#FLAG_USER_INITIATED}. |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 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) |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 144 | */ |
Sergey Poromov | fe06bf6 | 2015-12-15 16:26:23 +0100 | [diff] [blame] | 145 | int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd, int flags); |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 146 | |
| 147 | /** |
Christopher Tate | ee0e78a | 2009-07-02 11:17:03 -0700 | [diff] [blame] | 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. |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 152 | * |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 153 | * @return the same error codes as {@link #performBackup}. |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 154 | */ |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 155 | int clearBackupData(in PackageInfo packageInfo); |
Christopher Tate | ee0e78a | 2009-07-02 11:17:03 -0700 | [diff] [blame] | 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 | * |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 163 | * @return the same error codes as {@link #performBackup}. |
Christopher Tate | ee0e78a | 2009-07-02 11:17:03 -0700 | [diff] [blame] | 164 | */ |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 165 | int finishBackup(); |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 166 | |
| 167 | /** |
Christopher Tate | 50c6df0 | 2010-01-29 12:48:20 -0800 | [diff] [blame] | 168 | * Get the set of all backups currently available over this transport. |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 169 | * |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 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). |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 172 | **/ |
Christopher Tate | 9b3905c | 2009-06-08 15:24:01 -0700 | [diff] [blame] | 173 | RestoreSet[] getAvailableRestoreSets(); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 174 | |
| 175 | /** |
Christopher Tate | 50c6df0 | 2010-01-29 12:48:20 -0800 | [diff] [blame] | 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 | */ |
| 183 | long getCurrentRestoreSet(); |
| 184 | |
| 185 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 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. |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 189 | * |
Christopher Tate | 50c6df0 | 2010-01-29 12:48:20 -0800 | [diff] [blame] | 190 | * @param token A backup token as returned by {@link #getAvailableRestoreSets} |
| 191 | * or {@link #getCurrentRestoreSet}. |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 192 | * @param packages List of applications to restore (if data is available). |
| 193 | * Application data will be restored in the order given. |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 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). |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 197 | */ |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 198 | int startRestore(long token, in PackageInfo[] packages); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 199 | |
| 200 | /** |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 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. |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 218 | */ |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 219 | RestoreDescription nextRestorePackage(); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 220 | |
| 221 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 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. |
Christopher Tate | 74318c9 | 2014-05-15 19:03:44 -0700 | [diff] [blame] | 224 | * @return the same error codes as {@link #startRestore}. |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 225 | */ |
Dan Egnor | 0144516 | 2009-09-21 17:04:05 -0700 | [diff] [blame] | 226 | int getRestoreData(in ParcelFileDescriptor outFd); |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 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 | */ |
| 232 | void finishRestore(); |
Christopher Tate | 9ff53a7 | 2014-06-03 17:20:07 -0700 | [diff] [blame] | 233 | |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 234 | // full backup stuff |
| 235 | |
Christopher Tate | 9ff53a7 | 2014-06-03 17:20:07 -0700 | [diff] [blame] | 236 | long requestFullBackupTime(); |
Sergey Poromov | fe06bf6 | 2015-12-15 16:26:23 +0100 | [diff] [blame] | 237 | int performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket, int flags); |
Christopher Tate | 11ae768 | 2015-03-24 18:48:10 -0700 | [diff] [blame] | 238 | int checkFullBackupSize(long size); |
Christopher Tate | 9ff53a7 | 2014-06-03 17:20:07 -0700 | [diff] [blame] | 239 | int sendBackupData(int numBytes); |
Christopher Tate | bf1a4a8 | 2014-08-08 15:05:48 -0700 | [diff] [blame] | 240 | void cancelFullBackup(); |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 241 | |
Sergey Poromov | 9448196 | 2016-01-07 18:25:35 +0100 | [diff] [blame] | 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 | */ |
| 250 | boolean isAppEligibleForBackup(in PackageInfo targetPackage, boolean isFullBackup); |
| 251 | |
Sergey Poromov | 872d3b6 | 2016-01-12 15:48:08 +0100 | [diff] [blame] | 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 | */ |
| 260 | long getBackupQuota(String packageName, boolean isFullBackup); |
| 261 | |
Christopher Tate | 6a49dd0 | 2014-06-16 18:49:25 -0700 | [diff] [blame] | 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 | */ |
| 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 | */ |
| 308 | int abortFullRestore(); |
Robert Berry | 39194c0 | 2018-01-11 13:50:56 +0000 | [diff] [blame] | 309 | |
| 310 | /** |
| 311 | * Returns flags with additional information about the transport, which is accessible to the |
| 312 | * {@link android.app.backup.BackupAgent}. This allows the agent to decide what to backup or |
| 313 | * restore based on properties of the transport. |
| 314 | * |
| 315 | * <p>For supported flags see {@link android.app.backup.BackupAgent}. |
| 316 | */ |
| 317 | int getTransportFlags(); |
Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 318 | } |