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 */ 795cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate void doRestore(in ParcelFileDescriptor data, int appVersionCode, 8044a2790374bf27116cbd91060d4f096ca5999709Christopher Tate in ParcelFileDescriptor newState, int token, IBackupManager callbackBinder); 8179ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate 8279ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate /** 8379ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * Perform a "full" backup to the given file descriptor. The output file is presumed 8479ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * to be a socket or other non-seekable, write-only data sink. When this method is 8579ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * called, the app should write all of its files to the output. 8679ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 8779ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param data Write-only file to receive the backed-up file content stream. 8879ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * The data must be formatted correctly for the resulting archive to be 8979ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * legitimate, so that will be tightly controlled by the available API. 9079ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 9179ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param token Opaque token identifying this transaction. This must 9279ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * be echoed back to the backup service binder once the agent is 9379ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * finished restoring the application based on the restore data 9479ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * contents. 9579ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * 9679ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * @param callbackBinder Binder on which to indicate operation completion, 9779ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate * passed here as a convenience to the agent. 9879ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate */ 9979ec80db70d788f35aa13346e4684ecbd401bd84Christopher Tate void doFullBackup(in ParcelFileDescriptor data, int token, IBackupManager callbackBinder); 10075a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate 10175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate /** 10275a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * Restore a single "file" to the application. The file was typically obtained from 10375a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * a full-backup dataset. The agent reads 'size' bytes of file content 10475a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * from the provided file descriptor. 10575a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * 10675a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param data Read-only pipe delivering the file content itself. 10775a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * 10875a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param size Size of the file being restored. 10975a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param type Type of file system entity, e.g. FullBackup.TYPE_DIRECTORY. 11075a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param domain Name of the file's semantic domain to which the 'path' argument is a 11175a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * relative path. e.g. FullBackup.DATABASE_TREE_TOKEN. 11275a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param path Relative path of the file within its semantic domain. 11375a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param mode Access mode of the file system entity, e.g. 0660. 11475a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate * @param mtime Last modification time of the file system entity. 11575a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate */ 11675a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate void doRestoreFile(in ParcelFileDescriptor data, long size, 11775a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate int type, String domain, String path, long mode, long mtime, 11875a99709accef8cf221fd436d646727e7c8dd1f1Christopher Tate int token, IBackupManager callbackBinder); 119487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 120