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