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.IRestoreSession;
20
21/**
22 * Direct interface to the Backup Manager Service that applications invoke on.  The only
23 * operation currently needed is a simple notification that the app has made changes to
24 * data it wishes to back up, so the system should run a backup pass.
25 *
26 * Apps will use the {@link android.app.backup.BackupManager} class rather than going through
27 * this Binder interface directly.
28 *
29 * {@hide}
30 */
31interface IBackupManager {
32    /**
33     * Tell the system service that the caller has made changes to its
34     * data, and therefore needs to undergo an incremental backup pass.
35     *
36     * Any application can invoke this method for its own package, but
37     * only callers who hold the android.permission.BACKUP permission
38     * may invoke it for arbitrary packages.
39     */
40    void dataChanged(String packageName);
41
42    /**
43     * Erase all backed-up data for the given package from the storage
44     * destination.
45     *
46     * Any application can invoke this method for its own package, but
47     * only callers who hold the android.permission.BACKUP permission
48     * may invoke it for arbitrary packages.
49     */
50    void clearBackupData(String packageName);
51
52    /**
53     * Notifies the Backup Manager Service that an agent has become available.  This
54     * method is only invoked by the Activity Manager.
55     */
56    void agentConnected(String packageName, IBinder agent);
57
58    /**
59     * Notify the Backup Manager Service that an agent has unexpectedly gone away.
60     * This method is only invoked by the Activity Manager.
61     */
62    void agentDisconnected(String packageName);
63
64    /**
65     * Notify the Backup Manager Service that an application being installed will
66     * need a data-restore pass.  This method is only invoked by the Package Manager.
67     */
68    void restoreAtInstall(String packageName, int token);
69
70    /**
71     * Enable/disable the backup service entirely.  When disabled, no backup
72     * or restore operations will take place.  Data-changed notifications will
73     * still be observed and collected, however, so that changes made while the
74     * mechanism was disabled will still be backed up properly if it is enabled
75     * at some point in the future.
76     *
77     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
78     */
79    void setBackupEnabled(boolean isEnabled);
80
81    /**
82     * Enable/disable automatic restore of application data at install time.  When
83     * enabled, installation of any package will involve the Backup Manager.  If data
84     * exists for the newly-installed package, either from the device's current [enabled]
85     * backup dataset or from the restore set used in the last wholesale restore operation,
86     * that data will be supplied to the new package's restore agent before the package
87     * is made generally available for launch.
88     *
89     * <p>Callers must hold  the android.permission.BACKUP permission to use this method.
90     *
91     * @param doAutoRestore When true, enables the automatic app-data restore facility.  When
92     *   false, this facility will be disabled.
93     */
94    void setAutoRestore(boolean doAutoRestore);
95
96    /**
97     * Indicate that any necessary one-time provisioning has occurred.
98     *
99     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
100     */
101    void setBackupProvisioned(boolean isProvisioned);
102
103    /**
104     * Report whether the backup mechanism is currently enabled.
105     *
106     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
107     */
108    boolean isBackupEnabled();
109
110    /**
111     * Schedule an immediate backup attempt for all pending updates.  This is
112     * primarily intended for transports to use when they detect a suitable
113     * opportunity for doing a backup pass.  If there are no pending updates to
114     * be sent, no action will be taken.  Even if some updates are pending, the
115     * transport will still be asked to confirm via the usual requestBackupTime()
116     * method.
117     *
118     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
119     */
120    void backupNow();
121
122    /**
123     * Identify the currently selected transport.  Callers must hold the
124     * android.permission.BACKUP permission to use this method.
125     */
126    String getCurrentTransport();
127
128    /**
129     * Request a list of all available backup transports' names.  Callers must
130     * hold the android.permission.BACKUP permission to use this method.
131     */
132    String[] listAllTransports();
133
134    /**
135     * Specify the current backup transport.  Callers must hold the
136     * android.permission.BACKUP permission to use this method.
137     *
138     * @param transport The name of the transport to select.  This should be one
139     * of {@link BackupManager.TRANSPORT_GOOGLE} or {@link BackupManager.TRANSPORT_ADB}.
140     * @return The name of the previously selected transport.  If the given transport
141     *   name is not one of the currently available transports, no change is made to
142     *   the current transport setting and the method returns null.
143     */
144    String selectBackupTransport(String transport);
145
146    /**
147     * Begin a restore session with the given transport (which may differ from the
148     * currently-active backup transport).
149     *
150     * @param transport The name of the transport to use for the restore operation.
151     * @return An interface to the restore session, or null on error.
152     */
153    IRestoreSession beginRestoreSession(String transportID);
154
155    /**
156     * Notify the backup manager that a BackupAgent has completed the operation
157     * corresponding to the given token.
158     *
159     * @param token The transaction token passed to a BackupAgent's doBackup() or
160     *        doRestore() method.
161     * {@hide}
162     */
163    void opComplete(int token);
164}
165