Package ghidra.app.util.bin

Class BinaryReader

  • Direct Known Subclasses:
    FactoryBundledWithBinaryReader
    public class BinaryReader
extends java.lang.Object
    A class for reading data from a generic byte provider in either big-endian or little-endian.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int SIZEOF_BYTE
      The size of a BYTE in Java.
      static int SIZEOF_INT
      The size of an INTEGER in Java.
      static int SIZEOF_LONG
      The size of a LONG in Java.
      static int SIZEOF_SHORT
      The size of a SHORT in Java.

    • Constructor Summary

      Constructors 
      Constructor Description
      BinaryReader​(ByteProvider provider, boolean isLittleEndian)
      Constructs a reader using the given ByteProvider and endian-order.
      BinaryReader​(ByteProvider provider, DataConverter converter, long initialIndex)
      Creates a BinaryReader instance.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int align​(int alignValue)
      Aligns the current index on the specified alignment value.
      BinaryReader asBigEndian()
      Returns a BinaryReader that is in BigEndian mode.
      BinaryReader asLittleEndian()
      Returns a BinaryReader that is in LittleEndian mode.
      BinaryReader clone()
      Returns an independent clone of this reader positioned at the same index.
      BinaryReader clone​(long newIndex)
      Returns a clone of this reader, with its own independent current position, positioned at the new index.
      ByteProvider getByteProvider()
      Returns the underlying byte provider.
      long getPointerIndex()
      Returns the current index value.
      boolean isBigEndian()
      Returns true if this reader will extract values in big endian.
      boolean isLittleEndian()
      Returns true if this reader will extract values in little endian, otherwise in big endian.
      boolean isValidIndex​(int index)
      Returns true if the specified index into the underlying byte provider is valid.
      boolean isValidIndex​(long index)
      Returns true if the specified index into the underlying byte provider is valid.
      long length()
      Returns the length of the underlying file.
      byte peekNextByte()
      Peeks at the next byte without incrementing the current index.
      int peekNextInt()
      Peeks at the next integer without incrementing the current index.
      long peekNextLong()
      Peeks at the next long without incrementing the current index.
      short peekNextShort()
      Peeks at the next short without incrementing the current index.
      java.lang.String readAsciiString​(long index)
      Reads an Ascii string starting at index, ending at the next character outside the range [32..126] or when reaching the end of the underlying ByteProvider.
      java.lang.String readAsciiString​(long index, int length)
      Returns an Ascii string of length bytes starting at index.
      java.lang.String[] readAsciiStringArray​(long index, int nElements)
      Returns the Ascii string array of nElements starting at index
      byte readByte​(long index)
      Returns the signed BYTE at index.
      byte[] readByteArray​(long index, int nElements)
      Returns the BYTE array of nElements starting at index.
      java.lang.String readFixedLenAsciiString​(long index, int len)
      Reads an fixed length Ascii string starting at index.
      int readInt​(long index)
      Returns the signed INTEGER at index.
      int[] readIntArray​(long index, int nElements)
      Returns the INTEGER array of nElements starting at index.
      long readLong​(long index)
      Returns the signed LONG at index.
      long[] readLongArray​(long index, int nElements)
      Returns the LONG array of nElements starting at index.
      java.lang.String readNextAsciiString()
      Reads the Ascii string at the current index and then increments the current index by the length of the Ascii string that was found.
      java.lang.String readNextAsciiString​(int length)
      Reads an Ascii string of length characters starting at the current index and then increments the current index by length.
      byte readNextByte()
      Reads the byte at the current index and then increments the current index by SIZEOF_BYTE.
      byte[] readNextByteArray​(int nElements)
      Reads a byte array of nElements starting at the current index and then increments the current index by SIZEOF_BYTE * nElements.
      int readNextInt()
      Reads the integer at the current index and then increments the current index by SIZEOF_INT.
      int[] readNextIntArray​(int nElements)
      Reads an integer array of nElements starting at the current index and then increments the current index by SIZEOF_INT * nElements.
      long readNextLong()
      Reads the long at the current index and then increments the current index by SIZEOF_LONG.
      long[] readNextLongArray​(int nElements)
      Reads a long array of nElements starting at the current index and then increments the current index by SIZEOF_LONG * nElements.
      java.lang.String readNextNullTerminatedAsciiString()
      Reads a null terminated Ascii string starting at the current index, ending at the first null character or when reaching the end of the underlying ByteProvider.
      short readNextShort()
      Reads the short at the current index and then increments the current index by SIZEOF_SHORT.
      short[] readNextShortArray​(int nElements)
      Reads a short array of nElements starting at the current index and then increments the current index by SIZEOF_SHORT * nElements.
      java.lang.String readNextUnicodeString()
      Reads the Unicode string at the current index and then increments the current index by the length of the Unicode string that was found.
      java.lang.String readNextUnicodeString​(int length)
      Reads fixed length UTF-16 Unicode string the current index and then increments the current pointer index by length elements (length*2 bytes).
      int readNextUnsignedByte()
      Reads the unsigned byte at the current index and then increments the current index by SIZEOF_BYTE.
      long readNextUnsignedInt()
      Reads the unsigned integer at the current index and then increments the current index by SIZEOF_INT.
      int readNextUnsignedShort()
      Reads the unsigned short at the current index and then increments the current index by SIZEOF_SHORT.
      short readShort​(long index)
      Returns the signed SHORT at index.
      short[] readShortArray​(long index, int nElements)
      Returns the SHORT array of nElements starting at index.
      java.lang.String readTerminatedString​(long index, char termChar)
      Reads an Ascii string starting at index, ending at the next termChar character byte or when reaching the end of the underlying ByteProvider.
      java.lang.String readTerminatedString​(long index, java.lang.String termChars)
      Reads an Ascii string starting at index, ending at the next character that is one of the specified termChars or when reaching the end of the underlying ByteProvider.
      java.lang.String readUnicodeString​(long index)
      Reads a null-terminated UTF-16 Unicode string starting at index using the pre-specified endianness.
      java.lang.String readUnicodeString​(long index, int length)
      Reads a fixed length UTF-16 Unicode string of length characters starting at index, using the pre-specified endianness.
      int readUnsignedByte​(long index)
      Returns the unsigned BYTE at index.
      long readUnsignedInt​(long index)
      Returns the unsigned INTEGER at index.
      int readUnsignedShort​(long index)
      Returns the unsigned SHORT at index.
      long readUnsignedValue​(long index, int len)
      Returns the unsigned value of the integer (of the specified length) at the specified offset.
      long readValue​(long index, int len)
      Returns the signed value of the integer (of the specified length) at the specified offset.
      void setLittleEndian​(boolean isLittleEndian)
      Sets the endian of this binary reader.
      void setPointerIndex​(int index)
      A convenience method for setting the index using a 32 bit integer.
      void setPointerIndex​(long index)
      Sets the current index to the specified value.

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • SIZEOF_BYTE

        public static final int SIZEOF_BYTE
        The size of a BYTE in Java.
        See Also:
        Constant Field Values

      • SIZEOF_SHORT

        public static final int SIZEOF_SHORT
        The size of a SHORT in Java.
        See Also:
        Constant Field Values

      • SIZEOF_INT

        public static final int SIZEOF_INT
        The size of an INTEGER in Java.
        See Also:
        Constant Field Values

      • SIZEOF_LONG

        public static final int SIZEOF_LONG
        The size of a LONG in Java.
        See Also:
        Constant Field Values

    • Constructor Detail

      • BinaryReader

        public BinaryReader​(ByteProvider provider,
                    boolean isLittleEndian)
        Constructs a reader using the given ByteProvider and endian-order. If isLittleEndian is true, then all values read from the file will be done so assuming little-endian order. Otherwise, if isLittleEndian is false, then all values will be read assuming big-endian order.
        Parameters:
        provider - the byte provider
        isLittleEndian - the endian-order

      • BinaryReader

        public BinaryReader​(ByteProvider provider,
                    DataConverter converter,
                    long initialIndex)
        Creates a BinaryReader instance.
        Parameters:
        provider - the ByteProvider to use
        converter - the DataConverter to use
        initialIndex - the initial offset

    • Method Detail

      • clone

        public BinaryReader clone​(long newIndex)
        Returns a clone of this reader, with its own independent current position, positioned at the new index.
        Parameters:
        newIndex - the new index
        Returns:
        an independent clone of this reader positioned at the new index

      • clone

        public BinaryReader clone()
        Returns an independent clone of this reader positioned at the same index.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a independent clone of this reader positioned at the same index

      • asBigEndian

        public BinaryReader asBigEndian()
        Returns a BinaryReader that is in BigEndian mode.
        Returns:
        a new independent BinaryReader, at the same position, in BigEndian mode

      • asLittleEndian

        public BinaryReader asLittleEndian()
        Returns a BinaryReader that is in LittleEndian mode.
        Returns:
        a new independent instance, at the same position, in LittleEndian mode

      • isLittleEndian

        public boolean isLittleEndian()
        Returns true if this reader will extract values in little endian, otherwise in big endian.
        Returns:
        true is little endian, false is big endian

      • isBigEndian

        public boolean isBigEndian()
        Returns true if this reader will extract values in big endian.
        Returns:
        true is big endian, false is little endian

      • setLittleEndian

        public void setLittleEndian​(boolean isLittleEndian)
        Sets the endian of this binary reader.
        Parameters:
        isLittleEndian - true for little-endian and false for big-endian

      • length

        public long length()
            throws java.io.IOException
        Returns the length of the underlying file.
        Returns:
        returns the length of the underlying file
        Throws:
        java.io.IOException - if an I/O error occurs

      • isValidIndex

        public boolean isValidIndex​(int index)
                     throws java.io.IOException
        Returns true if the specified index into the underlying byte provider is valid.
        Parameters:
        index - the index in the byte provider
        Returns:
        returns true if the specified index is valid
        Throws:
        java.io.IOException - if an I/O error occurs

      • isValidIndex

        public boolean isValidIndex​(long index)
                     throws java.io.IOException
        Returns true if the specified index into the underlying byte provider is valid.
        Parameters:
        index - the index in the byte provider
        Returns:
        returns true if the specified index is valid
        Throws:
        java.io.IOException - if an I/O error occurs

      • align

        public int align​(int alignValue)
        Aligns the current index on the specified alignment value. For example, if current index was 123 and align value was 16, then current index would become 128.
        Parameters:
        alignValue -
        Returns:
        the number of bytes required to align

      • setPointerIndex

        public void setPointerIndex​(int index)
        A convenience method for setting the index using a 32 bit integer.
        Parameters:
        index - new index, treated as a 32 bit unsigned integer

      • setPointerIndex

        public void setPointerIndex​(long index)
        Sets the current index to the specified value. The pointer index will allow the reader to operate as a psuedo-iterator.
        Parameters:
        index - the byte provider index value

      • getPointerIndex

        public long getPointerIndex()
        Returns the current index value.
        Returns:
        the current index value

      • peekNextByte

        public byte peekNextByte()
                  throws java.io.IOException
        Peeks at the next byte without incrementing the current index.
        Returns:
        the next byte
        Throws:
        java.io.IOException - if an I/O error occurs

      • peekNextShort

        public short peekNextShort()
                    throws java.io.IOException
        Peeks at the next short without incrementing the current index.
        Returns:
        the next short
        Throws:
        java.io.IOException - if an I/O error occurs

      • peekNextInt

        public int peekNextInt()
                throws java.io.IOException
        Peeks at the next integer without incrementing the current index.
        Returns:
        the next int
        Throws:
        java.io.IOException - if an I/O error occurs

      • peekNextLong

        public long peekNextLong()
                  throws java.io.IOException
        Peeks at the next long without incrementing the current index.
        Returns:
        the next long
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextByte

        public byte readNextByte()
                  throws java.io.IOException
        Reads the byte at the current index and then increments the current index by SIZEOF_BYTE.
        Returns:
        the byte at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextUnsignedByte

        public int readNextUnsignedByte()
                         throws java.io.IOException
        Reads the unsigned byte at the current index and then increments the current index by SIZEOF_BYTE.
        Returns:
        the unsigned byte at the current index, as an int
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextShort

        public short readNextShort()
                    throws java.io.IOException
        Reads the short at the current index and then increments the current index by SIZEOF_SHORT.
        Returns:
        the short at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextUnsignedShort

        public int readNextUnsignedShort()
                          throws java.io.IOException
        Reads the unsigned short at the current index and then increments the current index by SIZEOF_SHORT.
        Returns:
        the unsigned short at the current index, as an int
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextInt

        public int readNextInt()
                throws java.io.IOException
        Reads the integer at the current index and then increments the current index by SIZEOF_INT.
        Returns:
        the integer at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextUnsignedInt

        public long readNextUnsignedInt()
                         throws java.io.IOException
        Reads the unsigned integer at the current index and then increments the current index by SIZEOF_INT.
        Returns:
        the unsigned integer at the current index, as a long
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextLong

        public long readNextLong()
                  throws java.io.IOException
        Reads the long at the current index and then increments the current index by SIZEOF_LONG.
        Returns:
        the long at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextAsciiString

        public java.lang.String readNextAsciiString()
                                     throws java.io.IOException
        Reads the Ascii string at the current index and then increments the current index by the length of the Ascii string that was found. This method expects the string to be null-terminated.
        Returns:
        the null-terminated Ascii string at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextNullTerminatedAsciiString

        public java.lang.String readNextNullTerminatedAsciiString()
                                                   throws java.io.IOException
        Reads a null terminated Ascii string starting at the current index, ending at the first null character or when reaching the end of the underlying ByteProvider.

        The current index is advanced to the next byte after the null terminator.

        Returns:
        the null-terminated Ascii string at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextAsciiString

        public java.lang.String readNextAsciiString​(int length)
                                     throws java.io.IOException
        Reads an Ascii string of length characters starting at the current index and then increments the current index by length.
        Returns:
        the Ascii string at the current index
        Throws:
        java.io.IOException

      • readNextUnicodeString

        public java.lang.String readNextUnicodeString()
                                       throws java.io.IOException
        Reads the Unicode string at the current index and then increments the current index by the length of the Unicode string that was found. This method expects the string to be double null-terminated ('\0\0').
        Returns:
        the null-terminated Ascii string at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextUnicodeString

        public java.lang.String readNextUnicodeString​(int length)
                                       throws java.io.IOException
        Reads fixed length UTF-16 Unicode string the current index and then increments the current pointer index by length elements (length*2 bytes).
        Returns:
        the UTF-16 Unicode string at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextByteArray

        public byte[] readNextByteArray​(int nElements)
                         throws java.io.IOException
        Reads a byte array of nElements starting at the current index and then increments the current index by SIZEOF_BYTE * nElements.
        Returns:
        the byte array starting at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextShortArray

        public short[] readNextShortArray​(int nElements)
                           throws java.io.IOException
        Reads a short array of nElements starting at the current index and then increments the current index by SIZEOF_SHORT * nElements.
        Returns:
        the short array starting at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextIntArray

        public int[] readNextIntArray​(int nElements)
                       throws java.io.IOException
        Reads an integer array of nElements starting at the current index and then increments the current index by SIZEOF_INT * nElements.
        Returns:
        the integer array starting at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNextLongArray

        public long[] readNextLongArray​(int nElements)
                         throws java.io.IOException
        Reads a long array of nElements starting at the current index and then increments the current index by SIZEOF_LONG * nElements.
        Returns:
        the long array starting at the current index
        Throws:
        java.io.IOException - if an I/O error occurs

      • readAsciiString

        public java.lang.String readAsciiString​(long index)
                                 throws java.io.IOException
        Reads an Ascii string starting at index, ending at the next character outside the range [32..126] or when reaching the end of the underlying ByteProvider.

        Leading and trailing spaces will be trimmed before the string is returned.

        Parameters:
        index - the index where the Ascii string begins
        Returns:
        the trimmed Ascii string
        Throws:
        java.io.IOException - if an I/O error occurs

      • readAsciiString

        public java.lang.String readAsciiString​(long index,
                                        int length)
                                 throws java.io.IOException
        Returns an Ascii string of length bytes starting at index. This method does not care about null-terminators. Leading and trailing spaces will be trimmed before the string is returned.
        Parameters:
        index - the index where the Ascii string begins
        length - the length of the Ascii string
        Returns:
        the trimmed Ascii string
        Throws:
        java.io.IOException - if an I/O error occurs

      • readTerminatedString

        public java.lang.String readTerminatedString​(long index,
                                             char termChar)
                                      throws java.io.IOException
        Reads an Ascii string starting at index, ending at the next termChar character byte or when reaching the end of the underlying ByteProvider.

        Does NOT trim the string.

        Parameters:
        index - the index where the Ascii string begins
        Returns:
        the Ascii string (excluding the terminating character)
        Throws:
        java.io.IOException - if an I/O error occurs

      • readTerminatedString

        public java.lang.String readTerminatedString​(long index,
                                             java.lang.String termChars)
                                      throws java.io.IOException
        Reads an Ascii string starting at index, ending at the next character that is one of the specified termChars or when reaching the end of the underlying ByteProvider.

        Does NOT trim the string.

        Parameters:
        index - the index where the Ascii string begins
        Returns:
        the Ascii string (excluding the terminating character)
        Throws:
        java.io.IOException - if an I/O error occurs

      • readFixedLenAsciiString

        public java.lang.String readFixedLenAsciiString​(long index,
                                                int len)
                                         throws java.io.IOException
        Reads an fixed length Ascii string starting at index.

        Does NOT trim the string.

        Parameters:
        index - the index where the Ascii string begins
        len - number of bytes to read
        Returns:
        the Ascii string
        Throws:
        java.io.IOException - if an I/O error occurs

      • readUnicodeString

        public java.lang.String readUnicodeString​(long index)
                                   throws java.io.IOException
        Reads a null-terminated UTF-16 Unicode string starting at index using the pre-specified endianness.

        The end of the string is denoted by a two-byte (ie. short) null character.

        Leading and trailing spaces will be trimmed before the string is returned.

        Parameters:
        index - the index where the UTF-16 Unicode string begins
        Returns:
        the trimmed UTF-16 Unicode string
        Throws:
        java.io.IOException - if an I/O error occurs

      • readUnicodeString

        public java.lang.String readUnicodeString​(long index,
                                          int length)
                                   throws java.io.IOException
        Reads a fixed length UTF-16 Unicode string of length characters starting at index, using the pre-specified endianness.

        This method does not care about null-terminators.

        Leading and trailing spaces will be trimmed before the string is returned.

        Parameters:
        index - the index where the UTF-16 Unicode string begins
        length - the number of UTF-16 character elements to read.
        Returns:
        the trimmed UTF-16 Unicode string
        Throws:
        java.io.IOException - if an I/O error occurs

      • readByte

        public byte readByte​(long index)
              throws java.io.IOException
        Returns the signed BYTE at index.
        Parameters:
        index - the index where the BYTE begins
        Returns:
        the signed BYTE
        Throws:
        java.io.IOException - if an I/O error occurs

      • readUnsignedByte

        public int readUnsignedByte​(long index)
                     throws java.io.IOException
        Returns the unsigned BYTE at index.
        Parameters:
        index - the index where the BYTE begins
        Returns:
        the unsigned BYTE as an int
        Throws:
        java.io.IOException - if an I/O error occurs

      • readShort

        public short readShort​(long index)
                throws java.io.IOException
        Returns the signed SHORT at index.
        Parameters:
        index - the index where the SHORT begins
        Returns:
        the signed SHORT
        Throws:
        java.io.IOException - if an I/O error occurs

      • readUnsignedShort

        public int readUnsignedShort​(long index)
                      throws java.io.IOException
        Returns the unsigned SHORT at index.
        Parameters:
        index - the index where the SHORT begins
        Returns:
        the unsigned SHORT as an int
        Throws:
        java.io.IOException - if an I/O error occurs

      • readInt

        public int readInt​(long index)
            throws java.io.IOException
        Returns the signed INTEGER at index.
        Parameters:
        index - the index where the INTEGER begins
        Returns:
        the signed INTEGER
        Throws:
        java.io.IOException - if an I/O error occurs

      • readUnsignedInt

        public long readUnsignedInt​(long index)
                     throws java.io.IOException
        Returns the unsigned INTEGER at index.
        Parameters:
        index - the index where the INTEGER begins
        Returns:
        the unsigned INTEGER as a long
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLong

        public long readLong​(long index)
              throws java.io.IOException
        Returns the signed LONG at index.
        Parameters:
        index - the index where the LONG begins
        Returns:
        the LONG
        Throws:
        java.io.IOException - if an I/O error occurs

      • readValue

        public long readValue​(long index,
                      int len)
               throws java.io.IOException
        Returns the signed value of the integer (of the specified length) at the specified offset.
        Parameters:
        index - offset the offset from the membuffers origin (the address that it is set at)
        len - the number of bytes that the integer occupies. Valid values are 1 (byte), 2 (short), 4 (int), 8 (long)
        Returns:
        value of requested length, with sign bit extended, in a long
        Throws:
        java.io.IOException

      • readUnsignedValue

        public long readUnsignedValue​(long index,
                              int len)
                       throws java.io.IOException
        Returns the unsigned value of the integer (of the specified length) at the specified offset.
        Parameters:
        index - offset the offset from the membuffers origin (the address that it is set at)
        len - the number of bytes that the integer occupies. Valid values are 1 (byte), 2 (short), 4 (int), 8 (long)
        Returns:
        unsigned value of requested length, in a long
        Throws:
        java.io.IOException

      • readByteArray

        public byte[] readByteArray​(long index,
                            int nElements)
                     throws java.io.IOException
        Returns the BYTE array of nElements starting at index.
        Parameters:
        index - the index where the BYTE begins
        nElements - the number of array elements
        Returns:
        the BYTE array
        Throws:
        java.io.IOException - if an I/O error occurs

      • readShortArray

        public short[] readShortArray​(long index,
                              int nElements)
                       throws java.io.IOException
        Returns the SHORT array of nElements starting at index.
        Parameters:
        index - the index where the SHORT begins
        nElements - the number of array elements
        Returns:
        the SHORT array
        Throws:
        java.io.IOException - if an I/O error occurs

      • readIntArray

        public int[] readIntArray​(long index,
                          int nElements)
                   throws java.io.IOException
        Returns the INTEGER array of nElements starting at index.
        Parameters:
        index - the index where the INTEGER begins
        nElements - the number of array elements
        Returns:
        the INTEGER array
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLongArray

        public long[] readLongArray​(long index,
                            int nElements)
                     throws java.io.IOException
        Returns the LONG array of nElements starting at index.
        Parameters:
        index - the index where the LONG begins
        nElements - the number of array elements
        Returns:
        the LONG array
        Throws:
        java.io.IOException - if an I/O error occurs

      • readAsciiStringArray

        public java.lang.String[] readAsciiStringArray​(long index,
                                               int nElements)
                                        throws java.io.IOException
        Returns the Ascii string array of nElements starting at index
        Parameters:
        index - the index where the Ascii Strings begin
        nElements - the number of array elements
        Returns:
        the Ascii String array
        Throws:
        java.io.IOException - if an I/O error occurs

      • getByteProvider

        public ByteProvider getByteProvider()
        Returns the underlying byte provider.
        Returns:
        the underlying byte provider