Package ghidra.app.util.bin.format.golang.structmapping

# Class StructureContext<T>

java.lang.Object
ghidra.app.util.bin.format.golang.structmapping.StructureContext<T>

Type Parameters:
  `T` - a java class that has been tagged with a `StructureMapping` annotation.

public class StructureContext<T> extends Object
Information about an instance of a structure that has been read from the memory of a Ghidra program.

All `StructureMapping` tagged classes must have a `ContextField` tagged StructureContext field for that class to be able to access meta-data about its self, and for other classes to reference it when performing markup:

     @StructureMapping(structureName = "mydatatype")
     class MyDataType {
            @ContextField
            private StructureContext<MyDataType> context;

            @FieldMapping
            private long someField;
      ...

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DataType`
  `containingFieldDataType`
  `protected final DataTypeMapper`
  `dataTypeMapper`
  `protected final StructureMappingInfo<T>`
  `mappingInfo`
  `protected final BinaryReader`
  `reader`
  `protected Structure`
  `structureDataType`
  `protected T`
  `structureInstance`
  `protected final long`
  `structureStart`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StructureContext(DataTypeMapper dataTypeMapper, StructureMappingInfo<T> mappingInfo, BinaryReader reader)`
  Creates an instance of a `StructureContext`.
  `StructureContext(DataTypeMapper dataTypeMapper, StructureMappingInfo<T> mappingInfo, DataType containingFieldDataType, BinaryReader reader)`
  Creates an instance of a `StructureContext`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FieldContext<T>`
  `createFieldContext(FieldMappingInfo<T> fmi, boolean includeReader)`
  Creates a new `FieldContext` for a specific field.
  `DataType`
  `getContainingFieldDataType()`
  Returns the `DataType` of the field that this object instance was contained inside of, or null if this instance was not a field inside another structure.
  `DataTypeMapper`
  `getDataTypeMapper()`
  Returns a reference to the root `DataTypeMapper`, as a plain DataTypeMapper type.
  `Address`
  `getFieldAddress(long fieldOffset)`
  Returns the address of an offset from the start of this structure instance.
  `long`
  `getFieldLocation(long fieldOffset)`
  Returns the stream location of an offset from the start of this structure instance.
  `BinaryReader`
  `getFieldReader(long fieldOffset)`
  Returns an independent `BinaryReader` that is positioned at the start of the specified field.
  `StructureMappingInfo<T>`
  `getMappingInfo()`
  Returns the `StructureMappingInfo` for this structure's class.
  `BinaryReader`
  `getReader()`
  Returns the `BinaryReader` that is used to deserialize this structure.
  `Address`
  `getStructureAddress()`
  Returns the address in the program of this structure instance.
  `Structure`
  `getStructureDataType()`
  Returns the Ghidra `structure data type` that represents this object.
  `long`
  `getStructureEnd()`
  Returns the stream location of the end of this structure instance.
  `T`
  `getStructureInstance()`
  Returns a reference to the object instance that was deserialized.
  `int`
  `getStructureLength()`
  Returns the length of this structure instance.
  `long`
  `getStructureStart()`
  Returns the stream location of this structure instance.
  `T`
  `readNewInstance()`
  Creates a new instance of the structure by deserializing the structure's marked fields into java fields.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### dataTypeMapper

    protected final DataTypeMapper dataTypeMapper

  - ### mappingInfo

    protected final StructureMappingInfo<T> mappingInfo

  - ### containingFieldDataType

    protected final DataType containingFieldDataType

  - ### reader

    protected final BinaryReader reader

  - ### structureStart

    protected final long structureStart

  - ### structureInstance

    protected T structureInstance

  - ### structureDataType

    protected Structure structureDataType

- ## Constructor Details

  - ### StructureContext

    public StructureContext(DataTypeMapper dataTypeMapper, StructureMappingInfo<T> mappingInfo, BinaryReader reader)
    Creates an instance of a `StructureContext`.
    Parameters:
      `dataTypeMapper` - mapping context for the program
      `mappingInfo` - mapping information about this structure
      `reader` - `BinaryReader` positioned at the start of the structure to be read, or null if this is a limited-use context object

  - ### StructureContext

    public StructureContext(DataTypeMapper dataTypeMapper, StructureMappingInfo<T> mappingInfo, DataType containingFieldDataType, BinaryReader reader)
    Creates an instance of a `StructureContext`.
    Parameters:
      `dataTypeMapper` - mapping context for the program
      `mappingInfo` - mapping information about this structure
      `containingFieldDataType` - optional, the DataType of the field that contained the instance being deserialized
      `reader` - `BinaryReader` positioned at the start of the structure to be read, or null if this is a limited-use context object

- ## Method Details

  - ### readNewInstance

    public T readNewInstance() throws IOException
    Creates a new instance of the structure by deserializing the structure's marked fields into java fields.
    Returns:
      new instance of structure
    Throws:
      `IOException` - if error reading

  - ### getMappingInfo

    public StructureMappingInfo<T> getMappingInfo()
    Returns the `StructureMappingInfo` for this structure's class.
    Returns:
      `StructureMappingInfo` for this structure's class

  - ### getDataTypeMapper

    public DataTypeMapper getDataTypeMapper()
    Returns a reference to the root `DataTypeMapper`, as a plain DataTypeMapper type. If a more specific DataTypeMapper type is needed, either type-cast this value, or use a `ContextField` tag on a field in your class that specifies the correct DataTypeMapper type.
    Returns:
      the program mapping context that control's this structure instance

  - ### getContainingFieldDataType

    public DataType getContainingFieldDataType()
    Returns the `DataType` of the field that this object instance was contained inside of, or null if this instance was not a field inside another structure.

    For instance, if a structure was being deserialized because it was a field inside another structure, the actual Ghidra data type of the field may be slightly different than the structure data type defined at the top of the structmapped class (ie. `@StructureMapping(structureName='struct')`. The containing field's data type could allow custom logic to enrich or modify this struct's behavior.

    Returns:
      `DataType` of the field that this object instance was contained inside of

  - ### getStructureAddress

    public Address getStructureAddress()
    Returns the address in the program of this structure instance.
    Returns:
      `Address`

  - ### getFieldAddress

    public Address getFieldAddress(long fieldOffset)
    Returns the address of an offset from the start of this structure instance.
    Parameters:
      `fieldOffset` - number of bytes from the beginning of this structure where a field (or other location of interest) starts
    Returns:
      `Address` of specified offset

  - ### getFieldLocation

    public long getFieldLocation(long fieldOffset)
    Returns the stream location of an offset from the start of this structure instance.
    Parameters:
      `fieldOffset` - number of bytes from the beginning of this structure where a field (or other location of interest) starts
    Returns:
      absolute offset / position in the program / BinaryReader stream

  - ### getStructureStart

    public long getStructureStart()
    Returns the stream location of this structure instance.
    Returns:
      absolute offset / position in the program / BinaryReader stream of this structure

  - ### getStructureEnd

    public long getStructureEnd()
    Returns the stream location of the end of this structure instance.
    Returns:
      absolute offset / position in the program / BinaryReader stream of the byte after this structure

  - ### getStructureLength

    public int getStructureLength()
    Returns the length of this structure instance.
    Returns:
      length of this structure, or 0 if this structure is a variable length structure that does not have a fixed length

  - ### getStructureInstance

    public T getStructureInstance()
    Returns a reference to the object instance that was deserialized.
    Returns:
      reference to deserialized structure mapped object

  - ### getReader

    public BinaryReader getReader()
    Returns the `BinaryReader` that is used to deserialize this structure.
    Returns:
      `BinaryReader` that is used to deserialize this structure

  - ### getFieldReader

    public BinaryReader getFieldReader(long fieldOffset)
    Returns an independent `BinaryReader` that is positioned at the start of the specified field.
    Parameters:
      `fieldOffset` - number of bytes from the beginning of this structure where a field (or other location of interest) starts
    Returns:
      new `BinaryReader` positioned at the specified relative offset

  - ### createFieldContext

    public FieldContext<T> createFieldContext(FieldMappingInfo<T> fmi, boolean includeReader)
    Creates a new `FieldContext` for a specific field.
    Parameters:
      `fmi` - `field` of interest
      `includeReader` - boolean flag, if true create a BinaryReader for the field, if false no BinaryReader will be created
    Returns:
      new `FieldContext`

  - ### getStructureDataType

    public Structure getStructureDataType() throws IOException
    Returns the Ghidra `structure data type` that represents this object.

    If this is an instance of a variable length structure mapped class, a custom structure data type will be minted that exactly matches this instance's variable length fields.

    Returns:
      Ghidra `structure data type` that represents this object
    Throws:
      `IOException` - if error constructing new struct data type

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`