11cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato/* 21cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * Copyright (C) 2009 The Android Open Source Project 31cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * 41cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * Licensed under the Apache License, Version 2.0 (the "License"); 51cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * you may not use this file except in compliance with the License. 61cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * You may obtain a copy of the License at 71cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * 81cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * http://www.apache.org/licenses/LICENSE-2.0 91cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * 101cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * Unless required by applicable law or agreed to in writing, software 111cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * distributed under the License is distributed on an "AS IS" BASIS, 121cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * See the License for the specific language governing permissions and 141cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato * limitations under the License. 151cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato */ 161cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato 174528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tatepackage android.app.backup; 181cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato 19d2d9ceb7305d593c1b767bbb05de0082a9af4109Joe Onoratoimport android.os.ParcelFileDescriptor; 20d2d9ceb7305d593c1b767bbb05de0082a9af4109Joe Onorato 21e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate/** 22d17da43c82c4edb97514d6138bc208eeba321636Scott Main * Defines the calling interface that {@link BackupAgentHelper} uses 237cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * when dispatching backup and restore operations to the installed helpers. 247cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * Applications can define and install their own helpers as well as using those 257cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * provided as part of the Android framework. 265a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * <p> 277cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * Although multiple helper objects may be installed simultaneously, each helper 287cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * is responsible only for handling its own data, and will not see entities 297cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * created by other components within the backup system. Invocations of multiple 307cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * helpers are performed sequentially by the {@link BackupAgentHelper}, with each 317cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * helper given a chance to access its own saved state from within the state record 327cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * produced during the previous backup operation. 337cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * 347cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * @see BackupAgentHelper 357cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * @see FileBackupHelper 367cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * @see SharedPreferencesBackupHelper 37e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate */ 3806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onoratopublic interface BackupHelper { 395f15d151b5101fadfe6cba1e8f4aa6367e8c603eJoe Onorato /** 40cd31d5d9aee277da23365e7e0a96ad359eb68a5fChristopher Tate * Based on <code>oldState</code>, determine what application content 41cd31d5d9aee277da23365e7e0a96ad359eb68a5fChristopher Tate * needs to be backed up, write it to <code>data</code>, and fill in 42cd31d5d9aee277da23365e7e0a96ad359eb68a5fChristopher Tate * <code>newState</code> with the complete state as it exists now. 437cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 447cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * Implementing this method is much like implementing 45d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) 46d17da43c82c4edb97514d6138bc208eeba321636Scott Main * onBackup()} — the method parameters are the same. When this method is invoked the 477cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * {@code oldState} descriptor points to the beginning of the state data 487cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * written during this helper's previous backup operation, and the {@code newState} 497cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * descriptor points to the file location at which the helper should write its 507cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * new state after performing the backup operation. 517cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 52d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> The helper should not close or seek either the {@code oldState} or 531203aa05f8bc0038b78ca2c8ab464b31d167e68aChristopher Tate * the {@code newState} file descriptors. It is essential that when reading the helper's 541203aa05f8bc0038b78ca2c8ab464b31d167e68aChristopher Tate * saved state from the {@code oldState} file, no extra content is consumed beyond 551203aa05f8bc0038b78ca2c8ab464b31d167e68aChristopher Tate * what was stored by this helper. If more old state data is read, even accidentally, 561203aa05f8bc0038b78ca2c8ab464b31d167e68aChristopher Tate * it will make it impossible for additional helpers that may be invoked after this one 571203aa05f8bc0038b78ca2c8ab464b31d167e68aChristopher Tate * to properly reconstruct their prior state.</p> 58d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 59d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param oldState An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the 60d17da43c82c4edb97514d6138bc208eeba321636Scott Main * last backup state provided by the application. May be 61d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <code>null</code>, in which case no prior state is being 62d17da43c82c4edb97514d6138bc208eeba321636Scott Main * provided and the application should perform a full backup. 63d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param data An open, read/write {@link BackupDataOutput} 64d17da43c82c4edb97514d6138bc208eeba321636Scott Main * pointing to the backup data destination. 65d17da43c82c4edb97514d6138bc208eeba321636Scott Main * Typically the application will use backup helper classes to 66d17da43c82c4edb97514d6138bc208eeba321636Scott Main * write to this file. 67d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param newState An open, read/write {@link android.os.ParcelFileDescriptor} pointing to an 68d17da43c82c4edb97514d6138bc208eeba321636Scott Main * empty file. The application should record the final backup 69d17da43c82c4edb97514d6138bc208eeba321636Scott Main * state here after writing the requested data to the <code>data</code> 70d17da43c82c4edb97514d6138bc208eeba321636Scott Main * output stream. 7106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato */ 7206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, 7306290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato ParcelFileDescriptor newState); 7406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 7506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato /** 76cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tate * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} 777cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * to restore a single entity from the restore data set. This method will be 787cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * called for each entity in the data set that belongs to this handler. 797cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 80d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> Do not close the <code>data</code> stream. Do not read more than 81d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link android.app.backup.BackupDataInputStream#size() size()} bytes from 82d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <code>data</code>.</p> 83d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 84d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param data An open {@link BackupDataInputStream} from which the backup data can be read. 855f15d151b5101fadfe6cba1e8f4aa6367e8c603eJoe Onorato */ 86efd0fab04b96d7ab0c1d8bf3b79397c8621e31c5Joe Onorato public void restoreEntity(BackupDataInputStream data); 8706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 8806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato /** 89cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tate * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} 904e14a829129feee14ebe453f61a124784c870610Christopher Tate * after a restore operation to write the backup state file corresponding to 917cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * the data as processed by the helper. The data written here will be 927cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * available to the helper during the next call to its 93d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) 94d17da43c82c4edb97514d6138bc208eeba321636Scott Main * performBackup()} method. 957cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 96d17da43c82c4edb97514d6138bc208eeba321636Scott Main * This method will be called even if the handler's 97d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link #restoreEntity(BackupDataInputStream) restoreEntity()} method was never invoked during 987cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * the restore operation. 997cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 100d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> The helper should not close or seek the {@code newState} 1017cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * file descriptor.</p> 102d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 103d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param newState A {@link android.os.ParcelFileDescriptor} to which the new state will be 104d17da43c82c4edb97514d6138bc208eeba321636Scott Main * written. 10506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato */ 1067cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate public void writeNewStateDescription(ParcelFileDescriptor newState); 1071cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato} 1081cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato 109