1487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/* 2487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate * Copyright (C) 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 17487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tatepackage com.android.internal.backup; 18487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate 196a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tateimport android.app.backup.RestoreDescription; 204528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tateimport android.app.backup.RestoreSet; 21a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tateimport android.content.Intent; 227b88128e08ba45b071cd714dad9681ce66920d32Christopher Tateimport android.content.pm.PackageInfo; 23e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tateimport android.os.ParcelFileDescriptor; 24e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 25487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/** {@hide} */ 26487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tateinterface IBackupTransport { 27cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate /** 28cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate * Ask the transport for the name under which it should be registered. This will 29cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate * typically be its host service's component name, but need not be. 30cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate */ 31cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate String name(); 32cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate 33a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 34a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * Ask the transport for an Intent that can be used to launch any internal 35a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * configuration Activity that it wishes to present. For example, the transport 36a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * may offer a UI for allowing the user to supply login credentials for the 37a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * transport's off-device backend. 38a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 39a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * If the transport does not supply any user-facing configuration UI, it should 40a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * return null from this method. 41a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 42a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return An Intent that can be passed to Context.startActivity() in order to 43a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * launch the transport's configuration UI. This method will return null 44a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * if the transport does not offer any user-facing configuration UI. 45a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 46a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate Intent configurationIntent(); 47a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 48a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 49a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * On demand, supply a one-line string that can be shown to the user that 50a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * describes the current backend destination. For example, a transport that 51a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * can potentially associate backup data with arbitrary user accounts should 52a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * include the name of the currently-active account here. 53a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 54a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return A string describing the destination to which the transport is currently 55a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * sending data. This method should not return null. 56a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 57a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate String currentDestinationString(); 58a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 59e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 609679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * Ask the transport for an Intent that can be used to launch a more detailed 619679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * secondary data management activity. For example, the configuration intent might 629679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * be one for allowing the user to select which account they wish to associate 639679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * their backups with, and the management intent might be one which presents a 649679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * UI for managing the data on the backend. 659679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * 669679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * <p>In the Settings UI, the configuration intent will typically be invoked 679679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * when the user taps on the preferences item labeled with the current 689679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * destination string, and the management intent will be placed in an overflow 699679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * menu labelled with the management label string. 709679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * 719679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * <p>If the transport does not supply any user-facing data management 729679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * UI, then it should return {@code null} from this method. 739679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * 749679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * @return An intent that can be passed to Context.startActivity() in order to 759679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * launch the transport's data-management UI. This method will return 769679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * {@code null} if the transport does not offer any user-facing data 779679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * management UI. 789679410db578e179c7559e7a52bb21c8082e9631Christopher Tate */ 799679410db578e179c7559e7a52bb21c8082e9631Christopher Tate Intent dataManagementIntent(); 809679410db578e179c7559e7a52bb21c8082e9631Christopher Tate 819679410db578e179c7559e7a52bb21c8082e9631Christopher Tate /** 829679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * On demand, supply a short string that can be shown to the user as the label 839679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * on an overflow menu item used to invoked the data management UI. 849679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * 859679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * @return A string to be used as the label for the transport's data management 869679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * affordance. If the transport supplies a data management intent, this 879679410db578e179c7559e7a52bb21c8082e9631Christopher Tate * method must not return {@code null}. 889679410db578e179c7559e7a52bb21c8082e9631Christopher Tate */ 899679410db578e179c7559e7a52bb21c8082e9631Christopher Tate String dataManagementLabel(); 909679410db578e179c7559e7a52bb21c8082e9631Christopher Tate 919679410db578e179c7559e7a52bb21c8082e9631Christopher Tate /** 925cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Ask the transport where, on local device storage, to keep backup state blobs. 935cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * This is per-transport so that mock transports used for testing can coexist with 945cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * "live" backup services without interfering with the live bookkeeping. The 955cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * returned string should be a name that is expected to be unambiguous among all 965cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * available backup transports; the name of the class implementing the transport 975cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * is a good choice. 985cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * 995cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * @return A unique name, suitable for use as a file or directory name, that the 1005cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Backup Manager could use to disambiguate state files associated with 1015cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * different backup transports. 1025cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate */ 1035cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate String transportDirName(); 1045cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate 1055cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate /** 106df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Verify that this is a suitable time for a backup pass. This should return zero 107aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * if a backup is reasonable right now, some positive value otherwise. This method 108aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * will be called outside of the {@link #startSession}/{@link #endSession} pair. 109df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * 110aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * <p>If this is not a suitable time for a backup, the transport should return a 111df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * backoff delay, in milliseconds, after which the Backup Manager should try again. 112aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * 113aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * @return Zero if this is a suitable time for a backup pass, or a positive time delay 114aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * in milliseconds to suggest deferring the backup pass for a while. 115df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate */ 116df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate long requestBackupTime(); 117df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate 118df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate /** 1190144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * Initialize the server side storage for this device, erasing all stored data. 1200144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * The transport may send the request immediately, or may buffer it. After 1210144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * this is called, {@link #finishBackup} must be called to ensure the request 1220144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * is sent and received successfully. 1230144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * 1240144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far) or 1250144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure). 1260144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor */ 1270144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int initializeDevice(); 1280144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor 1290144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor /** 130efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Send one application's data to the backup destination. The transport may send 131efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 132efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * must be called to ensure the data is sent and recorded successfully. 133e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 134b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being backed up. 135b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This specifically includes the signature list for the package. 136e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @param data The data stream that resulted from invoking the application's 1377b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * BackupService.doBackup() method. This may be a pipe rather than a file on 1387b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * persistent media, so it may not be seekable. 13925a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * @param wipeAllFirst When true, <i>all</i> backed-up data for the current device/account 14025a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * will be erased prior to the storage of the data provided here. The purpose of this 14125a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * is to provide a guarantee that no stale data exists in the restore set when the 14225a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * device begins providing backups. 1430144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far), 1440144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or 1450144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has 1460144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * become lost due to inactive expiry or some other reason and needs re-initializing) 147e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 1480144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 149efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 150efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 151ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Erase the give application's data from the backup destination. This clears 152ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * out the given package's data from the current backup set, making it as though 153ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * the app had never yet been backed up. After this is called, {@link finishBackup} 154ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * must be called to ensure that the operation is recorded successfully. 155efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * 1560144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 157efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 1580144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int clearBackupData(in PackageInfo packageInfo); 159ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate 160ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate /** 161ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Finish sending application data to the backup destination. This must be 162ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * called after {@link #performBackup} or {@link clearBackupData} to ensure that 163ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * all data is sent. Only when this method returns true can a backup be assumed 164ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * to have succeeded. 165ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * 1660144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 167ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate */ 1680144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int finishBackup(); 169e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 170e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 17150c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the set of all backups currently available over this transport. 172b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 173efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return Descriptions of the set of restore images available for this device, 174efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the attempt should be rescheduled). 175b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate **/ 1769b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tate RestoreSet[] getAvailableRestoreSets(); 177b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 178b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 17950c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the identifying token of the backup set currently being stored from 18050c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * this device. This is used in the case of applications wishing to restore 18150c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * their last-known-good data. 18250c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * 18350c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @return A token that can be passed to {@link #startRestore}, or 0 if there 18450c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * is no backup set available corresponding to the current device state. 18550c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate */ 18650c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate long getCurrentRestoreSet(); 18750c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate 18850c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate /** 189efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Start restoring application data from backup. After calling this function, 190efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 191efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * to walk through the actual application data. 192b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 19350c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @param token A backup token as returned by {@link #getAvailableRestoreSets} 19450c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * or {@link #getCurrentRestoreSet}. 195efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param packages List of applications to restore (if data is available). 196efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Application data will be restored in the order given. 1970144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call 1980144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR} 1990144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * (an error occurred, the restore should be aborted and rescheduled). 200b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 2010144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int startRestore(long token, in PackageInfo[] packages); 202b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 203b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 2046a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * Get the package name of the next application with data in the backup store, plus 2056a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * a description of the structure of the restored archive: either TYPE_KEY_VALUE for 2066a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * an original-API key/value dataset, or TYPE_FULL_STREAM for a tarball-type archive stream. 2076a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2086a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * <p>If the package name in the returned RestoreDescription object is the singleton 2096a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * {@link RestoreDescription#NO_MORE_PACKAGES}, it indicates that no further data is available 2106a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * in the current restore session: all packages described in startRestore() have been 2116a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * processed. 2126a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2136a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * <p>If this method returns {@code null}, it means that a transport-level error has 2146a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * occurred and the entire restore operation should be abandoned. 2156a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2166a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * @return A RestoreDescription object containing the name of one of the packages 2176a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * supplied to {@link #startRestore} plus an indicator of the data type of that 2186a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * restore data; or {@link RestoreDescription#NO_MORE_PACKAGES} to indicate that 2196a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * no more packages can be restored in this session; or {@code null} to indicate 2206a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * a transport-level error. 221b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 2226a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate RestoreDescription nextRestorePackage(); 223b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 224b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 225efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the data for the application returned by {@link #nextRestorePackage}. 226efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param data An open, writable file into which the backup data should be stored. 22774318c98a0f67e042815798f85c75eb7f14390e1Christopher Tate * @return the same error codes as {@link #startRestore}. 228efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 2290144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int getRestoreData(in ParcelFileDescriptor outFd); 230efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 231efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 232efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * End a restore session (aborting any in-process data transfer as necessary), 233efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * freeing any resources and connections used during the restore process. 234e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 235efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor void finishRestore(); 2369ff53a7100b1a40f5d2df3eb19a2f3f2fff39a46Christopher Tate 2376a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate // full backup stuff 2386a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate 2399ff53a7100b1a40f5d2df3eb19a2f3f2fff39a46Christopher Tate long requestFullBackupTime(); 2409ff53a7100b1a40f5d2df3eb19a2f3f2fff39a46Christopher Tate int performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket); 2419ff53a7100b1a40f5d2df3eb19a2f3f2fff39a46Christopher Tate int sendBackupData(int numBytes); 242bf1a4a81ebd340a18583f4ca9b5d562a01f55674Christopher Tate void cancelFullBackup(); 2436a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate 2446a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate // full restore stuff 2456a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate 2466a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate /** 2476a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * Ask the transport to provide data for the "current" package being restored. This 2486a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * is the package that was just reported by {@link #nextRestorePackage()} as having 2496a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * {@link RestoreDescription#TYPE_FULL_STREAM} data. 2506a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2516a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * The transport writes some data to the socket supplied to this call, and returns 2526a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * the number of bytes written. The system will then read that many bytes and 2536a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * stream them to the application's agent for restore, then will call this method again 2546a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * to receive the next chunk of the archive. This sequence will be repeated until the 2556a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * transport returns zero indicating that all of the package's data has been delivered 2566a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * (or returns a negative value indicating some sort of hard error condition at the 2576a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * transport level). 2586a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2596a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * <p>After this method returns zero, the system will then call 2606a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * {@link #getNextFullRestorePackage()} to begin the restore process for the next 2616a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * application, and the sequence begins again. 2626a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2636a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * <p>The transport should always close this socket when returning from this method. 2646a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * Do not cache this socket across multiple calls or you may leak file descriptors. 2656a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2666a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * @param socket The file descriptor that the transport will use for delivering the 2676a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * streamed archive. The transport must close this socket in all cases when returning 2686a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * from this method. 2696a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * @return 0 when no more data for the current package is available. A positive value 2706a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * indicates the presence of that many bytes to be delivered to the app. Any negative 2716a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * return value is treated as equivalent to {@link BackupTransport#TRANSPORT_ERROR}, 2726a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * indicating a fatal error condition that precludes further restore operations 2736a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * on the current dataset. 2746a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate */ 2756a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate int getNextFullRestoreDataChunk(in ParcelFileDescriptor socket); 2766a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate 2776a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate /** 2786a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * If the OS encounters an error while processing {@link RestoreDescription#TYPE_FULL_STREAM} 2796a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * data for restore, it will invoke this method to tell the transport that it should 2806a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * abandon the data download for the current package. The OS will then either call 2816a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * {@link #nextRestorePackage()} again to move on to restoring the next package in the 2826a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * set being iterated over, or will call {@link #finishRestore()} to shut down the restore 2836a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * operation. 2846a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * 2856a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * @return {@link #TRANSPORT_OK} if the transport was successful in shutting down the 2866a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * current stream cleanly, or {@link #TRANSPORT_ERROR} to indicate a serious 2876a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * transport-level failure. If the transport reports an error here, the entire restore 2886a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate * operation will immediately be finished with no further attempts to restore app data. 2896a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate */ 2906a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate int abortFullRestore(); 2916a49dd087f29cfca82d55dfabeb97439ef84b508Christopher Tate 292487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 293