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 17 package com.android.dx.util; 18 19 import com.android.dex.util.ByteOutput; 20 21 /** 22 * Interface for a sink for binary output. This is similar to 23 * {@code java.util.DataOutput}, but no {@code IOExceptions} 24 * are declared, and multibyte output is defined to be little-endian. 25 */ 26 public interface Output extends ByteOutput { 27 /** 28 * Gets the current cursor position. This is the same as the number of 29 * bytes written to this instance. 30 * 31 * @return {@code >= 0;} the cursor position 32 */ getCursor()33 public int getCursor(); 34 35 /** 36 * Asserts that the cursor is the given value. 37 * 38 * @param expectedCursor the expected cursor value 39 * @throws RuntimeException thrown if {@code getCursor() != 40 * expectedCursor} 41 */ assertCursor(int expectedCursor)42 public void assertCursor(int expectedCursor); 43 44 /** 45 * Writes a {@code byte} to this instance. 46 * 47 * @param value the value to write; all but the low 8 bits are ignored 48 */ writeByte(int value)49 public void writeByte(int value); 50 51 /** 52 * Writes a {@code short} to this instance. 53 * 54 * @param value the value to write; all but the low 16 bits are ignored 55 */ writeShort(int value)56 public void writeShort(int value); 57 58 /** 59 * Writes an {@code int} to this instance. 60 * 61 * @param value the value to write 62 */ writeInt(int value)63 public void writeInt(int value); 64 65 /** 66 * Writes a {@code long} to this instance. 67 * 68 * @param value the value to write 69 */ writeLong(long value)70 public void writeLong(long value); 71 72 /** 73 * Writes a DWARFv3-style unsigned LEB128 integer. For details, 74 * see the "Dalvik Executable Format" document or DWARF v3 section 75 * 7.6. 76 * 77 * @param value value to write, treated as an unsigned value 78 * @return {@code 1..5;} the number of bytes actually written 79 */ writeUleb128(int value)80 public int writeUleb128(int 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 88 * @return {@code 1..5;} the number of bytes actually written 89 */ writeSleb128(int value)90 public int writeSleb128(int value); 91 92 /** 93 * Writes a {@link ByteArray} to this instance. 94 * 95 * @param bytes {@code non-null;} the array to write 96 */ write(ByteArray bytes)97 public void write(ByteArray bytes); 98 99 /** 100 * Writes a portion of a {@code byte[]} to this instance. 101 * 102 * @param bytes {@code non-null;} the array to write 103 * @param offset {@code >= 0;} offset into {@code bytes} for the first 104 * byte to write 105 * @param length {@code >= 0;} number of bytes to write 106 */ write(byte[] bytes, int offset, int length)107 public void write(byte[] bytes, int offset, int length); 108 109 /** 110 * Writes a {@code byte[]} to this instance. This is just 111 * a convenient shorthand for {@code write(bytes, 0, bytes.length)}. 112 * 113 * @param bytes {@code non-null;} the array to write 114 */ write(byte[] bytes)115 public void write(byte[] bytes); 116 117 /** 118 * Writes the given number of {@code 0} bytes. 119 * 120 * @param count {@code >= 0;} the number of zeroes to write 121 */ writeZeroes(int count)122 public void writeZeroes(int count); 123 124 /** 125 * Adds extra bytes if necessary (with value {@code 0}) to 126 * force alignment of the output cursor as given. 127 * 128 * @param alignment {@code > 0;} the alignment; must be a power of two 129 */ alignTo(int alignment)130 public void alignTo(int alignment); 131 } 132