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 android.app.backup;
18
19import android.app.backup.RestoreSet;
20import android.app.backup.IRestoreObserver;
21import android.app.backup.IBackupManagerMonitor;
22/**
23 * Binder interface used by clients who wish to manage a restore operation.  Every
24 * method in this interface requires the android.permission.BACKUP permission.
25 *
26 * {@hide}
27 */
28interface IRestoreSession {
29    /**
30     * Ask the current transport what the available restore sets are.
31     *
32     * @param observer This binder points to an object whose onRestoreSetsAvailable()
33     *   method will be called to supply the results of the transport's lookup.
34     * @param monitor If non null the binder will send important events to this monitor.
35     * @return Zero on success; nonzero on error.  The observer will only receive a
36     *   result callback if this method returned zero.
37     */
38    int getAvailableRestoreSets(IRestoreObserver observer, IBackupManagerMonitor monitor);
39
40    /**
41     * Restore the given set onto the device, replacing the current data of any app
42     * contained in the restore set with the data previously backed up.
43     *
44     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
45     *
46     * @return Zero on success; nonzero on error.  The observer will only receive
47     *   progress callbacks if this method returned zero.
48     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
49     *   the restore set that should be used.
50     * @param observer If non-null, this binder points to an object that will receive
51     *   progress callbacks during the restore operation.
52     * @param monitor If non null the binder will send important events to this monitor.
53     */
54    int restoreAll(long token, IRestoreObserver observer, IBackupManagerMonitor monitor);
55
56    /**
57     * Restore select packages from the given set onto the device, replacing the
58     * current data of any app contained in the set with the data previously
59     * backed up.
60     *
61     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
62     *
63     * @return Zero on success, nonzero on error. The observer will only receive
64     *   progress callbacks if this method returned zero.
65     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
66     *   the restore set that should be used.
67     * @param observer If non-null, this binder points to an object that will receive
68     *   progress callbacks during the restore operation.
69     * @param packages The set of packages for which to attempt a restore.  Regardless of
70     *   the contents of the actual back-end dataset named by {@code token}, only
71     *   applications mentioned in this list will have their data restored.
72     * @param monitor If non null the binder will send important events to this monitor.
73     */
74    int restoreSome(long token, IRestoreObserver observer, IBackupManagerMonitor monitor,
75            in String[] packages);
76
77    /**
78     * Restore a single application from backup.  The data will be restored from the
79     * current backup dataset if the given package has stored data there, or from
80     * the dataset used during the last full device setup operation if the current
81     * backup dataset has no matching data.  If no backup data exists for this package
82     * in either source, a nonzero value will be returned.
83     *
84     * @return Zero on success; nonzero on error.  The observer will only receive
85     *   progress callbacks if this method returned zero.
86     * @param packageName The name of the package whose data to restore.  If this is
87     *   not the name of the caller's own package, then the android.permission.BACKUP
88     *   permission must be held.
89     * @param observer If non-null, this binder points to an object that will receive
90     *   progress callbacks during the restore operation.
91     * @param monitor If non null the binder will send important events to this monitor.
92     */
93    int restorePackage(in String packageName, IRestoreObserver observer,
94          IBackupManagerMonitor monitor);
95
96    /**
97     * End this restore session.  After this method is called, the IRestoreSession binder
98     * is no longer valid.
99     *
100     * <p><b>Note:</b> The caller <i>must</i> invoke this method to end the restore session,
101     *   even if {@link getAvailableRestoreSets} or {@link performRestore} failed.
102     */
103    void endRestoreSession();
104}
105