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 19 import android.app.backup.RestoreSet; 20 import android.content.Intent; 21 import android.content.pm.PackageInfo; 22 import android.os.ParcelFileDescriptor; 23 24 /** {@hide} */ 25 interface IBackupTransport { 26 /** 27 * Ask the transport for an Intent that can be used to launch any internal 28 * configuration Activity that it wishes to present. For example, the transport 29 * may offer a UI for allowing the user to supply login credentials for the 30 * transport's off-device backend. 31 * 32 * If the transport does not supply any user-facing configuration UI, it should 33 * return null from this method. 34 * 35 * @return An Intent that can be passed to Context.startActivity() in order to 36 * launch the transport's configuration UI. This method will return null 37 * if the transport does not offer any user-facing configuration UI. 38 */ configurationIntent()39 Intent configurationIntent(); 40 41 /** 42 * On demand, supply a one-line string that can be shown to the user that 43 * describes the current backend destination. For example, a transport that 44 * can potentially associate backup data with arbitrary user accounts should 45 * include the name of the currently-active account here. 46 * 47 * @return A string describing the destination to which the transport is currently 48 * sending data. This method should not return null. 49 */ currentDestinationString()50 String currentDestinationString(); 51 52 /** 53 * Ask the transport where, on local device storage, to keep backup state blobs. 54 * This is per-transport so that mock transports used for testing can coexist with 55 * "live" backup services without interfering with the live bookkeeping. The 56 * returned string should be a name that is expected to be unambiguous among all 57 * available backup transports; the name of the class implementing the transport 58 * is a good choice. 59 * 60 * @return A unique name, suitable for use as a file or directory name, that the 61 * Backup Manager could use to disambiguate state files associated with 62 * different backup transports. 63 */ transportDirName()64 String transportDirName(); 65 66 /** 67 * Verify that this is a suitable time for a backup pass. This should return zero 68 * if a backup is reasonable right now, some positive value otherwise. This method 69 * will be called outside of the {@link #startSession}/{@link #endSession} pair. 70 * 71 * <p>If this is not a suitable time for a backup, the transport should return a 72 * backoff delay, in milliseconds, after which the Backup Manager should try again. 73 * 74 * @return Zero if this is a suitable time for a backup pass, or a positive time delay 75 * in milliseconds to suggest deferring the backup pass for a while. 76 */ requestBackupTime()77 long requestBackupTime(); 78 79 /** 80 * Initialize the server side storage for this device, erasing all stored data. 81 * The transport may send the request immediately, or may buffer it. After 82 * this is called, {@link #finishBackup} must be called to ensure the request 83 * is sent and received successfully. 84 * 85 * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far) or 86 * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure). 87 */ initializeDevice()88 int initializeDevice(); 89 90 /** 91 * Send one application's data to the backup destination. The transport may send 92 * the data immediately, or may buffer it. After this is called, {@link #finishBackup} 93 * must be called to ensure the data is sent and recorded successfully. 94 * 95 * @param packageInfo The identity of the application whose data is being backed up. 96 * This specifically includes the signature list for the package. 97 * @param data The data stream that resulted from invoking the application's 98 * BackupService.doBackup() method. This may be a pipe rather than a file on 99 * persistent media, so it may not be seekable. 100 * @param wipeAllFirst When true, <i>all</i> backed-up data for the current device/account 101 * will be erased prior to the storage of the data provided here. The purpose of this 102 * is to provide a guarantee that no stale data exists in the restore set when the 103 * device begins providing backups. 104 * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far), 105 * {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or 106 * {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has 107 * become lost due to inactive expiry or some other reason and needs re-initializing) 108 */ performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd)109 int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd); 110 111 /** 112 * Erase the give application's data from the backup destination. This clears 113 * out the given package's data from the current backup set, making it as though 114 * the app had never yet been backed up. After this is called, {@link finishBackup} 115 * must be called to ensure that the operation is recorded successfully. 116 * 117 * @return the same error codes as {@link #performBackup}. 118 */ clearBackupData(in PackageInfo packageInfo)119 int clearBackupData(in PackageInfo packageInfo); 120 121 /** 122 * Finish sending application data to the backup destination. This must be 123 * called after {@link #performBackup} or {@link clearBackupData} to ensure that 124 * all data is sent. Only when this method returns true can a backup be assumed 125 * to have succeeded. 126 * 127 * @return the same error codes as {@link #performBackup}. 128 */ finishBackup()129 int finishBackup(); 130 131 /** 132 * Get the set of all backups currently available over this transport. 133 * 134 * @return Descriptions of the set of restore images available for this device, 135 * or null if an error occurred (the attempt should be rescheduled). 136 **/ getAvailableRestoreSets()137 RestoreSet[] getAvailableRestoreSets(); 138 139 /** 140 * Get the identifying token of the backup set currently being stored from 141 * this device. This is used in the case of applications wishing to restore 142 * their last-known-good data. 143 * 144 * @return A token that can be passed to {@link #startRestore}, or 0 if there 145 * is no backup set available corresponding to the current device state. 146 */ getCurrentRestoreSet()147 long getCurrentRestoreSet(); 148 149 /** 150 * Start restoring application data from backup. After calling this function, 151 * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData} 152 * to walk through the actual application data. 153 * 154 * @param token A backup token as returned by {@link #getAvailableRestoreSets} 155 * or {@link #getCurrentRestoreSet}. 156 * @param packages List of applications to restore (if data is available). 157 * Application data will be restored in the order given. 158 * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call 159 * {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR} 160 * (an error occurred, the restore should be aborted and rescheduled). 161 */ startRestore(long token, in PackageInfo[] packages)162 int startRestore(long token, in PackageInfo[] packages); 163 164 /** 165 * Get the package name of the next application with data in the backup store. 166 * @return The name of one of the packages supplied to {@link #startRestore}, 167 * or "" (the empty string) if no more backup data is available, 168 * or null if an error occurred (the restore should be aborted and rescheduled). 169 */ nextRestorePackage()170 String nextRestorePackage(); 171 172 /** 173 * Get the data for the application returned by {@link #nextRestorePackage}. 174 * @param data An open, writable file into which the backup data should be stored. 175 * @return the same error codes as {@link #nextRestorePackage}. 176 */ getRestoreData(in ParcelFileDescriptor outFd)177 int getRestoreData(in ParcelFileDescriptor outFd); 178 179 /** 180 * End a restore session (aborting any in-process data transfer as necessary), 181 * freeing any resources and connections used during the restore process. 182 */ finishRestore()183 void finishRestore(); 184 } 185