1/*
2 * [The "BSD licence"]
3 * Copyright (c) 2010 Ben Gruver (JesusFreke)
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 *    notice, this list of conditions and the following disclaimer in the
13 *    documentation and/or other materials provided with the distribution.
14 * 3. The name of the author may not be used to endorse or promote products
15 *    derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29package org.jf.dexlib.Util;
30
31/**
32 * Interface for a sink for binary output. This is similar to
33 * <code>java.util.DataOutput</code>, but no <code>IOExceptions</code>
34 * are declared, and multibyte output is defined to be little-endian.
35 */
36public interface Output {
37    /**
38     * Gets the current cursor position. This is the same as the number of
39     * bytes written to this instance.
40     *
41     * @return &gt;= 0; the cursor position
42     */
43    public int getCursor();
44
45    /**
46     * Asserts that the cursor is the given value.
47     *
48     * @param expectedCursor the expected cursor value
49     * @throws RuntimeException thrown if <code>getCursor() !=
50     * expectedCursor</code>
51     */
52    public void assertCursor(int expectedCursor);
53
54    /**
55     * Writes a <code>byte</code> to this instance.
56     *
57     * @param value the value to write; all but the low 8 bits are ignored
58     */
59    public void writeByte(int value);
60
61    /**
62     * Writes a <code>short</code> to this instance.
63     *
64     * @param value the value to write; all but the low 16 bits are ignored
65     */
66    public void writeShort(int value);
67
68    /**
69     * Writes an <code>int</code> to this instance.
70     *
71     * @param value the value to write
72     */
73    public void writeInt(int value);
74
75    /**
76     * Writes a <code>long</code> to this instance.
77     *
78     * @param value the value to write
79     */
80    public void writeLong(long value);
81
82    /**
83     * Writes a DWARFv3-style unsigned LEB128 integer. For details,
84     * see the "Dalvik Executable Format" document or DWARF v3 section
85     * 7.6.
86     *
87     * @param value value to write, treated as an unsigned value
88     * @return 1..5; the number of bytes actually written
89     */
90    public int writeUnsignedLeb128(int value);
91
92    /**
93     * Writes a DWARFv3-style unsigned LEB128 integer. For details,
94     * see the "Dalvik Executable Format" document or DWARF v3 section
95     * 7.6.
96     *
97     * @param value value to write
98     * @return 1..5; the number of bytes actually written
99     */
100    public int writeSignedLeb128(int value);
101
102    /**
103     * Writes a {@link org.jf.dexlib.Util.ByteArray} to this instance.
104     *
105     * @param bytes non-null; the array to write
106     */
107    public void write(ByteArray bytes);
108
109    /**
110     * Writes a portion of a <code>byte[]</code> to this instance.
111     *
112     * @param bytes non-null; the array to write
113     * @param offset &gt;= 0; offset into <code>bytes</code> for the first
114     * byte to write
115     * @param length &gt;= 0; number of bytes to write
116     */
117    public void write(byte[] bytes, int offset, int length);
118
119    /**
120     * Writes a <code>byte[]</code> to this instance. This is just
121     * a convenient shorthand for <code>write(bytes, 0, bytes.length)</code>.
122     *
123     * @param bytes non-null; the array to write
124     */
125    public void write(byte[] bytes);
126
127    /**
128     * Writes the given number of <code>0</code> bytes.
129     *
130     * @param count &gt;= 0; the number of zeroes to write
131     */
132    public void writeZeroes(int count);
133
134    /**
135     * Adds extra bytes if necessary (with value <code>0</code>) to
136     * force alignment of the output cursor as given.
137     *
138     * @param alignment &gt; 0; the alignment; must be a power of two
139     */
140    public void alignTo(int alignment);
141}