IBackupTransport.aidl revision ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66
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 199b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tateimport android.backup.RestoreSet; 207b88128e08ba45b071cd714dad9681ce66920d32Christopher Tateimport android.content.pm.PackageInfo; 21e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tateimport android.os.ParcelFileDescriptor; 22e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 23487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate/** {@hide} */ 24487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tateinterface IBackupTransport { 25e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate/* STOPSHIP - don't ship with this comment in place 26e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate Things the transport interface has to do: 27e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 1. set up the connection to the destination 28e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - set up encryption 29e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - for Google cloud, log in using the user's gaia credential or whatever 307b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate - for adb, just set up the all-in-one destination file 31e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 2. send each app's backup transaction 32e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - parse the data file for key/value pointers etc 33e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - send key/blobsize set to the Google cloud, get back quota ok/rejected response 34e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - sd/adb doesn't preflight; no per-app quota 35e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - app's entire change is essentially atomic 36e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - cloud transaction encrypts then sends each key/value pair separately; we already 37e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate parsed the data when preflighting so we don't have to again here 38e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - sd target streams raw data into encryption envelope then to sd? 39e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 3. shut down connection to destination 40e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate - cloud: tear down connection etc 417b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate - adb: close the file 42e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate*/ 43e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 445cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Ask the transport where, on local device storage, to keep backup state blobs. 455cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * This is per-transport so that mock transports used for testing can coexist with 465cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * "live" backup services without interfering with the live bookkeeping. The 475cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * returned string should be a name that is expected to be unambiguous among all 485cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * available backup transports; the name of the class implementing the transport 495cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * is a good choice. 505cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * 515cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * @return A unique name, suitable for use as a file or directory name, that the 525cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * Backup Manager could use to disambiguate state files associated with 535cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate * different backup transports. 545cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate */ 555cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate String transportDirName(); 565cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate 575cb400bd72726c22f641f334951b35ce2ddcfeefChristopher Tate /** 58df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Verify that this is a suitable time for a backup pass. This should return zero 59aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * if a backup is reasonable right now, some positive value otherwise. This method 60aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * will be called outside of the {@link #startSession}/{@link #endSession} pair. 61df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * 62aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * <p>If this is not a suitable time for a backup, the transport should return a 63df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * backoff delay, in milliseconds, after which the Backup Manager should try again. 64aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * 65aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * @return Zero if this is a suitable time for a backup pass, or a positive time delay 66aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * in milliseconds to suggest deferring the backup pass for a while. 67df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate */ 68df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate long requestBackupTime(); 69df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate 70df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate /** 71efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Send one application's data to the backup destination. The transport may send 72efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 73efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * must be called to ensure the data is sent and recorded successfully. 74e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 75b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being backed up. 76b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This specifically includes the signature list for the package. 77e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @param data The data stream that resulted from invoking the application's 787b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * BackupService.doBackup() method. This may be a pipe rather than a file on 797b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * persistent media, so it may not be seekable. 80efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return false if errors occurred (the backup should be aborted and rescheduled), 81efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * true if everything is OK so far (but {@link #finishBackup} must be called). 82e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 83efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor boolean performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 84efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 85efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 86ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Erase the give application's data from the backup destination. This clears 87ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * out the given package's data from the current backup set, making it as though 88ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * the app had never yet been backed up. After this is called, {@link finishBackup} 89ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * must be called to ensure that the operation is recorded successfully. 90efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * 91efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return false if errors occurred (the backup should be aborted and rescheduled), 92efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * true if everything is OK so far (but {@link #finishBackup} must be called). 93efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 94ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate boolean clearBackupData(in PackageInfo packageInfo); 95ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate 96ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate /** 97ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * Finish sending application data to the backup destination. This must be 98ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * called after {@link #performBackup} or {@link clearBackupData} to ensure that 99ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * all data is sent. Only when this method returns true can a backup be assumed 100ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * to have succeeded. 101ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * 102ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * @return false if errors occurred (the backup should be aborted and rescheduled), 103ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate * true if everything is OK. 104ee0e78af5af3bf23dd928fe5e0ebeb39157eaf66Christopher Tate */ 105efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor boolean finishBackup(); 106e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 107e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 108b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * Get the set of backups currently available over this transport. 109b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 110efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return Descriptions of the set of restore images available for this device, 111efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the attempt should be rescheduled). 112b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate **/ 1139b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tate RestoreSet[] getAvailableRestoreSets(); 114b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 115b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 116efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Start restoring application data from backup. After calling this function, 117efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 118efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * to walk through the actual application data. 119b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 120df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * @param token A backup token as returned by {@link #getAvailableRestoreSets}. 121efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param packages List of applications to restore (if data is available). 122efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Application data will be restored in the order given. 123efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return false if errors occurred (the restore should be aborted and rescheduled), 124efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * true if everything is OK so far (go ahead and call {@link #nextRestorePackage}). 125b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 126efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor boolean startRestore(long token, in PackageInfo[] packages); 127b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 128b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 129efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the package name of the next application with data in the backup store. 130efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return The name of one of the packages supplied to {@link #startRestore}, 131efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or "" (the empty string) if no more backup data is available, 132efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * or null if an error occurred (the restore should be aborted and rescheduled). 133b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 134efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor String nextRestorePackage(); 135b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 136b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 137efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * Get the data for the application returned by {@link #nextRestorePackage}. 138efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @param data An open, writable file into which the backup data should be stored. 139efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * @return false if errors occurred (the restore should be aborted and rescheduled), 140efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * true if everything is OK so far (go ahead and call {@link #nextRestorePackage}). 141efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor */ 142efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor boolean getRestoreData(in ParcelFileDescriptor outFd); 143efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor 144efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor /** 145efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * End a restore session (aborting any in-process data transfer as necessary), 146efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor * freeing any resources and connections used during the restore process. 147e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 148efe52647f6b41993be43a5f47d1178bb0468cec8Dan Egnor void finishRestore(); 149487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 150