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