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