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.compat.annotation.UnsupportedAppUsage;
20 
21 import java.io.IOException;
22 import java.io.InputStream;
23 
24 /**
25  * Provides an {@link java.io.InputStream}-like interface for accessing an
26  * entity's data during a restore operation. Used by {@link BackupHelper} classes within the {@link
27  * BackupAgentHelper} mechanism.
28  * <p>
29  * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity()}
30  * is called, the current entity's header has already been read from the underlying
31  * {@link BackupDataInput}.  The entity's key string and total data size are available
32  * through this class's {@link #getKey()} and {@link #size()} methods, respectively.
33  * <p class="note">
34  * <strong>Note:</strong> The caller should take care not to seek or close the underlying data
35  * source, nor read more than {@link #size()} bytes from the stream.</p>
36  *
37  * @see BackupAgentHelper
38  * @see BackupHelper
39  */
40 public class BackupDataInputStream extends InputStream {
41 
42     @UnsupportedAppUsage
43     String key;
44     @UnsupportedAppUsage
45     int dataSize;
46 
47     BackupDataInput mData;
48     byte[] mOneByte;
49 
50     /** @hide */
BackupDataInputStream(BackupDataInput data)51     BackupDataInputStream(BackupDataInput data) {
52         mData = data;
53     }
54 
55     /**
56      * Read one byte of entity data from the stream, returning it as
57      * an integer value.  If more than {@link #size()} bytes of data
58      * are read from the stream, the output of this method is undefined.
59      *
60      * @return The byte read, or undefined if the end of the stream has been reached.
61      */
read()62     public int read() throws IOException {
63         byte[] one = mOneByte;
64         if (mOneByte == null) {
65             one = mOneByte = new byte[1];
66         }
67         mData.readEntityData(one, 0, 1);
68         return one[0];
69     }
70 
71     /**
72      * Read up to {@code size} bytes of data into a byte array, beginning at position
73      * {@code offset} within the array.
74      *
75      * @param b Byte array into which the data will be read
76      * @param offset The data will be stored in {@code b} beginning at this index
77      *   within the array.
78      * @param size The number of bytes to read in this operation.  If insufficient
79      *   data exists within the entity to fulfill this request, only as much data
80      *   will be read as is available.
81      * @return The number of bytes of data read, or zero if all of the entity's
82      *   data has already been read.
83      */
read(byte[] b, int offset, int size)84     public int read(byte[] b, int offset, int size) throws IOException {
85         return mData.readEntityData(b, offset, size);
86     }
87 
88     /**
89      * Read enough entity data into a byte array to fill the array.
90      *
91      * @param b Byte array to fill with data from the stream.  If the stream does not
92      *   have sufficient data to fill the array, then the contents of the remainder of
93      *   the array will be undefined.
94      * @return The number of bytes of data read, or zero if all of the entity's
95      *   data has already been read.
96      */
read(byte[] b)97     public int read(byte[] b) throws IOException {
98         return mData.readEntityData(b, 0, b.length);
99     }
100 
101     /**
102      * Report the key string associated with this entity within the backup data set.
103      *
104      * @return The key string for this entity, equivalent to calling
105      *   {@link BackupDataInput#getKey()} on the underlying {@link BackupDataInput}.
106      */
getKey()107     public String getKey() {
108         return this.key;
109     }
110 
111     /**
112      * Report the total number of bytes of data available for the current entity.
113      *
114      * @return The number of data bytes available, equivalent to calling
115      *   {@link BackupDataInput#getDataSize()} on the underlying {@link BackupDataInput}.
116      */
size()117     public int size() {
118         return this.dataSize;
119     }
120 }
121 
122 
123