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 
17 package android.app.backup;
18 
19 import android.app.backup.RestoreSet;
20 import android.app.backup.IRestoreObserver;
21 import 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  */
28 interface 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      */
getAvailableRestoreSets(IRestoreObserver observer, IBackupManagerMonitor monitor)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      */
restoreAll(long token, IRestoreObserver observer, IBackupManagerMonitor monitor)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      */
restoreSome(long token, IRestoreObserver observer, IBackupManagerMonitor monitor, in String[] packages)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      */
restorePackage(in String packageName, IRestoreObserver observer, IBackupManagerMonitor monitor)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      */
endRestoreSession()103     void endRestoreSession();
104 }
105