Input.java revision a7139f6586c9bb8452e4c648ce582f8fbc626740 
1/*
2 * Copyright (C) 2007 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 org.jf.dexlib.Util;
18
19/**
20 * Interface for a source for binary input. This is similar to
21 * <code>java.util.DataInput</code>, but no <code>IOExceptions</code>
22 * are declared, and multibyte input is defined to be little-endian.
23 */
24public interface Input {
25    /**
26     * Gets the current cursor position. This is the same as the number of
27     * bytes read from this instance.
28     *
29     * @return &gt;= 0; the cursor position
30     */
31    public int getCursor();
32
33    /**
34     * Sets the current cursor position.
35     *
36     * @return &gt;= 0; the cursor position
37     */
38    public void setCursor(int cursor);
39
40    /**
41     * Asserts that the cursor is the given value.
42     *
43     * @param expectedCursor the expected cursor value
44     * @throws RuntimeException thrown if <code>getCursor() !=
45     * expectedCursor</code>
46     */
47    public void assertCursor(int expectedCursor);
48
49    /**
50     * Reads a <code>byte</code> from this instance.
51     *
52     * @return the byte value that was read
53     */
54    public byte readByte();
55
56    /**
57     * Reads a <code>short</code> from this instance.
58     *
59     * @return the short value that was read, as an int
60     */
61    public int readShort();
62
63    /**
64     * Reads an <code>int</code> from this instance.
65     *
66     * @return the unsigned int value that was read
67     */
68    public int readInt();
69
70    /**
71     * Reads a <code>long</code> from this instance.
72     *
73     * @return the long value that was read
74     */
75    public long readLong();
76
77
78    /**
79     * Reads a DWARFv3-style signed LEB128 integer. For details,
80     * see the "Dalvik Executable Format" document or DWARF v3 section
81     * 7.6.
82     *
83     * @return the integer value that was read
84     */
85    public int readSignedLeb128();
86
87    /**
88     * Reads a DWARFv3-style unsigned LEB128 integer. For details,
89     * see the "Dalvik Executable Format" document or DWARF v3 section
90     * 7.6.
91     *
92     * @return the integer value that was read
93     */
94    public int readUnsignedLeb128();
95
96
97    /**
98     * Reads a unsigned value as a DWARFv3-style LEB128 integer. It specifically
99     * checks for the case when the value was incorrectly formatted as a signed
100     * LEB128, and returns the appropriate unsigned value, but negated
101     * @return If the value was formatted as a ULEB128, it returns the actual unsigned
102     * value. Otherwise, if the value was formatted as a signed LEB128, it negates the
103     * "correct" unsigned value and returns that
104     */
105    public int readUnsignedOrSignedLeb128();
106
107    /**
108     * reads a <code>byte[]</code> from this instance.
109     *
110     * @param bytes non-null; the buffer to read the data into
111     * @param offset &gt;= 0; offset into <code>bytes</code> for the first
112     * byte to write
113     * @param length &gt;= 0; number of bytes to read
114     */
115    public void read(byte[] bytes, int offset, int length);
116
117    /**
118     * reads a <code>byte[]</code> from this instance. This is just
119     * a convenient shorthand for <code>read(bytes, 0, bytes.length)</code>.
120     *
121     * @param bytes non-null; the buffer to read the data into
122     */
123    public void read(byte[] bytes);
124
125
126    /**
127     * reads a <code>byte[]</code> from this instance
128     *
129     * @param length &gt;= 0; number of bytes to read
130     * @return a byte array containing <code>length</code> bytes
131     */
132    public byte[] readBytes(int length);
133
134    /**
135     * reads a <code>byte[]</code> from this instance, from the current cursor up to but not including
136     * the next null (0) byte. The terminating null byte is read and discarded, so that after the read,
137     * the cursor is positioned at the byte immediately after the terminating null
138     */
139    public byte[] readNullTerminatedBytes();
140
141    /**
142     * Skips the given number of bytes.
143     *
144     * @param count &gt;= 0; the number of bytes to skip
145     */
146    public void skipBytes(int count);
147
148    /**
149     * Skip extra bytes if necessary to force alignment of the output
150     * cursor as given.
151     *
152     * @param alignment &gt; 0; the alignment; must be a power of two
153     */
154    public void alignTo(int alignment);
155}
156