1 /* 2 * Copyright 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 android.app; 18 19 import android.app.backup.BackupRestoreEventLogger; 20 import android.app.backup.IBackupCallback; 21 import android.app.backup.IBackupManager; 22 import android.os.ParcelFileDescriptor; 23 24 import com.android.internal.infra.AndroidFuture; 25 26 /** 27 * Interface presented by applications being asked to participate in the 28 * backup & restore mechanism. End user code will not typically implement 29 * this interface directly; they subclass BackupAgent instead. 30 * 31 * {@hide} 32 */ 33 oneway interface IBackupAgent { 34 /** 35 * Request that the app perform an incremental backup. 36 * 37 * @param oldState Read-only file containing the description blob of the 38 * app's data state as of the last backup operation's completion. 39 * This file is empty or invalid when a full backup is being 40 * requested. 41 * 42 * @param data Read-write file, empty when onBackup() is called, that 43 * is the data destination for this backup pass's incrementals. 44 * 45 * @param newState Read-write file, empty when onBackup() is called, 46 * where the new state blob is to be recorded. 47 * 48 * @param quotaBytes Quota reported by the transport for this backup operation (in bytes). 49 * 50 * @param callbackBinder Binder on which to indicate operation completion. 51 * 52 * @param transportFlags Flags with additional information about the transport. 53 */ doBackup(in ParcelFileDescriptor oldState, in ParcelFileDescriptor data, in ParcelFileDescriptor newState, long quotaBytes, IBackupCallback callbackBinder, int transportFlags)54 void doBackup(in ParcelFileDescriptor oldState, 55 in ParcelFileDescriptor data, 56 in ParcelFileDescriptor newState, 57 long quotaBytes, IBackupCallback callbackBinder, int transportFlags); 58 59 /** 60 * Restore an entire data snapshot to the application. 61 * 62 * @param data Read-only file containing the full data snapshot of the 63 * app's backup. This is to be a <i>replacement</i> of the app's 64 * current data, not to be merged into it. 65 * 66 * @param appVersionCode The android:versionCode attribute of the application 67 * that created this data set. This can help the agent distinguish among 68 * various historical backup content possibilities. 69 * 70 * @param newState Read-write file, empty when onRestore() is called, 71 * that is to be written with the state description that holds after 72 * the restore has been completed. 73 * 74 * @param token Opaque token identifying this transaction. This must 75 * be echoed back to the backup service binder once the agent is 76 * finished restoring the application based on the restore data 77 * contents. 78 * 79 * @param callbackBinder Binder on which to indicate operation completion, 80 * passed here as a convenience to the agent. 81 */ doRestore(in ParcelFileDescriptor data, long appVersionCode, in ParcelFileDescriptor newState, int token, IBackupManager callbackBinder)82 void doRestore(in ParcelFileDescriptor data, 83 long appVersionCode, in ParcelFileDescriptor newState, 84 int token, IBackupManager callbackBinder); 85 86 /** 87 * Restore an entire data snapshot to the application and pass the list of excluded keys to the 88 * backup agent. 89 * 90 * @param excludedKeys List of keys to be excluded from the restore. It will be passed to the 91 * backup agent to make it aware of what data has been removed (in case it has any 92 * application-level implications) as well as the data that should be removed by the 93 * agent itself. 94 */ doRestoreWithExcludedKeys(in ParcelFileDescriptor data, long appVersionCode, in ParcelFileDescriptor newState, int token, IBackupManager callbackBinder, in List<String> excludedKeys)95 void doRestoreWithExcludedKeys(in ParcelFileDescriptor data, 96 long appVersionCode, in ParcelFileDescriptor newState, 97 int token, IBackupManager callbackBinder, in List<String> excludedKeys); 98 99 /** 100 * Perform a "full" backup to the given file descriptor. The output file is presumed 101 * to be a socket or other non-seekable, write-only data sink. When this method is 102 * called, the app should write all of its files to the output. 103 * 104 * @param data Write-only file to receive the backed-up file content stream. 105 * The data must be formatted correctly for the resulting archive to be 106 * legitimate, so that will be tightly controlled by the available API. 107 * 108 * @param quotaBytes Quota reported by the transport for this backup operation (in bytes). 109 * 110 * @param token Opaque token identifying this transaction. This must 111 * be echoed back to the backup service binder once the agent is 112 * finished restoring the application based on the restore data 113 * contents. 114 * 115 * @param callbackBinder Binder on which to indicate operation completion, 116 * passed here as a convenience to the agent. 117 * 118 * @param transportFlags Flags with additional information about transport. 119 */ doFullBackup(in ParcelFileDescriptor data, long quotaBytes, int token, IBackupManager callbackBinder, int transportFlags)120 void doFullBackup(in ParcelFileDescriptor data, long quotaBytes, int token, 121 IBackupManager callbackBinder, int transportFlags); 122 123 /** 124 * Estimate how much data a full backup will deliver 125 */ doMeasureFullBackup(long quotaBytes, int token, IBackupManager callbackBinder, int transportFlags)126 void doMeasureFullBackup(long quotaBytes, int token, IBackupManager callbackBinder, 127 int transportFlags); 128 129 /** 130 * Tells the application agent that the backup data size exceeded current transport quota. 131 * Later calls to {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} 132 * and {@link #onFullBackup(FullBackupDataOutput)} could use this information 133 * to reduce backup size under the limit. 134 * However, the quota can change, so do not assume that the value passed in here is absolute, 135 * similarly all subsequent backups should not be restricted to this size. 136 * This callback will be invoked before data has been put onto the wire in a preflight check, 137 * so it is relatively inexpensive to hit your quota. 138 * Apps that hit quota repeatedly without dealing with it can be subject to having their backup 139 * schedule reduced. 140 * The {@code quotaBytes} is a loose guideline b/c of metadata added by the backupmanager 141 * so apps should be more aggressive in trimming their backup set. 142 * 143 * @param backupDataBytes Expected or already processed amount of data. 144 * Could be less than total backup size if backup process was interrupted 145 * before finish of processing all backup data. 146 * @param quotaBytes Current amount of backup data that is allowed for the app. 147 * @param callbackBinder Binder on which to indicate operation completion. 148 */ doQuotaExceeded(long backupDataBytes, long quotaBytes, IBackupCallback callbackBinder)149 void doQuotaExceeded(long backupDataBytes, long quotaBytes, IBackupCallback callbackBinder); 150 151 /** 152 * Restore a single "file" to the application. The file was typically obtained from 153 * a full-backup dataset. The agent reads 'size' bytes of file content 154 * from the provided file descriptor. 155 * 156 * @param data Read-only pipe delivering the file content itself. 157 * 158 * @param size Size of the file being restored. 159 * @param type Type of file system entity, e.g. FullBackup.TYPE_DIRECTORY. 160 * @param domain Name of the file's semantic domain to which the 'path' argument is a 161 * relative path. e.g. FullBackup.DATABASE_TREE_TOKEN. 162 * @param path Relative path of the file within its semantic domain. 163 * @param mode Access mode of the file system entity, e.g. 0660. 164 * @param mtime Last modification time of the file system entity. 165 * @param token Opaque token identifying this transaction. This must 166 * be echoed back to the backup service binder once the agent is 167 * finished restoring the application based on the restore data 168 * contents. 169 * @param callbackBinder Binder on which to indicate operation completion, 170 * passed here as a convenience to the agent. 171 */ doRestoreFile(in ParcelFileDescriptor data, long size, int type, String domain, String path, long mode, long mtime, int token, IBackupManager callbackBinder)172 void doRestoreFile(in ParcelFileDescriptor data, long size, 173 int type, String domain, String path, long mode, long mtime, 174 int token, IBackupManager callbackBinder); 175 176 /** 177 * Provide the app with a canonical "all data has been delivered" end-of-restore 178 * callback so that it can do any postprocessing of the restored data that might 179 * be appropriate. This is issued after both key/value and full data restore 180 * operations have completed. 181 * 182 * @param token Opaque token identifying this transaction. This must 183 * be echoed back to the backup service binder once the agent is 184 * finished restoring the application based on the restore data 185 * contents. 186 * @param callbackBinder Binder on which to indicate operation completion, 187 * passed here as a convenience to the agent. 188 */ doRestoreFinished(int token, IBackupManager callbackBinder)189 void doRestoreFinished(int token, IBackupManager callbackBinder); 190 191 /** 192 * Out of band: instruct the agent to crash within the client process. This is used 193 * when the backup infrastructure detects a semantic error post-hoc and needs to 194 * pass the problem back to the app. 195 * 196 * @param message The message to be passed to the agent's application in an exception. 197 */ fail(String message)198 void fail(String message); 199 200 /** 201 * Provides the logging results that were accumulated in the BackupAgent during a backup or 202 * restore operation. This method should be called after the agent completes its backup or 203 * restore. 204 * 205 * @param resultsFuture a future that is completed with the logging results. 206 */ getLoggerResults( in AndroidFuture<List<BackupRestoreEventLogger.DataTypeResult>> resultsFuture)207 void getLoggerResults( 208 in AndroidFuture<List<BackupRestoreEventLogger.DataTypeResult>> resultsFuture); 209 210 /** 211 * Provides the operation type (backup or restore) the agent is created for. See 212 * {@link android.app.backup.BackupAnnotations.OperationType}. 213 */ getOperationType(in AndroidFuture<int> operationTypeFuture)214 void getOperationType(in AndroidFuture<int> operationTypeFuture); 215 216 /** 217 * Clears the logs accumulated by the BackupAgent during a backup or restore operation. 218 */ clearBackupRestoreEventLogger()219 void clearBackupRestoreEventLogger(); 220 } 221