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

# Class DataTypeMapper

java.lang.Object
ghidra.app.util.bin.format.golang.structmapping.DataTypeMapper

All Implemented Interfaces:
  `AutoCloseable`

Direct Known Subclasses:
  `GoRttiMapper`

public class DataTypeMapper extends Object implements AutoCloseable
Information about `StructureMapping` classes and their metadata.

To use the full might and majesty of StructureMapping(tm), a DataTypeMapper must be created. It must be able to `find` (`more find`) the Ghidra structure data types being used, and it must `know` about all classes that are going to participate during deserialization and markup.

Structure mapped classes can receive a reference to the specific DataTypeMapper type that created them by declaring a `DataTypeMapper` field, and tagging it with the @`ContextField` annotation:

     class MyDataTypeMapper extends DataTypeMapper {
      public MyDataTypeMapper() {
        ...
       registerStructure(MyDataType.class);
      }
      public void foo() { ... }
     }

     @StructureMapping(structureName = "mydatatype")
     class MyDataType {

      @ContextField
      private MyDataTypeMapper myDataTypeMapper;

      @ContextField
      private StructureContext<MyDataType> context;

      @FieldMapping
      private long someField;

     void bar() {
      context.getDataTypeMapper().getProgram(); // can only access methods defined on base DataTypeMapper type
      myDataTypeMapper.foo(); // same context as previous line, but typed correctly
     ...

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DataTypeManager`
  `archiveDTM`
  `protected List<CategoryPath>`
  `archiveSearchCPs`
  `protected Map<Class<?>,StructureMappingInfo<?>>`
  `mappingInfo`
  `protected Program`
  `program`
  `protected DataTypeManager`
  `programDTM`
  `protected List<CategoryPath>`
  `programSearchCPs`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DataTypeMapper(Program program, ResourceFile archiveGDT)`
  Creates and initializes a DataTypeMapper.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addArchiveSearchCategoryPath(CategoryPath... paths)`
  Adds category paths to a search list, used when looking for a data type.
  `void`
  `addProgramSearchCategoryPath(CategoryPath... paths)`
  Adds category paths to a search list, used when looking for a data type.
  `void`
  `close()`
  `<T> StructureContext<T>`
  `createArtificialStructureContext(Class<T> structureClass)`
  Creates an artificial structure context to be used in some limited situations.
  `MarkupSession`
  `createMarkupSession(TaskMonitor monitor)`
  Creates a `MarkupSession` that is controlled by the specified `TaskMonitor`.
  `protected BinaryReader`
  `createProgramReader()`
  Creates a new BinaryReader that reads bytes from the current program's memory image.
  `protected DataType`
  `findType(String name, List<CategoryPath> searchList, DataTypeManager dtm)`
  `<T> Address`
  `getAddressOfStructure(T structureInstance)`
  Attempts to convert an instance of an object (that represents a chunk of memory in the program) into its Address.
  `Address`
  `getCodeAddress(long offset)`
  Converts an offset into an Address.
  `Address`
  `getDataAddress(long offset)`
  Converts an offset into an Address.
  `DataConverter`
  `getDataConverter()`
  Returns a `DataConverter` appropriate for the current program.
  `CategoryPath`
  `getDefaultVariableLengthStructCategoryPath()`
  CategoryPath location (in the program) where new data types will be created to represent variable length structures.
  `DataTypeManager`
  `getDTM()`
  Returns the program's data type manager.
  `<T> Address`
  `getMaxAddressOfStructure(T structureInstance)`
  Returns the address of the last byte of a structure.
  `Program`
  `getProgram()`
  Returns the program.
  `BinaryReader`
  `getReader(long position)`
  Creates a `BinaryReader`, at the specified position.
  `<T> StructureContext<T>`
  `getStructureContextOfInstance(T structureInstance)`
  Returns the `StructureContext` of a structure mapped instance.
  `Structure`
  `getStructureDataType(Class<?> clazz)`
  Returns a Ghidra structure data type representing the specified class.
  `String`
  `getStructureDataTypeName(Class<?> clazz)`
  Returns the name of the Ghidra structure that has been registered for the specified structure mapped class.
  `<T> StructureMappingInfo<T>`
  `getStructureMappingInfo(Class<T> clazz)`
  Returns the `StructureMappingInfo` for a class (that has already been registered).
  `<T> StructureMappingInfo<T>`
  `getStructureMappingInfo(T structureInstance)`
  Returns the `StructureMappingInfo` for an object instance.
  `<T extends DataType>
  T`
  `getType(String name, Class<T> clazz)`
  Returns a named `DataType`, searching the registered `program` and `archive` category paths.
  `<T extends DataType>
  T`
  `getTypeOrDefault(String name, Class<T> clazz, T defaultValue)`
  Returns a named `DataType`, searching the registered `program` and `archive` category paths.
  `<T> T`
  `readStructure(Class<T> structureClass, long position)`
  Reads a structure mapped object from the specified position of the program.
  `<T> T`
  `readStructure(Class<T> structureClass, BinaryReader structReader)`
  Reads a structure mapped object from the current position of the specified BinaryReader.
  `<T> T`
  `readStructure(Class<T> structureClass, Address address)`
  Reads a structure mapped object from the specified Address of the program.
  `<T> T`
  `readStructure(Class<T> structureClass, DataType containingFieldDataType, BinaryReader structReader)`
  Reads a structure mapped object from the current position of the specified BinaryReader.
  `<T> void`
  `registerStructure(Class<T> clazz)`
  Registers a class that has `structure mapping` information.
  `void`
  `registerStructures(List<Class<?>> classes)`
  Registers the specified `structure mapping` classes.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### program

    protected Program program

  - ### programDTM

    protected DataTypeManager programDTM

  - ### archiveDTM

    protected DataTypeManager archiveDTM

  - ### programSearchCPs

    protected List<CategoryPath> programSearchCPs

  - ### archiveSearchCPs

    protected List<CategoryPath> archiveSearchCPs

  - ### mappingInfo

    protected Map<Class<?>,StructureMappingInfo<?>> mappingInfo

- ## Constructor Details

  - ### DataTypeMapper

    protected DataTypeMapper(Program program, ResourceFile archiveGDT) throws IOException
    Creates and initializes a DataTypeMapper.
    Parameters:
      `program` - the `Program` that will contain the deserialized data
      `archiveGDT` - path to a gdt data type archive that will be searched when a `getType(String, Class)` is called, or `null` if no archive
    Throws:
      `IOException` - if error opening data type archive

- ## Method Details

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`

  - ### getDefaultVariableLengthStructCategoryPath

    public CategoryPath getDefaultVariableLengthStructCategoryPath()
    CategoryPath location (in the program) where new data types will be created to represent variable length structures.
    Returns:
      `CategoryPath`, default is ROOT

  - ### getProgram

    public Program getProgram()
    Returns the program.
    Returns:
      ghidra `Program`

  - ### createMarkupSession

    public MarkupSession createMarkupSession(TaskMonitor monitor)
    Creates a `MarkupSession` that is controlled by the specified `TaskMonitor`.
    Parameters:
      `monitor` - `TaskMonitor`
    Returns:
      new `MarkupSession`

  - ### getDataConverter

    public DataConverter getDataConverter()
    Returns a `DataConverter` appropriate for the current program.
    Returns:
      `DataConverter`

  - ### addProgramSearchCategoryPath

    public void addProgramSearchCategoryPath(CategoryPath... paths)
    Adds category paths to a search list, used when looking for a data type.

    See `getType(String, Class)`.

    Parameters:
      `paths` - vararg list of `CategoryPath`s

  - ### addArchiveSearchCategoryPath

    public void addArchiveSearchCategoryPath(CategoryPath... paths)
    Adds category paths to a search list, used when looking for a data type.

    See `getType(String, Class)`.

    Parameters:
      `paths` - vararg list of `CategoryPath`s

  - ### registerStructure

    public <T> void registerStructure(Class<T> clazz) throws IOException
    Registers a class that has `structure mapping` information.
    Type Parameters:
      `T` - structure mapped class type
    Parameters:
      `clazz` - class that represents a structure, marked with `StructureMapping` annotation
    Throws:
      `IOException` - if the class's Ghidra structure data type could not be found

  - ### registerStructures

    public void registerStructures(List<Class<?>> classes) throws IOException
    Registers the specified `structure mapping` classes.
    Parameters:
      `classes` - list of classes to register
    Throws:
      `IOException` - if a class's Ghidra structure data type could not be found

  - ### getStructureMappingInfo

    public <T> StructureMappingInfo<T> getStructureMappingInfo(Class<T> clazz)
    Returns the `StructureMappingInfo` for a class (that has already been registered).
    Type Parameters:
      `T` - structure mapped class type
    Parameters:
      `clazz` - the class
    Returns:
      `StructureMappingInfo` for the specified class, or null if the class was not previously `registered`

  - ### getStructureMappingInfo

    public <T> StructureMappingInfo<T> getStructureMappingInfo(T structureInstance)
    Returns the `StructureMappingInfo` for an object instance.
    Type Parameters:
      `T` - structure mapped class type
    Parameters:
      `structureInstance` - an instance of a previously registered `structure mapping` class, or null
    Returns:
      `StructureMappingInfo` for the instance, or null if the class was not previously `registered`

  - ### getStructureDataType

    public Structure getStructureDataType(Class<?> clazz)
    Returns a Ghidra structure data type representing the specified class.
    Parameters:
      `clazz` - a structure mapped class
    Returns:
      `Structure` data type, or null if the class was a struct with variable length fields

  - ### getStructureDataTypeName

    public String getStructureDataTypeName(Class<?> clazz)
    Returns the name of the Ghidra structure that has been registered for the specified structure mapped class.
    Parameters:
      `clazz` - a structure mapped class
    Returns:
      name of the corresponding Ghidra structure data type, or null if class was not registered

  - ### getType

    public <T extends DataType> T getType(String name, Class<T> clazz)
    Returns a named `DataType`, searching the registered `program` and `archive` category paths.

    DataTypes that were found in the attached archive gdt manager will be copied into the program's data type manager before being returned.

    Type Parameters:
      `T` - DataType or derived type
    Parameters:
      `name` - `DataType` name
      `clazz` - expected DataType class
    Returns:
      DataType or null if not found

  - ### getTypeOrDefault

    public <T extends DataType> T getTypeOrDefault(String name, Class<T> clazz, T defaultValue)
    Returns a named `DataType`, searching the registered `program` and `archive` category paths.

    DataTypes that were found in the attached archive gdt manager will be copied into the program's data type manager before being returned.

    Type Parameters:
      `T` - DataType or derived type
    Parameters:
      `name` - `DataType` name
      `clazz` - expected DataType class
      `defaultValue` - value to return if the requested data type was not found
    Returns:
      DataType or `defaultValue` if not found

  - ### getDTM

    public DataTypeManager getDTM()
    Returns the program's data type manager.
    Returns:
      program's `DataTypeManager`

  - ### getStructureContextOfInstance

    public <T> StructureContext<T> getStructureContextOfInstance(T structureInstance)
    Returns the `StructureContext` of a structure mapped instance.
    Type Parameters:
      `T` - java type of a class that is structure mapped
    Parameters:
      `structureInstance` - an existing instance of type T
    Returns:
      `StructureContext` of the instance, or null if instance was null or not a structure mapped object

  - ### getAddressOfStructure

    public <T> Address getAddressOfStructure(T structureInstance)
    Attempts to convert an instance of an object (that represents a chunk of memory in the program) into its Address.
    Type Parameters:
      `T` - type of the object
    Parameters:
      `structureInstance` - instance of an object that represents something in the program's memory
    Returns:
      `Address` of the object, or null if not found or not a supported object

  - ### getMaxAddressOfStructure

    public <T> Address getMaxAddressOfStructure(T structureInstance)
    Returns the address of the last byte of a structure.
    Type Parameters:
      `T` - type of object
    Parameters:
      `structureInstance` - instance of an object that represents something in the program's memory
    Returns:
      `Address` of the last byte of the object, or null if not found or not a supported object

  - ### readStructure

    public <T> T readStructure(Class<T> structureClass, BinaryReader structReader) throws IOException
    Reads a structure mapped object from the current position of the specified BinaryReader.
    Type Parameters:
      `T` - type of object
    Parameters:
      `structureClass` - structure mapped object class
      `structReader` - `BinaryReader` positioned at the start of an object
    Returns:
      new object instance of type T
    Throws:
      `IOException` - if error reading
      `IllegalArgumentException` - if specified structureClass is not valid

  - ### readStructure

    public <T> T readStructure(Class<T> structureClass, DataType containingFieldDataType, BinaryReader structReader) throws IOException
    Reads a structure mapped object from the current position of the specified BinaryReader.
    Type Parameters:
      `T` - type of object
    Parameters:
      `structureClass` - structure mapped object class
      `containingFieldDataType` - optional, data type of the structure field that contained the object instance that is being read (may be different than the data type that was specified in the matching `StructureMappingInfo`)
      `structReader` - `BinaryReader` positioned at the start of an object
    Returns:
      new object instance of type T
    Throws:
      `IOException` - if error reading
      `IllegalArgumentException` - if specified structureClass is not valid

  - ### readStructure

    public <T> T readStructure(Class<T> structureClass, long position) throws IOException
    Reads a structure mapped object from the specified position of the program.
    Type Parameters:
      `T` - type of object
    Parameters:
      `structureClass` - structure mapped object class
      `position` - of object
    Returns:
      new object instance of type T
    Throws:
      `IOException` - if error reading
      `IllegalArgumentException` - if specified structureClass is not valid

  - ### readStructure

    public <T> T readStructure(Class<T> structureClass, Address address) throws IOException
    Reads a structure mapped object from the specified Address of the program.
    Type Parameters:
      `T` - type of object
    Parameters:
      `structureClass` - structure mapped object class
      `address` - location of object
    Returns:
      new object instance of type T
    Throws:
      `IOException` - if error reading
      `IllegalArgumentException` - if specified structureClass is not valid

  - ### getReader

    public BinaryReader getReader(long position)
    Creates a `BinaryReader`, at the specified position.
    Parameters:
      `position` - location in the program
    Returns:
      new `BinaryReader`

  - ### getDataAddress

    public Address getDataAddress(long offset)
    Converts an offset into an Address.
    Parameters:
      `offset` - numeric offset
    Returns:
      `Address`

  - ### getCodeAddress

    public Address getCodeAddress(long offset)
    Converts an offset into an Address.
    Parameters:
      `offset` - numeric offset
    Returns:
      `Address`

  - ### toString

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

  - ### createProgramReader

    protected BinaryReader createProgramReader()
    Creates a new BinaryReader that reads bytes from the current program's memory image.

    Address offsets and index offsets in the BinaryReader should be synonymous.

    Returns:
      new BinaryReader

  - ### findType

    protected DataType findType(String name, List<CategoryPath> searchList, DataTypeManager dtm)

  - ### createArtificialStructureContext

    public <T> StructureContext<T> createArtificialStructureContext(Class<T> structureClass)
    Creates an artificial structure context to be used in some limited situations.
    Type Parameters:
      `T` - type of structure mapped object
    Parameters:
      `structureClass` - class of structure mapped object
    Returns:
      new `StructureContext`