IBackupTransport.aidl revision 74318c98a0f67e042815798f85c75eb7f14390e1
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 { 26cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate /** 27cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate * Ask the transport for the name under which it should be registered. This will 28cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate * typically be its host service's component name, but need not be. 29cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate */ 30cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate String name(); 31cefba58d14f9669b57c16b4ea493779d882c43bdChristopher Tate 32a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 33a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * Ask the transport for an Intent that can be used to launch any internal 34a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * configuration Activity that it wishes to present. For example, the transport 35a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * may offer a UI for allowing the user to supply login credentials for the 36a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * transport's off-device backend. 37a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 38a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * If the transport does not supply any user-facing configuration UI, it should 39a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * return null from this method. 40a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 41a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return An Intent that can be passed to Context.startActivity() in order to 42a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * launch the transport's configuration UI. This method will return null 43a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * if the transport does not offer any user-facing configuration UI. 44a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 45a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate Intent configurationIntent(); 46a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 47a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate /** 48a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * On demand, supply a one-line string that can be shown to the user that 49a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * describes the current backend destination. For example, a transport that 50a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * can potentially associate backup data with arbitrary user accounts should 51a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * include the name of the currently-active account here. 52a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * 53a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * @return A string describing the destination to which the transport is currently 54a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate * sending data. This method should not return null. 55a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate */ 56a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate String currentDestinationString(); 57a8ddef346cece1ad229e270ac4deebbd41ba6721Chris Tate 58e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 595cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Ask the transport where, on local device storage, to keep backup state blobs. 605cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * This is per-transport so that mock transports used for testing can coexist with 615cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * "live" backup services without interfering with the live bookkeeping. The 625cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * returned string should be a name that is expected to be unambiguous among all 635cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * available backup transports; the name of the class implementing the transport 645cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * is a good choice. 655cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * 665cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * @return A unique name, suitable for use as a file or directory name, that the 675cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Backup Manager could use to disambiguate state files associated with 685cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * different backup transports. 695cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate */ 705cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate String transportDirName(); 715cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate 725cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate /** 73df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Verify that this is a suitable time for a backup pass. This should return zero 74aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * if a backup is reasonable right now, some positive value otherwise. This method 75aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * will be called outside of the {@link #startSession}/{@link #endSession} pair. 76df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * 77aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * <p>If this is not a suitable time for a backup, the transport should return a 78df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * backoff delay, in milliseconds, after which the Backup Manager should try again. 79aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * 80aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * @return Zero if this is a suitable time for a backup pass, or a positive time delay 81aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * in milliseconds to suggest deferring the backup pass for a while. 82df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate */ 83df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate long requestBackupTime(); 84df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate 85df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate /** 860144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * Initialize the server side storage for this device, erasing all stored data. 870144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * The transport may send the request immediately, or may buffer it. After 880144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * this is called, {@link #finishBackup} must be called to ensure the request 890144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * is sent and received successfully. 900144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * 910144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far) or 920144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure). 930144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor */ 940144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int initializeDevice(); 950144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor 960144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor /** 97efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Send one application's data to the backup destination. The transport may send 98efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 99efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * must be called to ensure the data is sent and recorded successfully. 100e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 101b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being backed up. 102b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This specifically includes the signature list for the package. 103e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @param data The data stream that resulted from invoking the application's 1047b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * BackupService.doBackup() method. This may be a pipe rather than a file on 1057b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * persistent media, so it may not be seekable. 10625a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * @param wipeAllFirst When true, <i>all</i> backed-up data for the current device/account 10725a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * will be erased prior to the storage of the data provided here. The purpose of this 10825a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * is to provide a guarantee that no stale data exists in the restore set when the 10925a747f5c47f25c1a18961b03507f309b84924feChristopher Tate * device begins providing backups. 1100144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far), 1110144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or 1120144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has 1130144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * become lost due to inactive expiry or some other reason and needs re-initializing) 114e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 1150144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 116efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 117efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 118ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Erase the give application's data from the backup destination. This clears 119ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * out the given package's data from the current backup set, making it as though 120ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * the app had never yet been backed up. After this is called, {@link finishBackup} 121ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * must be called to ensure that the operation is recorded successfully. 122efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * 1230144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 124efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 1250144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int clearBackupData(in PackageInfo packageInfo); 126ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate 127ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate /** 128ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Finish sending application data to the backup destination. This must be 129ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * called after {@link #performBackup} or {@link clearBackupData} to ensure that 130ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * all data is sent. Only when this method returns true can a backup be assumed 131ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * to have succeeded. 132ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * 1330144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return the same error codes as {@link #performBackup}. 134ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate */ 1350144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int finishBackup(); 136e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 137e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 13850c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the set of all backups currently available over this transport. 139b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 140efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return Descriptions of the set of restore images available for this device, 141efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the attempt should be rescheduled). 142b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate **/ 1439b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tate RestoreSet[] getAvailableRestoreSets(); 144b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 145b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 14650c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * Get the identifying token of the backup set currently being stored from 14750c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * this device. This is used in the case of applications wishing to restore 14850c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * their last-known-good data. 14950c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * 15050c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @return A token that can be passed to {@link #startRestore}, or 0 if there 15150c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * is no backup set available corresponding to the current device state. 15250c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate */ 15350c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate long getCurrentRestoreSet(); 15450c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate 15550c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate /** 156efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Start restoring application data from backup. After calling this function, 157efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 158efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * to walk through the actual application data. 159b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 16050c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * @param token A backup token as returned by {@link #getAvailableRestoreSets} 16150c6df04cf17a99c3959c306a4e0e10da6d85c46Christopher Tate * or {@link #getCurrentRestoreSet}. 162efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param packages List of applications to restore (if data is available). 163efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Application data will be restored in the order given. 1640144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call 1650144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR} 1660144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor * (an error occurred, the restore should be aborted and rescheduled). 167b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 1680144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int startRestore(long token, in PackageInfo[] packages); 169b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 170b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 171efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the package name of the next application with data in the backup store. 172efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return The name of one of the packages supplied to {@link #startRestore}, 173efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or "" (the empty string) if no more backup data is available, 174efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the restore should be aborted and rescheduled). 175b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 176efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor String nextRestorePackage(); 177b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 178b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 179efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the data for the application returned by {@link #nextRestorePackage}. 180efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param data An open, writable file into which the backup data should be stored. 18174318c98a0f67e042815798f85c75eb7f14390e1Christopher Tate * @return the same error codes as {@link #startRestore}. 182efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 1830144516e19b9fd5415a56f8b41191187e2344bb0Dan Egnor int getRestoreData(in ParcelFileDescriptor outFd); 184efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 185efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 186efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * End a restore session (aborting any in-process data transfer as necessary), 187efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * freeing any resources and connections used during the restore process. 188e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 189efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor void finishRestore(); 190487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 191