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 Details

  • 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 CategoryPaths

    • 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 CategoryPaths

    • 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