org.apache.poi.hssf.record

## Class RecordInputStream

- java.lang.Object
- - org.apache.poi.hssf.record.RecordInputStream

- All Implemented Interfaces:
    LittleEndianInput

      public final class RecordInputStream
      extends java.lang.Object
      implements LittleEndianInput

  Title: Record Input Stream Description: Wraps a stream and provides helper methods for the construction of records.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RecordInputStream.LeftoverDataException` For use in `BiffViewer` which may construct `Record`s that don't completely read all available data.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static short` | `MAX_RECORD_DATA_SIZE` Maximum size of a single record (minus the 4 byte header) without a continue

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RecordInputStream(java.io.InputStream in)`
    `RecordInputStream(java.io.InputStream in, EncryptionInfo key, int initialOffset)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()`
    `int` | `getNextSid()`
    `short` | `getSid()`
    `boolean` | `hasNextRecord()` Note - this method is expected to be called only when completed reading the current BIFF record.
    `void` | `mark(int readlimit)` Mark the stream position - experimental function
    `void` | `nextRecord()` Moves to the next record in the stream.
    `int` | `read(byte[] b, int off, int len)`
    `byte[]` | `readAllContinuedRemainder()` Deprecated. POI 2.0 Best to write a input stream that wraps this one where there is special sub record that may overlap continue records.
    `byte` | `readByte()` Reads an 8 bit, signed value
    `java.lang.String` | `readCompressedUnicode(int requestedLength)`
    `double` | `readDouble()`
    `void` | `readFully(byte[] buf)`
    `void` | `readFully(byte[] buf, int off, int len)`
    `int` | `readInt()` Reads a 32 bit, signed value
    `long` | `readLong()` Reads a 64 bit, signed value
    `void` | `readPlain(byte[] buf, int off, int len)` Usually acts the same as `LittleEndianInput.readFully(byte[], int, int)`, but for an encrypted stream the raw (unencrypted) data is filled
    `byte[]` | `readRemainder()` Returns the remaining bytes for the current record.
    `short` | `readShort()` Reads a 16 bit, signed value
    `java.lang.String` | `readString()`
    `int` | `readUByte()` Reads an 8 bit, unsigned value
    `java.lang.String` | `readUnicodeLEString(int requestedLength)` given a byte array of 16-bit unicode characters, compress to 8-bit and return a string { 0x16, 0x00 } -0x16
    `int` | `readUShort()` Reads a 16 bit, unsigned value.
    `int` | `remaining()` The remaining number of bytes in the current record.
    `void` | `reset()` Resets the stream position to the previously marked position.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### MAX_RECORD_DATA_SIZE

          public static final short MAX_RECORD_DATA_SIZE

      Maximum size of a single record (minus the 4 byte header) without a continue
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RecordInputStream

          public RecordInputStream(java.io.InputStream in)
                            throws RecordFormatException

      Throws:
        `RecordFormatException`

    - #### RecordInputStream

          public RecordInputStream(java.io.InputStream in,
                                   EncryptionInfo key,
                                   int initialOffset)
                            throws RecordFormatException

      Throws:
        `RecordFormatException`

  - ### Method Detail

    - #### available

          public int available()

      Specified by:
        `available` in interface `LittleEndianInput`
      Returns:
        the number of bytes available in the current BIFF record
      See Also:
        `remaining()`

    - #### read

          public int read(byte[] b,
                          int off,
                          int len)

    - #### getSid

          public short getSid()

    - #### hasNextRecord

          public boolean hasNextRecord()
                                throws RecordInputStream.LeftoverDataException

      Note - this method is expected to be called only when completed reading the current BIFF record.
      Returns:
        true, if there's another record in the stream
      Throws:
        `RecordInputStream.LeftoverDataException` - if this method is called before reaching the end of the current record.

    - #### nextRecord

          public void nextRecord()
                          throws RecordFormatException

      Moves to the next record in the stream. Note: The auto continue flag is reset to true
      Throws:
        `RecordFormatException`

    - #### readByte

          public byte readByte()

      Reads an 8 bit, signed value
      Specified by:
        `readByte` in interface `LittleEndianInput`

    - #### readShort

          public short readShort()

      Reads a 16 bit, signed value
      Specified by:
        `readShort` in interface `LittleEndianInput`

    - #### readInt

          public int readInt()

      Reads a 32 bit, signed value
      Specified by:
        `readInt` in interface `LittleEndianInput`

    - #### readLong

          public long readLong()

      Reads a 64 bit, signed value
      Specified by:
        `readLong` in interface `LittleEndianInput`

    - #### readUByte

          public int readUByte()

      Reads an 8 bit, unsigned value
      Specified by:
        `readUByte` in interface `LittleEndianInput`

    - #### readUShort

          public int readUShort()

      Reads a 16 bit, unsigned value.
      Specified by:
        `readUShort` in interface `LittleEndianInput`

    - #### readDouble

          public double readDouble()

      Specified by:
        `readDouble` in interface `LittleEndianInput`

    - #### readPlain

          public void readPlain(byte[] buf,
                                int off,
                                int len)

      Description copied from interface: `LittleEndianInput`
      Usually acts the same as `LittleEndianInput.readFully(byte[], int, int)`, but for an encrypted stream the raw (unencrypted) data is filled
      Specified by:
        `readPlain` in interface `LittleEndianInput`
      Parameters:
        `buf` - the byte array to receive the bytes
        `off` - the start offset into the byte array
        `len` - the amount of bytes to fill

    - #### readFully

          public void readFully(byte[] buf)

      Specified by:
        `readFully` in interface `LittleEndianInput`

    - #### readFully

          public void readFully(byte[] buf,
                                int off,
                                int len)

      Specified by:
        `readFully` in interface `LittleEndianInput`

    - #### readString

          public java.lang.String readString()

    - #### readUnicodeLEString

          public java.lang.String readUnicodeLEString(int requestedLength)

      given a byte array of 16-bit unicode characters, compress to 8-bit and return a string { 0x16, 0x00 } -0x16
      Parameters:
        `requestedLength` - the length of the final string
      Returns:
        the converted string
      Throws:
        `java.lang.IllegalArgumentException` - if len is too large (i.e., there is not enough data in string to create a String of that length)

    - #### readCompressedUnicode

          public java.lang.String readCompressedUnicode(int requestedLength)

    - #### readRemainder

          public byte[] readRemainder()

      Returns the remaining bytes for the current record.
      Returns:
        The remaining bytes of the current record.

    - #### readAllContinuedRemainder

          @Deprecated
          public byte[] readAllContinuedRemainder()

      Deprecated. POI 2.0 Best to write a input stream that wraps this one where there is special sub record that may overlap continue records.
      Reads all byte data for the current record, including any that overlaps into any following continue records.
      Returns:
        all byte data for the current record

    - #### remaining

          public int remaining()

      The remaining number of bytes in the current record.
      Returns:
        The number of bytes remaining in the current record

    - #### getNextSid

          public int getNextSid()

      Returns:
        sid of next record. Can be called after hasNextRecord()

    - #### mark

          @Internal
          public void mark(int readlimit)

      Mark the stream position - experimental function
      Parameters:
        `readlimit` - the read ahead limit
      See Also:
        `InputStream.mark(int)`

    - #### reset

          @Internal
          public void reset()
                               throws java.io.IOException

      Resets the stream position to the previously marked position. Experimental function - this only works, when nextRecord() wasn't called in the meantime.
      Throws:
        `java.io.IOException` - if marking is not supported
      See Also:
        `InputStream.reset()`

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.