1487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/* 2487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Copyright 2009, The Android Open Source Project 3487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 4487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Licensed under the Apache License, Version 2.0 (the "License"); 5487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * you may not use this file except in compliance with the License. 6487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * You may obtain a copy of the License at 7487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 8487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * http://www.apache.org/licenses/LICENSE-2.0 9487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 10487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Unless required by applicable law or agreed to in writing, software 11487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * distributed under the License is distributed on an "AS IS" BASIS, 12487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * See the License for the specific language governing permissions and 14487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * limitations under the License. 15487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate */ 16487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate 17181fafaf48208978b8ba2022683ffa78aaeddde1Christopher Tatepackage android.app; 18487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate 194528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tateimport android.app.backup.IBackupManager; 2022b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tateimport android.os.ParcelFileDescriptor; 2122b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate 22487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/** 23487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Interface presented by applications being asked to participate in the 244528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tate * backup & restore mechanism. End user code will not typically implement 254528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tate * this interface directly; they subclass BackupAgent instead. 26487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 27487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * {@hide} 2822b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate */ 2944a2790374bf27116cbd91060d4f096ca5999709Christopher Tateoneway interface IBackupAgent { 30487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate /** 31487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Request that the app perform an incremental backup. 32487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 3322b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * @param oldState Read-only file containing the description blob of the 34487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * app's data state as of the last backup operation's completion. 3522b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * This file is empty or invalid when a full backup is being 3622b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * requested. 37487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 3822b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * @param data Read-write file, empty when onBackup() is called, that 39487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * is the data destination for this backup pass's incrementals. 40487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 4122b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * @param newState Read-write file, empty when onBackup() is called, 42487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * where the new state blob is to be recorded. 4344a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * 4444a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * @param token Opaque token identifying this transaction. This must 4544a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * be echoed back to the backup service binder once the new 4644a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * data has been written to the data and newState files. 4744a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * 4844a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 4944a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * passed here as a convenience to the agent. 50487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate */ 5122b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate void doBackup(in ParcelFileDescriptor oldState, 5222b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate in ParcelFileDescriptor data, 5344a2790374bf27116cbd91060d4f096ca5999709Christopher Tate in ParcelFileDescriptor newState, 5444a2790374bf27116cbd91060d4f096ca5999709Christopher Tate int token, IBackupManager callbackBinder); 55487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate 56487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate /** 57487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Restore an entire data snapshot to the application. 58487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 5922b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * @param data Read-only file containing the full data snapshot of the 60487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * app's backup. This is to be a <i>replacement</i> of the app's 61487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * current data, not to be merged into it. 62487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * 635cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate * @param appVersionCode The android:versionCode attribute of the application 645cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate * that created this data set. This can help the agent distinguish among 655cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate * various historical backup content possibilities. 665cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate * 6722b8787ed4be8d4b7ed5d54802f9913fedb41425Christopher Tate * @param newState Read-write file, empty when onRestore() is called, 68487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * that is to be written with the state description that holds after 69487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * the restore has been completed. 7044a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * 7144a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * @param token Opaque token identifying this transaction. This must 7244a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * be echoed back to the backup service binder once the agent is 7344a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * finished restoring the application based on the restore data 7444a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * contents. 7544a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * 7644a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 7744a2790374bf27116cbd91060d4f096ca5999709Christopher Tate * passed here as a convenience to the agent. 78487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate */ 79adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate void doRestore(in ParcelFileDescriptor data, 80adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate int appVersionCode, in ParcelFileDescriptor newState, 81adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate int token, IBackupManager callbackBinder); 8279ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate 8379ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate /** 8479ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * Perform a "full" backup to the given file descriptor. The output file is presumed 8579ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * to be a socket or other non-seekable, write-only data sink. When this method is 8679ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * called, the app should write all of its files to the output. 8779ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 8879ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param data Write-only file to receive the backed-up file content stream. 8979ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * The data must be formatted correctly for the resulting archive to be 9079ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * legitimate, so that will be tightly controlled by the available API. 9179ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 9279ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param token Opaque token identifying this transaction. This must 9379ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * be echoed back to the backup service binder once the agent is 9479ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * finished restoring the application based on the restore data 9579ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * contents. 9679ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 9779ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 9879ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * passed here as a convenience to the agent. 9979ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate */ 10079ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate void doFullBackup(in ParcelFileDescriptor data, int token, IBackupManager callbackBinder); 10175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate 10275a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate /** 10311ae768cf1b8348e761ad9c09e98788da1e591b1Christopher Tate * Estimate how much data a full backup will deliver 10411ae768cf1b8348e761ad9c09e98788da1e591b1Christopher Tate */ 10511ae768cf1b8348e761ad9c09e98788da1e591b1Christopher Tate void doMeasureFullBackup(int token, IBackupManager callbackBinder); 10611ae768cf1b8348e761ad9c09e98788da1e591b1Christopher Tate 10711ae768cf1b8348e761ad9c09e98788da1e591b1Christopher Tate /** 108872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * Tells the application agent that the backup data size exceeded current transport quota. 109872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * Later calls to {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} 110872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * and {@link #onFullBackup(FullBackupDataOutput)} could use this information 111872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * to reduce backup size under the limit. 112872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * However, the quota can change, so do not assume that the value passed in here is absolute, 113872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * similarly all subsequent backups should not be restricted to this size. 114872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * This callback will be invoked before data has been put onto the wire in a preflight check, 115872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * so it is relatively inexpensive to hit your quota. 116872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * Apps that hit quota repeatedly without dealing with it can be subject to having their backup 117872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * schedule reduced. 118872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * The {@code quotaBytes} is a loose guideline b/c of metadata added by the backupmanager 119872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * so apps should be more aggressive in trimming their backup set. 120872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * 121872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * @param backupDataBytes Expected or already processed amount of data. 122872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * Could be less than total backup size if backup process was interrupted 123872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * before finish of processing all backup data. 124872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov * @param quotaBytes Current amount of backup data that is allowed for the app. 125872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov */ 126872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov void doQuotaExceeded(long backupDataBytes, long quotaBytes); 127872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov 128872d3b6e19933af6fa9ae65214b9f6df04fc3222Sergey Poromov /** 12975a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * Restore a single "file" to the application. The file was typically obtained from 13075a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * a full-backup dataset. The agent reads 'size' bytes of file content 13175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * from the provided file descriptor. 13275a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * 13375a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param data Read-only pipe delivering the file content itself. 13475a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * 13575a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param size Size of the file being restored. 13675a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param type Type of file system entity, e.g. FullBackup.TYPE_DIRECTORY. 13775a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param domain Name of the file's semantic domain to which the 'path' argument is a 13875a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * relative path. e.g. FullBackup.DATABASE_TREE_TOKEN. 13975a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param path Relative path of the file within its semantic domain. 14075a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param mode Access mode of the file system entity, e.g. 0660. 14175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param mtime Last modification time of the file system entity. 142adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * @param token Opaque token identifying this transaction. This must 143adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * be echoed back to the backup service binder once the agent is 144adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * finished restoring the application based on the restore data 145adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * contents. 146adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 147adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate * passed here as a convenience to the agent. 14875a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate */ 14975a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate void doRestoreFile(in ParcelFileDescriptor data, long size, 15075a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate int type, String domain, String path, long mode, long mtime, 15175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate int token, IBackupManager callbackBinder); 152adfe8b86e9178a553b6db9722340fa4ff5201cf1Christopher Tate 153cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate /** 1542e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * Provide the app with a canonical "all data has been delivered" end-of-restore 1552e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * callback so that it can do any postprocessing of the restored data that might 1562e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * be appropriate. This is issued after both key/value and full data restore 1572e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * operations have completed. 1582e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * 1592e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * @param token Opaque token identifying this transaction. This must 1602e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * be echoed back to the backup service binder once the agent is 1612e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * finished restoring the application based on the restore data 1622e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * contents. 1632e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 1642e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate * passed here as a convenience to the agent. 1652e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate */ 1662e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate void doRestoreFinished(int token, IBackupManager callbackBinder); 1672e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate 1682e40d115ca4332d88424d1b591fdd8d5f78d1831Christopher Tate /** 169cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate * Out of band: instruct the agent to crash within the client process. This is used 170cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate * when the backup infrastructure detects a semantic error post-hoc and needs to 171cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate * pass the problem back to the app. 172cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate * 173cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate * @param message The message to be passed to the agent's application in an exception. 174cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate */ 175cba5941c6085dab1566bc047c1ea31f58a2dd4cfChristopher Tate void fail(String message); 176487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 177