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