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
17package com.android.internal.backup;
18
19import android.app.backup.RestoreDescription;
20import android.app.backup.RestoreSet;
21import android.content.Intent;
22import android.content.pm.PackageInfo;
23import android.os.ParcelFileDescriptor;
24
25/** {@hide} */
26interface IBackupTransport {
27    /**
28     * Ask the transport for the name under which it should be registered.  This will
29     * typically be its host service's component name, but need not be.
30     */
31    String name();
32
33	/**
34	 * Ask the transport for an Intent that can be used to launch any internal
35	 * configuration Activity that it wishes to present.  For example, the transport
36	 * may offer a UI for allowing the user to supply login credentials for the
37	 * transport's off-device backend.
38	 *
39	 * If the transport does not supply any user-facing configuration UI, it should
40	 * return null from this method.
41	 *
42	 * @return An Intent that can be passed to Context.startActivity() in order to
43	 *         launch the transport's configuration UI.  This method will return null
44	 *         if the transport does not offer any user-facing configuration UI.
45	 */
46	Intent configurationIntent();
47
48	/**
49	 * On demand, supply a one-line string that can be shown to the user that
50	 * describes the current backend destination.  For example, a transport that
51	 * can potentially associate backup data with arbitrary user accounts should
52	 * include the name of the currently-active account here.
53	 *
54	 * @return A string describing the destination to which the transport is currently
55	 *         sending data.  This method should not return null.
56	 */
57	String currentDestinationString();
58
59    /**
60     * Ask the transport for an Intent that can be used to launch a more detailed
61     * secondary data management activity.  For example, the configuration intent might
62     * be one for allowing the user to select which account they wish to associate
63     * their backups with, and the management intent might be one which presents a
64     * UI for managing the data on the backend.
65     *
66     * <p>In the Settings UI, the configuration intent will typically be invoked
67     * when the user taps on the preferences item labeled with the current
68     * destination string, and the management intent will be placed in an overflow
69     * menu labelled with the management label string.
70     *
71     * <p>If the transport does not supply any user-facing data management
72     * UI, then it should return {@code null} from this method.
73     *
74     * @return An intent that can be passed to Context.startActivity() in order to
75     *         launch the transport's data-management UI.  This method will return
76     *         {@code null} if the transport does not offer any user-facing data
77     *         management UI.
78     */
79    Intent dataManagementIntent();
80
81    /**
82     * On demand, supply a short string that can be shown to the user as the label
83     * on an overflow menu item used to invoked the data management UI.
84     *
85     * @return A string to be used as the label for the transport's data management
86     *         affordance.  If the transport supplies a data management intent, this
87     *         method must not return {@code null}.
88     */
89    String dataManagementLabel();
90
91    /**
92     * Ask the transport where, on local device storage, to keep backup state blobs.
93     * This is per-transport so that mock transports used for testing can coexist with
94     * "live" backup services without interfering with the live bookkeeping.  The
95     * returned string should be a name that is expected to be unambiguous among all
96     * available backup transports; the name of the class implementing the transport
97     * is a good choice.
98     *
99     * @return A unique name, suitable for use as a file or directory name, that the
100     *         Backup Manager could use to disambiguate state files associated with
101     *         different backup transports.
102     */
103    String transportDirName();
104
105    /**
106     * Verify that this is a suitable time for a backup pass.  This should return zero
107     * if a backup is reasonable right now, some positive value otherwise.  This method
108     * will be called outside of the {@link #startSession}/{@link #endSession} pair.
109     *
110     * <p>If this is not a suitable time for a backup, the transport should return a
111     * backoff delay, in milliseconds, after which the Backup Manager should try again.
112     *
113     * @return Zero if this is a suitable time for a backup pass, or a positive time delay
114     *   in milliseconds to suggest deferring the backup pass for a while.
115     */
116    long requestBackupTime();
117
118    /**
119     * Initialize the server side storage for this device, erasing all stored data.
120     * The transport may send the request immediately, or may buffer it.  After
121     * this is called, {@link #finishBackup} must be called to ensure the request
122     * is sent and received successfully.
123     *
124     * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far) or
125     *   {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure).
126     */
127    int initializeDevice();
128
129    /**
130     * Send one application's data to the backup destination.  The transport may send
131     * the data immediately, or may buffer it.  After this is called, {@link #finishBackup}
132     * must be called to ensure the data is sent and recorded successfully.
133     *
134     * @param packageInfo The identity of the application whose data is being backed up.
135     *   This specifically includes the signature list for the package.
136     * @param data The data stream that resulted from invoking the application's
137     *   BackupService.doBackup() method.  This may be a pipe rather than a file on
138     *   persistent media, so it may not be seekable.
139     * @param wipeAllFirst When true, <i>all</i> backed-up data for the current device/account
140     *   will be erased prior to the storage of the data provided here.  The purpose of this
141     *   is to provide a guarantee that no stale data exists in the restore set when the
142     *   device begins providing backups.
143     * @return one of {@link BackupConstants#TRANSPORT_OK} (OK so far),
144     *  {@link BackupConstants#TRANSPORT_ERROR} (on network error or other failure), or
145     *  {@link BackupConstants#TRANSPORT_NOT_INITIALIZED} (if the backend dataset has
146     *  become lost due to inactive expiry or some other reason and needs re-initializing)
147     */
148    int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd);
149
150    /**
151     * Erase the give application's data from the backup destination.  This clears
152     * out the given package's data from the current backup set, making it as though
153     * the app had never yet been backed up.  After this is called, {@link finishBackup}
154     * must be called to ensure that the operation is recorded successfully.
155     *
156     * @return the same error codes as {@link #performBackup}.
157     */
158    int clearBackupData(in PackageInfo packageInfo);
159
160    /**
161     * Finish sending application data to the backup destination.  This must be
162     * called after {@link #performBackup} or {@link clearBackupData} to ensure that
163     * all data is sent.  Only when this method returns true can a backup be assumed
164     * to have succeeded.
165     *
166     * @return the same error codes as {@link #performBackup}.
167     */
168    int finishBackup();
169
170    /**
171     * Get the set of all backups currently available over this transport.
172     *
173     * @return Descriptions of the set of restore images available for this device,
174     *   or null if an error occurred (the attempt should be rescheduled).
175     **/
176    RestoreSet[] getAvailableRestoreSets();
177
178    /**
179     * Get the identifying token of the backup set currently being stored from
180     * this device.  This is used in the case of applications wishing to restore
181     * their last-known-good data.
182     *
183     * @return A token that can be passed to {@link #startRestore}, or 0 if there
184     *   is no backup set available corresponding to the current device state.
185     */
186    long getCurrentRestoreSet();
187
188    /**
189     * Start restoring application data from backup.  After calling this function,
190     * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData}
191     * to walk through the actual application data.
192     *
193     * @param token A backup token as returned by {@link #getAvailableRestoreSets}
194     *   or {@link #getCurrentRestoreSet}.
195     * @param packages List of applications to restore (if data is available).
196     *   Application data will be restored in the order given.
197     * @return One of {@link BackupConstants#TRANSPORT_OK} (OK so far, call
198     *   {@link #nextRestorePackage}) or {@link BackupConstants#TRANSPORT_ERROR}
199     *   (an error occurred, the restore should be aborted and rescheduled).
200     */
201    int startRestore(long token, in PackageInfo[] packages);
202
203    /**
204     * Get the package name of the next application with data in the backup store, plus
205     * a description of the structure of the restored archive: either TYPE_KEY_VALUE for
206     * an original-API key/value dataset, or TYPE_FULL_STREAM for a tarball-type archive stream.
207     *
208     * <p>If the package name in the returned RestoreDescription object is the singleton
209     * {@link RestoreDescription#NO_MORE_PACKAGES}, it indicates that no further data is available
210     * in the current restore session: all packages described in startRestore() have been
211     * processed.
212     *
213     * <p>If this method returns {@code null}, it means that a transport-level error has
214     * occurred and the entire restore operation should be abandoned.
215     *
216     * @return A RestoreDescription object containing the name of one of the packages
217     *   supplied to {@link #startRestore} plus an indicator of the data type of that
218     *   restore data; or {@link RestoreDescription#NO_MORE_PACKAGES} to indicate that
219     *   no more packages can be restored in this session; or {@code null} to indicate
220     *   a transport-level error.
221     */
222    RestoreDescription nextRestorePackage();
223
224    /**
225     * Get the data for the application returned by {@link #nextRestorePackage}.
226     * @param data An open, writable file into which the backup data should be stored.
227     * @return the same error codes as {@link #startRestore}.
228     */
229    int getRestoreData(in ParcelFileDescriptor outFd);
230
231    /**
232     * End a restore session (aborting any in-process data transfer as necessary),
233     * freeing any resources and connections used during the restore process.
234     */
235    void finishRestore();
236
237    // full backup stuff
238
239    long requestFullBackupTime();
240    int performFullBackup(in PackageInfo targetPackage, in ParcelFileDescriptor socket);
241    int sendBackupData(int numBytes);
242    void cancelFullBackup();
243
244    // full restore stuff
245
246    /**
247     * Ask the transport to provide data for the "current" package being restored.  This
248     * is the package that was just reported by {@link #nextRestorePackage()} as having
249     * {@link RestoreDescription#TYPE_FULL_STREAM} data.
250     *
251     * The transport writes some data to the socket supplied to this call, and returns
252     * the number of bytes written.  The system will then read that many bytes and
253     * stream them to the application's agent for restore, then will call this method again
254     * to receive the next chunk of the archive.  This sequence will be repeated until the
255     * transport returns zero indicating that all of the package's data has been delivered
256     * (or returns a negative value indicating some sort of hard error condition at the
257     * transport level).
258     *
259     * <p>After this method returns zero, the system will then call
260     * {@link #getNextFullRestorePackage()} to begin the restore process for the next
261     * application, and the sequence begins again.
262     *
263     * <p>The transport should always close this socket when returning from this method.
264     * Do not cache this socket across multiple calls or you may leak file descriptors.
265     *
266     * @param socket The file descriptor that the transport will use for delivering the
267     *    streamed archive.  The transport must close this socket in all cases when returning
268     *    from this method.
269     * @return 0 when no more data for the current package is available.  A positive value
270     *    indicates the presence of that many bytes to be delivered to the app.  Any negative
271     *    return value is treated as equivalent to {@link BackupTransport#TRANSPORT_ERROR},
272     *    indicating a fatal error condition that precludes further restore operations
273     *    on the current dataset.
274     */
275    int getNextFullRestoreDataChunk(in ParcelFileDescriptor socket);
276
277    /**
278     * If the OS encounters an error while processing {@link RestoreDescription#TYPE_FULL_STREAM}
279     * data for restore, it will invoke this method to tell the transport that it should
280     * abandon the data download for the current package.  The OS will then either call
281     * {@link #nextRestorePackage()} again to move on to restoring the next package in the
282     * set being iterated over, or will call {@link #finishRestore()} to shut down the restore
283     * operation.
284     *
285     * @return {@link #TRANSPORT_OK} if the transport was successful in shutting down the
286     *    current stream cleanly, or {@link #TRANSPORT_ERROR} to indicate a serious
287     *    transport-level failure.  If the transport reports an error here, the entire restore
288     *    operation will immediately be finished with no further attempts to restore app data.
289     */
290    int abortFullRestore();
291
292}
293