IBackupTransport.aidl revision 8c850b792f2d371fd8a4aff146d9d757ee982539 
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.content.pm.PackageInfo;
20import android.os.Bundle;
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     * Establish a connection to the back-end data repository, if necessary.  If the transport
45     * needs to initialize state that is not tied to individual applications' backup operations,
46     * this is where it should be done.
47     *
48     * @return Zero on success; a nonzero error code on failure.
49     */
50    int startSession();
51
52    /**
53     * Send one application's data to the backup destination.
54     *
55     * @param packageInfo The identity of the application whose data is being backed up.
56     *   This specifically includes the signature list for the package.
57     * @param data The data stream that resulted from invoking the application's
58     *   BackupService.doBackup() method.  This may be a pipe rather than a file on
59     *   persistent media, so it may not be seekable.
60     * @return Zero on success; a nonzero error code on failure.
61     */
62    int performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor data);
63
64    /**
65     * Get the set of backups currently available over this transport.
66     *
67     * @return A bundle containing two elements:  an int array under the key
68     *   "tokens" whose entries are a transport-private identifier for each backup set;
69     *   and a String array under the key "names" whose entries are the user-meaningful
70     *   names corresponding to the backup sets at each index in the tokens array.
71     **/
72    Bundle getAvailableRestoreSets();
73
74    /**
75     * Get the set of applications from a given backup image.
76     *
77     * @param token A backup token as returned by {@link availableBackups}.
78     * @return An array of PackageInfo objects describing all of the applications
79     *   available for restore from the given backup set.  This should include the list
80     *   of signatures for each package so that the Backup Manager can filter using that
81     *   information.
82     */
83    PackageInfo[] getAppSet(int token);
84
85    /**
86     * Retrieve one application's data from the backup destination.
87     *
88     * @param token The backup record from which a restore is being requested.
89     * @param packageInfo The identity of the application whose data is being restored.
90     *   This must include the signature list for the package; it is up to the transport
91     *   to verify that the requested app's signatures match the saved backup record
92     *   because the transport cannot necessarily trust the client device.
93     * @param data An open, writeable file into which the backup image should be stored.
94     * @return Zero on success; a nonzero error code on failure.
95     */
96    int getRestoreData(int token, in PackageInfo packageInfo, in ParcelFileDescriptor data);
97
98    /**
99     * Terminate the backup session, closing files, freeing memory, and cleaning up whatever
100     * other state the transport required.
101     *
102     * @return Zero on success; a nonzero error code on failure.  Even on failure, the session
103     *         is torn down and must be restarted if another backup is attempted.
104     */
105    int endSession();
106}
107