IBackupTransport.aidl revision aa088447baadd2e0bbcfd18cc529645610c13ddc
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 /** 44df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Verify that this is a suitable time for a backup pass. This should return zero 45aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * if a backup is reasonable right now, some positive value otherwise. This method 46aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * will be called outside of the {@link #startSession}/{@link #endSession} pair. 47df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * 48aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * <p>If this is not a suitable time for a backup, the transport should return a 49df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * backoff delay, in milliseconds, after which the Backup Manager should try again. 50aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * 51aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * @return Zero if this is a suitable time for a backup pass, or a positive time delay 52aa088447baadd2e0bbcfd18cc529645610c13ddcChristopher Tate * in milliseconds to suggest deferring the backup pass for a while. 53df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate */ 54df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate long requestBackupTime(); 55df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate 56df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate /** 57e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * Establish a connection to the back-end data repository, if necessary. If the transport 58e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * needs to initialize state that is not tied to individual applications' backup operations, 59e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * this is where it should be done. 60e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 61e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @return Zero on success; a nonzero error code on failure. 62e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 63e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate int startSession(); 64e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 65e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 66e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * Send one application's data to the backup destination. 67e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 68b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being backed up. 69b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This specifically includes the signature list for the package. 70e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @param data The data stream that resulted from invoking the application's 717b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * BackupService.doBackup() method. This may be a pipe rather than a file on 727b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate * persistent media, so it may not be seekable. 73e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @return Zero on success; a nonzero error code on failure. 74e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 757b88128e08ba45b071cd714dad9681ce66920d32Christopher Tate int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor data); 76e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate 77e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate /** 78b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * Get the set of backups currently available over this transport. 79b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 80df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * @return Descriptions of the set of restore images available for this device. 81b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate **/ 829b3905c4a25f2d785ce7535d1f2e1540b46bb561Christopher Tate RestoreSet[] getAvailableRestoreSets(); 83b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 84b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 85df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Get the set of applications from a given restore image. 86b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 87df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * @param token A backup token as returned by {@link #getAvailableRestoreSets}. 88b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @return An array of PackageInfo objects describing all of the applications 89df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * available for restore from this restore image. This should include the list 90b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * of signatures for each package so that the Backup Manager can filter using that 91b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * information. 92b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 93b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate PackageInfo[] getAppSet(int token); 94b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 95b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 96df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * Retrieve one application's data from the backing store. 97b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * 98b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param token The backup record from which a restore is being requested. 99b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @param packageInfo The identity of the application whose data is being restored. 100b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * This must include the signature list for the package; it is up to the transport 101b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * to verify that the requested app's signatures match the saved backup record 102b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * because the transport cannot necessarily trust the client device. 103df01deaacff82b918b4f0ba774d5ad3087543629Christopher Tate * @param data An open, writable file into which the backup image should be stored. 104b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate * @return Zero on success; a nonzero error code on failure. 105b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate */ 106b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate int getRestoreData(int token, in PackageInfo packageInfo, in ParcelFileDescriptor data); 107b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate 108b4a6188a74273611abcae05f3a3b1f0547548301Christopher Tate /** 109e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * Terminate the backup session, closing files, freeing memory, and cleaning up whatever 110e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * other state the transport required. 111e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * 112e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * @return Zero on success; a nonzero error code on failure. Even on failure, the session 113e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate * is torn down and must be restarted if another backup is attempted. 114e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate */ 115e10be807872a88f872bef96d1fd5a1d9f78af282Christopher Tate int endSession(); 116487529a70cd1479ae8d6bbfb356be7e72542c185Christopher Tate} 117