Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2009 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package com.android.internal.backup; |
| 18 | |
Christopher Tate | 9b3905c | 2009-06-08 15:24:01 -0700 | [diff] [blame] | 19 | import android.backup.RestoreSet; |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 20 | import android.content.pm.PackageInfo; |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 21 | import android.os.ParcelFileDescriptor; |
| 22 | |
Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 23 | /** {@hide} */ |
| 24 | interface IBackupTransport { |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 25 | /* STOPSHIP - don't ship with this comment in place |
| 26 | Things the transport interface has to do: |
| 27 | 1. set up the connection to the destination |
| 28 | - set up encryption |
| 29 | - for Google cloud, log in using the user's gaia credential or whatever |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 30 | - for adb, just set up the all-in-one destination file |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 31 | 2. send each app's backup transaction |
| 32 | - parse the data file for key/value pointers etc |
| 33 | - send key/blobsize set to the Google cloud, get back quota ok/rejected response |
| 34 | - sd/adb doesn't preflight; no per-app quota |
| 35 | - app's entire change is essentially atomic |
| 36 | - cloud transaction encrypts then sends each key/value pair separately; we already |
| 37 | parsed the data when preflighting so we don't have to again here |
| 38 | - sd target streams raw data into encryption envelope then to sd? |
| 39 | 3. shut down connection to destination |
| 40 | - cloud: tear down connection etc |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 41 | - adb: close the file |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 42 | */ |
| 43 | /** |
Christopher Tate | 5cb400b | 2009-06-25 16:03:14 -0700 | [diff] [blame^] | 44 | * Ask the transport where, on local device storage, to keep backup state blobs. |
| 45 | * This is per-transport so that mock transports used for testing can coexist with |
| 46 | * "live" backup services without interfering with the live bookkeeping. The |
| 47 | * returned string should be a name that is expected to be unambiguous among all |
| 48 | * available backup transports; the name of the class implementing the transport |
| 49 | * is a good choice. |
| 50 | * |
| 51 | * @return A unique name, suitable for use as a file or directory name, that the |
| 52 | * Backup Manager could use to disambiguate state files associated with |
| 53 | * different backup transports. |
| 54 | */ |
| 55 | String transportDirName(); |
| 56 | |
| 57 | /** |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 58 | * Verify that this is a suitable time for a backup pass. This should return zero |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 59 | * if a backup is reasonable right now, some positive value otherwise. This method |
| 60 | * will be called outside of the {@link #startSession}/{@link #endSession} pair. |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 61 | * |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 62 | * <p>If this is not a suitable time for a backup, the transport should return a |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 63 | * backoff delay, in milliseconds, after which the Backup Manager should try again. |
Christopher Tate | aa08844 | 2009-06-16 18:25:46 -0700 | [diff] [blame] | 64 | * |
| 65 | * @return Zero if this is a suitable time for a backup pass, or a positive time delay |
| 66 | * in milliseconds to suggest deferring the backup pass for a while. |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 67 | */ |
| 68 | long requestBackupTime(); |
| 69 | |
| 70 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 71 | * Send one application's data to the backup destination. The transport may send |
| 72 | * the data immediately, or may buffer it. After this is called, {@link #finishBackup} |
| 73 | * must be called to ensure the data is sent and recorded successfully. |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 74 | * |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 75 | * @param packageInfo The identity of the application whose data is being backed up. |
| 76 | * This specifically includes the signature list for the package. |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 77 | * @param data The data stream that resulted from invoking the application's |
Christopher Tate | 7b88128 | 2009-06-07 13:52:37 -0700 | [diff] [blame] | 78 | * BackupService.doBackup() method. This may be a pipe rather than a file on |
| 79 | * persistent media, so it may not be seekable. |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 80 | * @return false if errors occurred (the backup should be aborted and rescheduled), |
| 81 | * true if everything is OK so far (but {@link #finishBackup} must be called). |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 82 | */ |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 83 | boolean performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); |
| 84 | |
| 85 | /** |
| 86 | * Finish sending application data to the backup destination. This must be |
| 87 | * called after {@link #performBackup} to ensure that all data is sent. Only |
| 88 | * when this method returns true can the backup be assumed to have succeeded. |
| 89 | * |
| 90 | * @return false if errors occurred (the backup should be aborted and rescheduled), |
| 91 | * true if everything is OK so far (but {@link #finishBackup} must be called). |
| 92 | */ |
| 93 | boolean finishBackup(); |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 94 | |
| 95 | /** |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 96 | * Get the set of backups currently available over this transport. |
| 97 | * |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 98 | * @return Descriptions of the set of restore images available for this device, |
| 99 | * or null if an error occurred (the attempt should be rescheduled). |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 100 | **/ |
Christopher Tate | 9b3905c | 2009-06-08 15:24:01 -0700 | [diff] [blame] | 101 | RestoreSet[] getAvailableRestoreSets(); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 102 | |
| 103 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 104 | * Start restoring application data from backup. After calling this function, |
| 105 | * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} |
| 106 | * to walk through the actual application data. |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 107 | * |
Christopher Tate | df01dea | 2009-06-09 20:45:02 -0700 | [diff] [blame] | 108 | * @param token A backup token as returned by {@link #getAvailableRestoreSets}. |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 109 | * @param packages List of applications to restore (if data is available). |
| 110 | * Application data will be restored in the order given. |
| 111 | * @return false if errors occurred (the restore should be aborted and rescheduled), |
| 112 | * true if everything is OK so far (go ahead and call {@link #nextRestorePackage}). |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 113 | */ |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 114 | boolean startRestore(long token, in PackageInfo[] packages); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 115 | |
| 116 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 117 | * Get the package name of the next application with data in the backup store. |
| 118 | * @return The name of one of the packages supplied to {@link #startRestore}, |
| 119 | * or "" (the empty string) if no more backup data is available, |
| 120 | * or null if an error occurred (the restore should be aborted and rescheduled). |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 121 | */ |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 122 | String nextRestorePackage(); |
Christopher Tate | b4a6188 | 2009-06-07 15:19:32 -0700 | [diff] [blame] | 123 | |
| 124 | /** |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 125 | * Get the data for the application returned by {@link #nextRestorePackage}. |
| 126 | * @param data An open, writable file into which the backup data should be stored. |
| 127 | * @return false if errors occurred (the restore should be aborted and rescheduled), |
| 128 | * true if everything is OK so far (go ahead and call {@link #nextRestorePackage}). |
Christopher Tate | e10be80 | 2009-05-07 17:22:16 -0700 | [diff] [blame] | 129 | */ |
Dan Egnor | efe5264 | 2009-06-24 00:16:33 -0700 | [diff] [blame] | 130 | boolean getRestoreData(in ParcelFileDescriptor outFd); |
| 131 | |
| 132 | /** |
| 133 | * End a restore session (aborting any in-process data transfer as necessary), |
| 134 | * freeing any resources and connections used during the restore process. |
| 135 | */ |
| 136 | void finishRestore(); |
Christopher Tate | 487529a | 2009-04-29 14:03:25 -0700 | [diff] [blame] | 137 | } |