IBackupTransport.aidl revision efe52647f6b41993be43a5f47d1178bb0468cec8 
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, some positive value otherwise.  This method
46     * will be called outside of the {@link #startSession}/{@link #endSession} pair.
47     *
48     * <p>If this is not a suitable time for a backup, the transport should return a
49     * backoff delay, in milliseconds, after which the Backup Manager should try again.
50     *
51     * @return Zero if this is a suitable time for a backup pass, or a positive time delay
52     *   in milliseconds to suggest deferring the backup pass for a while.
53     */
54    long requestBackupTime();
55
56    /**
57     * Send one application's data to the backup destination.  The transport may send
58     * the data immediately, or may buffer it.  After this is called, {@link #finishBackup}
59     * must be called to ensure the data is sent and recorded successfully.
60     *
61     * @param packageInfo The identity of the application whose data is being backed up.
62     *   This specifically includes the signature list for the package.
63     * @param data The data stream that resulted from invoking the application's
64     *   BackupService.doBackup() method.  This may be a pipe rather than a file on
65     *   persistent media, so it may not be seekable.
66     * @return false if errors occurred (the backup should be aborted and rescheduled),
67     *   true if everything is OK so far (but {@link #finishBackup} must be called).
68     */
69    boolean performBackup(in PackageInfo packageInfo, in ParcelFileDescriptor inFd);
70
71    /**
72     * Finish sending application data to the backup destination.  This must be
73     * called after {@link #performBackup} to ensure that all data is sent.  Only
74     * when this method returns true can the backup be assumed to have succeeded.
75     *
76     * @return false if errors occurred (the backup should be aborted and rescheduled),
77     *   true if everything is OK so far (but {@link #finishBackup} must be called).
78     */
79    boolean finishBackup();
80
81    /**
82     * Get the set of backups currently available over this transport.
83     *
84     * @return Descriptions of the set of restore images available for this device,
85     *   or null if an error occurred (the attempt should be rescheduled).
86     **/
87    RestoreSet[] getAvailableRestoreSets();
88
89    /**
90     * Start restoring application data from backup.  After calling this function,
91     * alternate calls to {@link #nextRestorePackage} and {@link #nextRestoreData}
92     * to walk through the actual application data.
93     *
94     * @param token A backup token as returned by {@link #getAvailableRestoreSets}.
95     * @param packages List of applications to restore (if data is available).
96     *   Application data will be restored in the order given.
97     * @return false if errors occurred (the restore should be aborted and rescheduled),
98     *   true if everything is OK so far (go ahead and call {@link #nextRestorePackage}).
99     */
100    boolean startRestore(long token, in PackageInfo[] packages);
101
102    /**
103     * Get the package name of the next application with data in the backup store.
104     * @return The name of one of the packages supplied to {@link #startRestore},
105     *   or "" (the empty string) if no more backup data is available,
106     *   or null if an error occurred (the restore should be aborted and rescheduled).
107     */
108    String nextRestorePackage();
109
110    /**
111     * Get the data for the application returned by {@link #nextRestorePackage}.
112     * @param data An open, writable file into which the backup data should be stored.
113     * @return false if errors occurred (the restore should be aborted and rescheduled),
114     *   true if everything is OK so far (go ahead and call {@link #nextRestorePackage}).
115     */
116    boolean getRestoreData(in ParcelFileDescriptor outFd);
117
118    /**
119     * End a restore session (aborting any in-process data transfer as necessary),
120     * freeing any resources and connections used during the restore process.
121     */
122    void finishRestore();
123}
124