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.annotation.SystemApi;
20 import android.compat.annotation.UnsupportedAppUsage;
21 import android.os.ParcelFileDescriptor;
22 
23 import java.io.FileDescriptor;
24 import java.io.IOException;
25 
26 /**
27  * Provides the structured interface through which a {@link BackupAgent} commits
28  * information to the backup data set, via its {@link
29  * BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
30  * onBackup()} method.  Data written for backup is presented
31  * as a set of "entities," key/value pairs in which each binary data record "value" is
32  * named with a string "key."
33  * <p>
34  * To commit a data record to the backup transport, the agent's
35  * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
36  * onBackup()} method first writes an "entity header" that supplies the key string for the record
37  * and the total size of the binary value for the record.  After the header has been
38  * written, the agent then writes the binary entity value itself.  The entity value can
39  * be written in multiple chunks if desired, as long as the total count of bytes written
40  * matches what was supplied to {@link #writeEntityHeader(String, int) writeEntityHeader()}.
41  * <p>
42  * Entity key strings are considered to be unique within a given application's backup
43  * data set. If a backup agent writes a new entity under an existing key string, its value will
44  * replace any previous value in the transport's remote data store.  You can remove a record
45  * entirely from the remote data set by writing a new entity header using the
46  * existing record's key, but supplying a negative <code>dataSize</code> parameter.
47  * When you do so, the agent does not need to call {@link #writeEntityData(byte[], int)}.
48  * <h3>Example</h3>
49  * <p>
50  * Here is an example illustrating a way to back up the value of a String variable
51  * called <code>mStringToBackUp</code>:
52  * <pre>
53  * static final String MY_STRING_KEY = "storedstring";
54  *
55  * public void {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)}
56  *         throws IOException {
57  *     ...
58  *     byte[] stringBytes = mStringToBackUp.getBytes();
59  *     data.writeEntityHeader(MY_STRING_KEY, stringBytes.length);
60  *     data.writeEntityData(stringBytes, stringBytes.length);
61  *     ...
62  * }</pre>
63  *
64  * @see BackupAgent
65  */
66 public class BackupDataOutput {
67 
68     private final long mQuota;
69     private final int mTransportFlags;
70 
71     @UnsupportedAppUsage
72     long mBackupWriter;
73 
74     /**
75      * Construct a BackupDataOutput purely for data-stream manipulation.  This instance will
76      * not report usable quota information.
77      * @hide */
78     @SystemApi
BackupDataOutput(FileDescriptor fd)79     public BackupDataOutput(FileDescriptor fd) {
80         this(fd, /*quota=*/ -1, /*transportFlags=*/ 0);
81     }
82 
83     /** @hide */
84     @SystemApi
BackupDataOutput(FileDescriptor fd, long quota)85     public BackupDataOutput(FileDescriptor fd, long quota) {
86         this(fd, quota, /*transportFlags=*/ 0);
87     }
88 
89     /** @hide */
BackupDataOutput(FileDescriptor fd, long quota, int transportFlags)90     public BackupDataOutput(FileDescriptor fd, long quota, int transportFlags) {
91         if (fd == null) throw new NullPointerException();
92         mQuota = quota;
93         mTransportFlags = transportFlags;
94         mBackupWriter = ctor(fd);
95         if (mBackupWriter == 0) {
96             throw new RuntimeException("Native initialization failed with fd=" + fd);
97         }
98     }
99 
100     /**
101      * Returns the quota in bytes for the application's current backup operation.  The
102      * value can vary for each operation.
103      *
104      * @see FullBackupDataOutput#getQuota()
105      */
getQuota()106     public long getQuota() {
107         return mQuota;
108     }
109 
110     /**
111      * Returns flags with additional information about the backup transport. For supported flags see
112      * {@link android.app.backup.BackupAgent}
113      *
114      * @see FullBackupDataOutput#getTransportFlags()
115      */
getTransportFlags()116     public int getTransportFlags() {
117         return mTransportFlags;
118     }
119 
120     /**
121      * Mark the beginning of one record in the backup data stream. This must be called before
122      * {@link #writeEntityData}.
123      * @param key A string key that uniquely identifies the data record within the application.
124      *    Keys whose first character is \uFF00 or higher are not valid.
125      * @param dataSize The size in bytes of this record's data.  Passing a dataSize
126      *    of -1 indicates that the record under this key should be deleted.
127      * @return The number of bytes written to the backup stream
128      * @throws IOException if the write failed
129      */
writeEntityHeader(String key, int dataSize)130     public int writeEntityHeader(String key, int dataSize) throws IOException {
131         int result = writeEntityHeader_native(mBackupWriter, key, dataSize);
132         if (result >= 0) {
133             return result;
134         } else {
135             throw new IOException("result=0x" + Integer.toHexString(result));
136         }
137     }
138 
139     /**
140      * Write a chunk of data under the current entity to the backup transport.
141      * @param data A raw data buffer to send
142      * @param size The number of bytes to be sent in this chunk
143      * @return the number of bytes written
144      * @throws IOException if the write failed
145      */
writeEntityData(byte[] data, int size)146     public int writeEntityData(byte[] data, int size) throws IOException {
147         int result = writeEntityData_native(mBackupWriter, data, size);
148         if (result >= 0) {
149             return result;
150         } else {
151             throw new IOException("result=0x" + Integer.toHexString(result));
152         }
153     }
154 
155     /** @hide */
setKeyPrefix(String keyPrefix)156     public void setKeyPrefix(String keyPrefix) {
157         setKeyPrefix_native(mBackupWriter, keyPrefix);
158     }
159 
160     /** @hide */
161     @Override
finalize()162     protected void finalize() throws Throwable {
163         try {
164             dtor(mBackupWriter);
165         } finally {
166             super.finalize();
167         }
168     }
169 
ctor(FileDescriptor fd)170     private native static long ctor(FileDescriptor fd);
dtor(long mBackupWriter)171     private native static void dtor(long mBackupWriter);
172 
writeEntityHeader_native(long mBackupWriter, String key, int dataSize)173     private native static int writeEntityHeader_native(long mBackupWriter, String key, int dataSize);
writeEntityData_native(long mBackupWriter, byte[] data, int size)174     private native static int writeEntityData_native(long mBackupWriter, byte[] data, int size);
setKeyPrefix_native(long mBackupWriter, String keyPrefix)175     private native static void setKeyPrefix_native(long mBackupWriter, String keyPrefix);
176 }
177 
178