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 194528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tateimport android.app.backup.RestoreSet; 20a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tateimport android.content.Intent; 217b88128e08ba45b071cd714dad9681ce66920d32Christopher Tateimport android.content.pm.PackageInfo; 22e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tateimport android.os.ParcelFileDescriptor; 23e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 24487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/** {@hide} */ 25487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tateinterface IBackupTransport { 26a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 27a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * Ask the transport for an Intent that can be used to launch any internal 28a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * configuration Activity that it wishes to present. For example, the transport 29a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * may offer a UI for allowing the user to supply login credentials for the 30a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * transport's off-device backend. 31a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 32a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * If the transport does not supply any user-facing configuration UI, it should 33a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * return null from this method. 34a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 35a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return An Intent that can be passed to Context.startActivity() in order to 36a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * launch the transport's configuration UI. This method will return null 37a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * if the transport does not offer any user-facing configuration UI. 38a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 39a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate Intent configurationIntent(); 40a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 41a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 42a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * On demand, supply a one-line string that can be shown to the user that 43a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * describes the current backend destination. For example, a transport that 44a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * can potentially associate backup data with arbitrary user accounts should 45a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * include the name of the currently-active account here. 46a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 47a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return A string describing the destination to which the transport is currently 48a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * sending data. This method should not return null. 49a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 50a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate String currentDestinationString(); 51a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 52e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 535cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Ask the transport where, on local device storage, to keep backup state blobs. 545cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * This is per-transport so that mock transports used for testing can coexist with 555cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * "live" backup services without interfering with the live bookkeeping. The 565cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * returned string should be a name that is expected to be unambiguous among all 575cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * available backup transports; the name of the class implementing the transport 585cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * is a good choice. 595cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * 605cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * @return A unique name, suitable for use as a file or directory name, that the 615cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Backup Manager could use to disambiguate state files associated with 625cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * different backup transports. 635cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate */ 645cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate String transportDirName(); 655cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate 665cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate /** 67df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Verify that this is a suitable time for a backup pass. This should return zero 68aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * if a backup is reasonable right now, some positive value otherwise. This method 69aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * will be called outside of the {@link #startSession}/{@link #endSession} pair. 70df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * 71aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * <p>If this is not a suitable time for a backup, the transport should return a 72df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * backoff delay, in milliseconds, after which the Backup Manager should try again. 73aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * 74aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * @return Zero if this is a suitable time for a backup pass, or a positive time delay 75aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * in milliseconds to suggest deferring the backup pass for a while. 76df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate */ 77df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate long requestBackupTime(); 78df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate 79df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate /** 800144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * Initialize the server side storage for this device, erasing all stored data. 810144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * The transport may send the request immediately, or may buffer it. After 820144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * this is called, {@link #finishBackup} must be called to ensure the request 830144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * is sent and received successfully. 840144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * 850144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far) or 860144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure). 870144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor */ 880144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int initializeDevice(); 890144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor 900144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor /** 91efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Send one application's data to the backup destination. The transport may send 92efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 93efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * must be called to ensure the data is sent and recorded successfully. 94e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 95b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being backed up. 96b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This specifically includes the signature list for the package. 97e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @param data The data stream that resulted from invoking the application's 987b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * BackupService.doBackup() method. This may be a pipe rather than a file on 997b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * persistent media, so it may not be seekable. 10025a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * @param wipeAllFirst When true, <i>all</i> backed-up data for the current device/account 10125a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * will be erased prior to the storage of the data provided here. The purpose of this 10225a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * is to provide a guarantee that no stale data exists in the restore set when the 10325a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * device begins providing backups. 1040144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far), 1050144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or 1060144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has 1070144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * become lost due to inactive expiry or some other reason and needs re-initializing) 108e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 1090144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 110efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 111efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 112ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Erase the give application's data from the backup destination. This clears 113ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * out the given package's data from the current backup set, making it as though 114ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * the app had never yet been backed up. After this is called, {@link finishBackup} 115ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * must be called to ensure that the operation is recorded successfully. 116efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * 1170144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 118efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 1190144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int clearBackupData(in PackageInfo packageInfo); 120ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate 121ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate /** 122ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Finish sending application data to the backup destination. This must be 123ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * called after {@link #performBackup} or {@link clearBackupData} to ensure that 124ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * all data is sent. Only when this method returns true can a backup be assumed 125ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * to have succeeded. 126ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * 1270144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 128ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate */ 1290144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int finishBackup(); 130e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 131e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 13250c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the set of all backups currently available over this transport. 133b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 134efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return Descriptions of the set of restore images available for this device, 135efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the attempt should be rescheduled). 136b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate **/ 1379b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tate RestoreSet[] getAvailableRestoreSets(); 138b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 139b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 14050c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the identifying token of the backup set currently being stored from 14150c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * this device. This is used in the case of applications wishing to restore 14250c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * their last-known-good data. 14350c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * 14450c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @return A token that can be passed to {@link #startRestore}, or 0 if there 14550c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * is no backup set available corresponding to the current device state. 14650c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate */ 14750c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate long getCurrentRestoreSet(); 14850c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate 14950c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate /** 150efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Start restoring application data from backup. After calling this function, 151efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 152efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * to walk through the actual application data. 153b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 15450c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @param token A backup token as returned by {@link #getAvailableRestoreSets} 15550c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * or {@link #getCurrentRestoreSet}. 156efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param packages List of applications to restore (if data is available). 157efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Application data will be restored in the order given. 1580144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call 1590144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR} 1600144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * (an error occurred, the restore should be aborted and rescheduled). 161b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 1620144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int startRestore(long token, in PackageInfo[] packages); 163b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 164b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 165efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the package name of the next application with data in the backup store. 166efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return The name of one of the packages supplied to {@link #startRestore}, 167efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or "" (the empty string) if no more backup data is available, 168efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the restore should be aborted and rescheduled). 169b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 170efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor String nextRestorePackage(); 171b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 172b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 173efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the data for the application returned by {@link #nextRestorePackage}. 174efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param data An open, writable file into which the backup data should be stored. 1750144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #nextRestorePackage}. 176efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 1770144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int getRestoreData(in ParcelFileDescriptor outFd); 178efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 179efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 180efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * End a restore session (aborting any in-process data transfer as necessary), 181efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * freeing any resources and connections used during the restore process. 182e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 183efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor void finishRestore(); 184487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 185