Package ghidra.app.util.bin

# Class MemoryByteProvider

java.lang.Object
ghidra.app.util.bin.MemoryByteProvider

All Implemented Interfaces:
  `ByteProvider`, `Closeable`, `AutoCloseable`

Direct Known Subclasses:
  `MemoryMutableByteProvider`

public class MemoryByteProvider extends Object implements ByteProvider
A `ByteProvider` implementation based on `Memory`.

The bytes returned by this provider are indexed relative to the `baseAddress` supplied to the constructor, and are limited to `memory blocks` of the same address space.

Warnings:

Using this ByteProvider with memory block/address spaces that are not simple "ram" initialized memory blocks is fraught with peril.

Addresses and address spaces can use all 64 bits of a `long` as an offset, which causes a problem when trying to express the correct `length()` of this ByteProvider as a long. (this is why address ranges deal with inclusive end values instead of exclusive).

- The return value of `length()` is constrained to a max of Long.MAX_VALUE
- `isValidIndex(long)` treats its argument as an unsigned int64, and works for the entire address space range.

Not all byte provider index locations between 0 and `length()` will be valid (because gaps between memory blocks), and may generate exceptions when those locations are read.

- To avoid this situation, the caller will need to use information from the program's Memory manager to align reads to valid locations.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Address`
  `baseAddress`
  `protected boolean`
  `isEmtpy`
  `protected long`
  `maxOffset`
  `protected Memory`
  `memory`

  ### Fields inherited from interface ghidra.app.util.bin.ByteProvider

  `EMPTY_BYTEPROVIDER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MemoryByteProvider(Memory memory, Address baseAddress)`
  Constructs a new `MemoryByteProvider` relative to the specified base address, containing the address range to the highest address in the same address space currently found in the memory map.
  `MemoryByteProvider(Memory memory, Address baseAddress, boolean firstBlockOnly)`
  Constructs a new `MemoryByteProvider` relative to the specified base address, containing the address range to the end of the first memory block, or the highest address in the same address space, currently found in the memory map.
  `MemoryByteProvider(Memory memory, Address baseAddress, Address maxAddress)`
  Constructs a new `MemoryByteProvider` relative to the specified base address, with the specified length.
  `MemoryByteProvider(Memory memory, AddressSpace space)`
  Constructs a new `MemoryByteProvider` for a specific `AddressSpace`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Releases any resources the `ByteProvider` may have occupied
  `static MemoryByteProvider`
  `createDefaultAddressSpaceByteProvider(Program program, boolean firstBlockOnly)`
  Create a `ByteProvider` that starts at the beginning (e.g.
  `static MemoryByteProvider`
  `createMemoryBlockByteProvider(Memory memory, MemoryBlock block)`
  Create a `ByteProvider` that is limited to the specified `MemoryBlock`.
  `static MemoryByteProvider`
  `createProgramHeaderByteProvider(Program program, boolean firstBlockOnly)`
  Create a `ByteProvider` that starts at the beginning of the specified `program's` memory, containing either just the first memory block, or all memory blocks (of the same address space).
  `String`
  `getAbsolutePath()`
  Returns the absolute path (similar to, but not a, URI) to the `ByteProvider`.
  `AddressSetView`
  `getAddressSet()`
  Returns the address range of the bytes of this provider.
  `Address`
  `getEndAddress()`
  Returns the address of the last byte of this provider.
  `File`
  `getFile()`
  Returns the underlying `File` for this `ByteProvider`, or null if this `ByteProvider` is not associated with a `File`.
  `String`
  `getName()`
  Returns the name of the `ByteProvider`.
  `Address`
  `getStartAddress()`
  Returns the address of the first byte of this provider.
  `boolean`
  `isEmpty()`
  Returns true if this ByteProvider does not contain any bytes.
  `boolean`
  `isValidIndex(long index)`
  Returns true if the specified index is valid.
  `long`
  `length()`
  Returns the length of the `ByteProvider`
  `byte`
  `readByte(long index)`
  Reads a byte at the specified index
  `byte[]`
  `readBytes(long index, long length)`
  Reads a byte array at the specified index

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

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

  ### Methods inherited from interface ghidra.app.util.bin.ByteProvider

  `getFSRL, getInputStream`

- ## Field Details

  - ### memory

    protected Memory memory

  - ### baseAddress

    protected Address baseAddress

  - ### maxOffset

    protected long maxOffset

  - ### isEmtpy

    protected boolean isEmtpy

- ## Constructor Details

  - ### MemoryByteProvider

    public MemoryByteProvider(Memory memory, AddressSpace space)
    Constructs a new `MemoryByteProvider` for a specific `AddressSpace`. Bytes will be provided relative to the minimum address (typically 0) in the space, and ranges to the highest address in the same address space currently found in the memory map.

    Parameters:
      `memory` - the `Memory`
      `space` - the `AddressSpace`

  - ### MemoryByteProvider

    public MemoryByteProvider(Memory memory, Address baseAddress)
    Constructs a new `MemoryByteProvider` relative to the specified base address, containing the address range to the highest address in the same address space currently found in the memory map.
    Parameters:
      `memory` - the `Memory`
      `baseAddress` - the base address

  - ### MemoryByteProvider

    public MemoryByteProvider(Memory memory, Address baseAddress, boolean firstBlockOnly)
    Constructs a new `MemoryByteProvider` relative to the specified base address, containing the address range to the end of the first memory block, or the highest address in the same address space, currently found in the memory map.
    Parameters:
      `memory` - the `Memory`
      `baseAddress` - the base address
      `firstBlockOnly` - boolean flag, if true, only the first memory block will be accessible, if false, all memory blocks of the address space will be accessible

  - ### MemoryByteProvider

    public MemoryByteProvider(Memory memory, Address baseAddress, Address maxAddress)
    Constructs a new `MemoryByteProvider` relative to the specified base address, with the specified length.
    Parameters:
      `memory` - the `Memory`
      `baseAddress` - the base address
      `maxAddress` - the highest address accessible by this provider (inclusive), or null if there is no memory

- ## Method Details

  - ### createMemoryBlockByteProvider

    public static MemoryByteProvider createMemoryBlockByteProvider(Memory memory, MemoryBlock block)
    Create a `ByteProvider` that is limited to the specified `MemoryBlock`.
    Parameters:
      `memory` - `Memory` of the program
      `block` - `MemoryBlock` to read from
    Returns:
      new `ByteProvider` that contains the bytes of the specified MemoryBlock

  - ### createProgramHeaderByteProvider

    public static MemoryByteProvider createProgramHeaderByteProvider(Program program, boolean firstBlockOnly)
    Create a `ByteProvider` that starts at the beginning of the specified `program's` memory, containing either just the first memory block, or all memory blocks (of the same address space).
    Parameters:
      `program` - `Program` to read
      `firstBlockOnly` - boolean flag, if true, only the first memory block will be accessible via the returned provider, if false, all memory blocks of the address space will be accessible
    Returns:
      new `MemoryByteProvider`, starting at program's minAddress

  - ### createDefaultAddressSpaceByteProvider

    public static MemoryByteProvider createDefaultAddressSpaceByteProvider(Program program, boolean firstBlockOnly)
    Create a `ByteProvider` that starts at the beginning (e.g. 0) of the specified `program's` default address space memory, containing either the first memory block, or all memory blocks (of the same address space).
    Parameters:
      `program` - `Program` to read
      `firstBlockOnly` - boolean flag, if true, only the first memory block will be accessible via the returned provider, if false, all memory blocks of the address space will be accessible
    Returns:
      new `MemoryByteProvider`, starting at program's minAddress

  - ### getStartAddress

    public Address getStartAddress()
    Returns the address of the first byte of this provider.
    Returns:
      address of the first byte returned by this provider (at index 0)

  - ### getEndAddress

    public Address getEndAddress()
    Returns the address of the last byte of this provider.
    Returns:
      address of the last byte returned by this provider

  - ### getAddressSet

    public AddressSetView getAddressSet()
    Returns the address range of the bytes of this provider.
    Returns:
      address range of first byte to last byte of this provider

  - ### isEmpty

    public boolean isEmpty()
    Description copied from interface: `ByteProvider`
    Returns true if this ByteProvider does not contain any bytes.
    Specified by:
      `isEmpty` in interface `ByteProvider`
    Returns:
      boolean true if this provider is empty, false if contains bytes

  - ### getFile

    public File getFile()
    Description copied from interface: `ByteProvider`
    Returns the underlying `File` for this `ByteProvider`, or null if this `ByteProvider` is not associated with a `File`.
    Specified by:
      `getFile` in interface `ByteProvider`
    Returns:
      the underlying file for this byte provider

  - ### getName

    public String getName()
    Description copied from interface: `ByteProvider`
    Returns the name of the `ByteProvider`. For example, the underlying file name.
    Specified by:
      `getName` in interface `ByteProvider`
    Returns:
      the name of the `ByteProvider` or null if there is no name

  - ### getAbsolutePath

    public String getAbsolutePath()
    Description copied from interface: `ByteProvider`
    Returns the absolute path (similar to, but not a, URI) to the `ByteProvider`. For example, the complete path to the file.
    Specified by:
      `getAbsolutePath` in interface `ByteProvider`
    Returns:
      the absolute path to the `ByteProvider` or null if not associated with a `File`.

  - ### length

    public long length() throws IOException
    Description copied from interface: `ByteProvider`
    Returns the length of the `ByteProvider`
    Specified by:
      `length` in interface `ByteProvider`
    Returns:
      the length of the `ByteProvider`
    Throws:
      `IOException` - if an I/O error occurs

  - ### isValidIndex

    public boolean isValidIndex(long index)
    Description copied from interface: `ByteProvider`
    Returns true if the specified index is valid.
    Specified by:
      `isValidIndex` in interface `ByteProvider`
    Parameters:
      `index` - the index in the byte provider to check
    Returns:
      true if the specified index is valid

  - ### readByte

    public byte readByte(long index) throws IOException
    Description copied from interface: `ByteProvider`
    Reads a byte at the specified index
    Specified by:
      `readByte` in interface `ByteProvider`
    Parameters:
      `index` - the index of the byte to read
    Returns:
      the byte read from the specified index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readBytes

    public byte[] readBytes(long index, long length) throws IOException
    Description copied from interface: `ByteProvider`
    Reads a byte array at the specified index
    Specified by:
      `readBytes` in interface `ByteProvider`
    Parameters:
      `index` - the index of the byte to read
      `length` - the number of bytes to read
    Returns:
      the byte array read from the specified index
    Throws:
      `IOException` - if an I/O error occurs

  - ### close

    public void close()
    Description copied from interface: `ByteProvider`
    Releases any resources the `ByteProvider` may have occupied
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `ByteProvider`
    Specified by:
      `close` in interface `Closeable`