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 /** 405a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * Based on <code>oldState</code>, determine which of the files from the 415a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * application's data directory need to be backed up, write them to 425a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * <code>data</code>, and fill in <code>newState</code> with the state as it 435a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * exists now. 447cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 457cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * Implementing this method is much like implementing 46d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) 47d17da43c82c4edb97514d6138bc208eeba321636Scott Main * onBackup()} — the method parameters are the same. When this method is invoked the 487cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * {@code oldState} descriptor points to the beginning of the state data 497cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * written during this helper's previous backup operation, and the {@code newState} 507cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * descriptor points to the file location at which the helper should write its 517cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * new state after performing the backup operation. 527cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 53d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> The helper should not close or seek either the {@code oldState} or 547cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * the {@code newState} file descriptors.</p> 55d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 56d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param oldState An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the 57d17da43c82c4edb97514d6138bc208eeba321636Scott Main * last backup state provided by the application. May be 58d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <code>null</code>, in which case no prior state is being 59d17da43c82c4edb97514d6138bc208eeba321636Scott Main * provided and the application should perform a full backup. 60d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param data An open, read/write {@link BackupDataOutput} 61d17da43c82c4edb97514d6138bc208eeba321636Scott Main * pointing to the backup data destination. 62d17da43c82c4edb97514d6138bc208eeba321636Scott Main * Typically the application will use backup helper classes to 63d17da43c82c4edb97514d6138bc208eeba321636Scott Main * write to this file. 64d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param newState An open, read/write {@link android.os.ParcelFileDescriptor} pointing to an 65d17da43c82c4edb97514d6138bc208eeba321636Scott Main * empty file. The application should record the final backup 66d17da43c82c4edb97514d6138bc208eeba321636Scott Main * state here after writing the requested data to the <code>data</code> 67d17da43c82c4edb97514d6138bc208eeba321636Scott Main * output stream. 6806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato */ 6906290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, 7006290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato ParcelFileDescriptor newState); 7106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 7206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato /** 73cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tate * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} 747cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * to restore a single entity from the restore data set. This method will be 757cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * called for each entity in the data set that belongs to this handler. 767cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 77d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> Do not close the <code>data</code> stream. Do not read more than 78d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link android.app.backup.BackupDataInputStream#size() size()} bytes from 79d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <code>data</code>.</p> 80d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 81d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param data An open {@link BackupDataInputStream} from which the backup data can be read. 825f15d151b5101fadfe6cba1e8f4aa6367e8c603eJoe Onorato */ 83efd0fab04b96d7ab0c1d8bf3b79397c8621e31c5Joe Onorato public void restoreEntity(BackupDataInputStream data); 8406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 8506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato /** 86cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tate * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} 874e14a829129feee14ebe453f61a124784c870610Christopher Tate * after a restore operation to write the backup state file corresponding to 887cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * the data as processed by the helper. The data written here will be 897cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * available to the helper during the next call to its 90d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) 91d17da43c82c4edb97514d6138bc208eeba321636Scott Main * performBackup()} method. 927cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 93d17da43c82c4edb97514d6138bc208eeba321636Scott Main * This method will be called even if the handler's 94d17da43c82c4edb97514d6138bc208eeba321636Scott Main * {@link #restoreEntity(BackupDataInputStream) restoreEntity()} method was never invoked during 957cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * the restore operation. 967cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p class="note"> 97d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <strong>Note:</strong> The helper should not close or seek the {@code newState} 987cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * file descriptor.</p> 99d17da43c82c4edb97514d6138bc208eeba321636Scott Main * 100d17da43c82c4edb97514d6138bc208eeba321636Scott Main * @param newState A {@link android.os.ParcelFileDescriptor} to which the new state will be 101d17da43c82c4edb97514d6138bc208eeba321636Scott Main * written. 10206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato */ 1037cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate public void writeNewStateDescription(ParcelFileDescriptor newState); 1041cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato} 1051cf587496fcb1d652bab9fc6792fb106b6fefaa4Joe Onorato 106