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.IFullBackupRestoreObserver;
20import android.app.backup.IRestoreSession;
21import android.os.ParcelFileDescriptor;
22import android.content.Intent;
23
24/**
25 * Direct interface to the Backup Manager Service that applications invoke on.  The only
26 * operation currently needed is a simple notification that the app has made changes to
27 * data it wishes to back up, so the system should run a backup pass.
28 *
29 * Apps will use the {@link android.app.backup.BackupManager} class rather than going through
30 * this Binder interface directly.
31 *
32 * {@hide}
33 */
34interface IBackupManager {
35    /**
36     * Tell the system service that the caller has made changes to its
37     * data, and therefore needs to undergo an incremental backup pass.
38     *
39     * Any application can invoke this method for its own package, but
40     * only callers who hold the android.permission.BACKUP permission
41     * may invoke it for arbitrary packages.
42     */
43    void dataChanged(String packageName);
44
45    /**
46     * Erase all backed-up data for the given package from the given storage
47     * destination.
48     *
49     * Any application can invoke this method for its own package, but
50     * only callers who hold the android.permission.BACKUP permission
51     * may invoke it for arbitrary packages.
52     */
53    void clearBackupData(String transportName, String packageName);
54
55    /**
56     * Notifies the Backup Manager Service that an agent has become available.  This
57     * method is only invoked by the Activity Manager.
58     */
59    void agentConnected(String packageName, IBinder agent);
60
61    /**
62     * Notify the Backup Manager Service that an agent has unexpectedly gone away.
63     * This method is only invoked by the Activity Manager.
64     */
65    void agentDisconnected(String packageName);
66
67    /**
68     * Notify the Backup Manager Service that an application being installed will
69     * need a data-restore pass.  This method is only invoked by the Package Manager.
70     */
71    void restoreAtInstall(String packageName, int token);
72
73    /**
74     * Enable/disable the backup service entirely.  When disabled, no backup
75     * or restore operations will take place.  Data-changed notifications will
76     * still be observed and collected, however, so that changes made while the
77     * mechanism was disabled will still be backed up properly if it is enabled
78     * at some point in the future.
79     *
80     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
81     */
82    void setBackupEnabled(boolean isEnabled);
83
84    /**
85     * Enable/disable automatic restore of application data at install time.  When
86     * enabled, installation of any package will involve the Backup Manager.  If data
87     * exists for the newly-installed package, either from the device's current [enabled]
88     * backup dataset or from the restore set used in the last wholesale restore operation,
89     * that data will be supplied to the new package's restore agent before the package
90     * is made generally available for launch.
91     *
92     * <p>Callers must hold  the android.permission.BACKUP permission to use this method.
93     *
94     * @param doAutoRestore When true, enables the automatic app-data restore facility.  When
95     *   false, this facility will be disabled.
96     */
97    void setAutoRestore(boolean doAutoRestore);
98
99    /**
100     * Indicate that any necessary one-time provisioning has occurred.
101     *
102     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
103     */
104    void setBackupProvisioned(boolean isProvisioned);
105
106    /**
107     * Report whether the backup mechanism is currently enabled.
108     *
109     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
110     */
111    boolean isBackupEnabled();
112
113    /**
114     * Set the device's backup password.  Returns {@code true} if the password was set
115     * successfully, {@code false} otherwise.  Typically a failure means that an incorrect
116     * current password was supplied.
117     *
118     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
119     */
120    boolean setBackupPassword(in String currentPw, in String newPw);
121
122    /**
123     * Reports whether a backup password is currently set.  If not, then a null or empty
124     * "current password" argument should be passed to setBackupPassword().
125     *
126     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
127     */
128    boolean hasBackupPassword();
129
130    /**
131     * Schedule an immediate backup attempt for all pending updates.  This is
132     * primarily intended for transports to use when they detect a suitable
133     * opportunity for doing a backup pass.  If there are no pending updates to
134     * be sent, no action will be taken.  Even if some updates are pending, the
135     * transport will still be asked to confirm via the usual requestBackupTime()
136     * method.
137     *
138     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
139     */
140    void backupNow();
141
142    /**
143     * Write a full backup of the given package to the supplied file descriptor.
144     * The fd may be a socket or other non-seekable destination.  If no package names
145     * are supplied, then every application on the device will be backed up to the output.
146     *
147     * <p>This method is <i>synchronous</i> -- it does not return until the backup has
148     * completed.
149     *
150     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
151     *
152     * @param fd The file descriptor to which a 'tar' file stream is to be written
153     * @param includeApks If <code>true</code>, the resulting tar stream will include the
154     *     application .apk files themselves as well as their data.
155     * @param includeObbs If <code>true</code>, the resulting tar stream will include any
156     *     application expansion (OBB) files themselves belonging to each application.
157     * @param includeShared If <code>true</code>, the resulting tar stream will include
158     *     the contents of the device's shared storage (SD card or equivalent).
159     * @param allApps If <code>true</code>, the resulting tar stream will include all
160     *     installed applications' data, not just those named in the <code>packageNames</code>
161     *     parameter.
162     * @param allIncludesSystem If {@code true}, then {@code allApps} will be interpreted
163     *     as including packages pre-installed as part of the system. If {@code false},
164     *     then setting {@code allApps} to {@code true} will mean only that all 3rd-party
165     *     applications will be included in the dataset.
166     * @param packageNames The package names of the apps whose data (and optionally .apk files)
167     *     are to be backed up.  The <code>allApps</code> parameter supersedes this.
168     */
169    void fullBackup(in ParcelFileDescriptor fd, boolean includeApks, boolean includeObbs,
170            boolean includeShared, boolean allApps, boolean allIncludesSystem,
171            in String[] packageNames);
172
173    /**
174     * Restore device content from the data stream passed through the given socket.  The
175     * data stream must be in the format emitted by fullBackup().
176     *
177     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
178     */
179    void fullRestore(in ParcelFileDescriptor fd);
180
181    /**
182     * Confirm that the requested full backup/restore operation can proceed.  The system will
183     * not actually perform the operation described to fullBackup() / fullRestore() unless the
184     * UI calls back into the Backup Manager to confirm, passing the correct token.  At
185     * the same time, the UI supplies a callback Binder for progress notifications during
186     * the operation.
187     *
188     * <p>The password passed by the confirming entity must match the saved backup or
189     * full-device encryption password in order to perform a backup.  If a password is
190     * supplied for restore, it must match the password used when creating the full
191     * backup dataset being used for restore.
192     *
193     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
194     */
195    void acknowledgeFullBackupOrRestore(int token, boolean allow,
196            in String curPassword, in String encryptionPassword,
197            IFullBackupRestoreObserver observer);
198
199    /**
200     * Identify the currently selected transport.  Callers must hold the
201     * android.permission.BACKUP permission to use this method.
202     */
203    String getCurrentTransport();
204
205    /**
206     * Request a list of all available backup transports' names.  Callers must
207     * hold the android.permission.BACKUP permission to use this method.
208     */
209    String[] listAllTransports();
210
211    /**
212     * Specify the current backup transport.  Callers must hold the
213     * android.permission.BACKUP permission to use this method.
214     *
215     * @param transport The name of the transport to select.  This should be one
216     * of {@link BackupManager.TRANSPORT_GOOGLE} or {@link BackupManager.TRANSPORT_ADB}.
217     * @return The name of the previously selected transport.  If the given transport
218     *   name is not one of the currently available transports, no change is made to
219     *   the current transport setting and the method returns null.
220     */
221    String selectBackupTransport(String transport);
222
223    /**
224     * Get the configuration Intent, if any, from the given transport.  Callers must
225     * hold the android.permission.BACKUP permission in order to use this method.
226     *
227     * @param transport The name of the transport to query.
228     * @return An Intent to use with Activity#startActivity() to bring up the configuration
229     *   UI supplied by the transport.  If the transport has no configuration UI, it should
230     *   return {@code null} here.
231     */
232    Intent getConfigurationIntent(String transport);
233
234    /**
235     * Get the destination string supplied by the given transport.  Callers must
236     * hold the android.permission.BACKUP permission in order to use this method.
237     *
238     * @param transport The name of the transport to query.
239     * @return A string describing the current backup destination.  This string is used
240     *   verbatim by the Settings UI as the summary text of the "configure..." item.
241     */
242    String getDestinationString(String transport);
243
244    /**
245     * Begin a restore session.  Either or both of packageName and transportID
246     * may be null.  If packageName is non-null, then only the given package will be
247     * considered for restore.  If transportID is null, then the restore will use
248     * the current active transport.
249     * <p>
250     * This method requires the android.permission.BACKUP permission <i>except</i>
251     * when transportID is null and packageName is the name of the caller's own
252     * package.  In that case, the restore session returned is suitable for supporting
253     * the BackupManager.requestRestore() functionality via RestoreSession.restorePackage()
254     * without requiring the app to hold any special permission.
255     *
256     * @param packageName The name of the single package for which a restore will
257     *        be requested.  May be null, in which case all packages in the restore
258     *        set can be restored.
259     * @param transportID The name of the transport to use for the restore operation.
260     *        May be null, in which case the current active transport is used.
261     * @return An interface to the restore session, or null on error.
262     */
263    IRestoreSession beginRestoreSession(String packageName, String transportID);
264
265    /**
266     * Notify the backup manager that a BackupAgent has completed the operation
267     * corresponding to the given token.
268     *
269     * @param token The transaction token passed to a BackupAgent's doBackup() or
270     *        doRestore() method.
271     * {@hide}
272     */
273    void opComplete(int token);
274}
275