BackupHelper.java revision cc84c69726507a85116f5664e20e2ebfac76edbe 
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.os.ParcelFileDescriptor;
20
21/**
22 * A convenient interface to be used with the
23 * {@link android.app.backup.BackupAgentHelper} to implement backup and restore of
24 * arbitrary data types.
25 * <p>
26 * STOPSHOP: document!
27 */
28public interface BackupHelper {
29    /**
30     * Based on <code>oldState</code>, determine which of the files from the
31     * application's data directory need to be backed up, write them to
32     * <code>data</code>, and fill in <code>newState</code> with the state as it
33     * exists now.
34     */
35    public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
36            ParcelFileDescriptor newState);
37
38    /**
39     * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
40     * to restore one entity from the restore dataset.
41     * <p class=note>
42     * Do not close the <code>data</code> stream.  Do not read more than
43     * <code>data.size()</code> bytes from <code>data</code>.
44     */
45    public void restoreEntity(BackupDataInputStream data);
46
47    /**
48     * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
49     * to write the new backup state file corresponding to
50     * the current state of the app's data at the time the backup operation was
51     * performed.
52     */
53    public void writeNewStateDescription(ParcelFileDescriptor fd);
54}
55
56