Class DataTypeMapper
- All Implemented Interfaces:
AutoCloseable
- Direct Known Subclasses:
GoRttiMapper
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
Modifier and TypeFieldDescriptionprotected DataTypeManager
protected List<CategoryPath>
protected Map<Class<?>,
StructureMappingInfo<?>> protected Program
protected DataTypeManager
protected List<CategoryPath>
-
Constructor Summary
ModifierConstructorDescriptionprotected
DataTypeMapper
(Program program, ResourceFile archiveGDT) Creates and initializes a DataTypeMapper. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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.createMarkupSession
(TaskMonitor monitor) Creates aMarkupSession
that is controlled by the specifiedTaskMonitor
.protected BinaryReader
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.getCodeAddress
(long offset) Converts an offset into an Address.getDataAddress
(long offset) Converts an offset into an Address.Returns aDataConverter
appropriate for the current program.CategoryPath location (in the program) where new data types will be created to represent variable length structures.getDTM()
Returns the program's data type manager.<T> Address
getMaxAddressOfStructure
(T structureInstance) Returns the address of the last byte of a structure.Returns the program.getReader
(long position) Creates aBinaryReader
, at the specified position.<T> StructureContext<T>
getStructureContextOfInstance
(T structureInstance) Returns theStructureContext
of a structure mapped instance.getStructureDataType
(Class<?> clazz) Returns a Ghidra structure data type representing the specified class.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 theStructureMappingInfo
for a class (that has already been registered).<T> StructureMappingInfo<T>
getStructureMappingInfo
(T structureInstance) Returns theStructureMappingInfo
for an object instance.<T extends DataType>
T<T extends DataType>
T<T extends DataType>
TgetTypeOrDefault
(String name, Class<T> clazz, T defaultValue) <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 hasstructure mapping
information.void
registerStructures
(List<Class<?>> classes) Registers the specifiedstructure mapping
classes.toString()
-
Field Details
-
program
-
programDTM
-
archiveDTM
-
programSearchCPs
-
archiveSearchCPs
-
mappingInfo
-
-
Constructor Details
-
DataTypeMapper
Creates and initializes a DataTypeMapper.- Parameters:
program
- theProgram
that will contain the deserialized dataarchiveGDT
- path to a gdt data type archive that will be searched when agetType(String, Class)
is called, ornull
if no archive- Throws:
IOException
- if error opening data type archive
-
-
Method Details
-
close
public void close()- Specified by:
close
in interfaceAutoCloseable
-
getDefaultVariableLengthStructCategoryPath
CategoryPath location (in the program) where new data types will be created to represent variable length structures.- Returns:
CategoryPath
, default is ROOT
-
getProgram
Returns the program.- Returns:
- ghidra
Program
-
createMarkupSession
Creates aMarkupSession
that is controlled by the specifiedTaskMonitor
.- Parameters:
monitor
-TaskMonitor
- Returns:
- new
MarkupSession
-
getDataConverter
Returns aDataConverter
appropriate for the current program.- Returns:
DataConverter
-
addProgramSearchCategoryPath
Adds category paths to a search list, used when looking for a data type.- Parameters:
paths
- vararg list ofCategoryPath
s
-
addArchiveSearchCategoryPath
Adds category paths to a search list, used when looking for a data type.- Parameters:
paths
- vararg list ofCategoryPath
s
-
registerStructure
Registers a class that hasstructure mapping
information.- Type Parameters:
T
- structure mapped class type- Parameters:
clazz
- class that represents a structure, marked withStructureMapping
annotation- Throws:
IOException
- if the class's Ghidra structure data type could not be found
-
registerStructures
Registers the specifiedstructure mapping
classes.- Parameters:
classes
- list of classes to register- Throws:
IOException
- if a class's Ghidra structure data type could not be found
-
getStructureMappingInfo
Returns theStructureMappingInfo
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 previouslyregistered
-
getStructureMappingInfo
Returns theStructureMappingInfo
for an object instance.- Type Parameters:
T
- structure mapped class type- Parameters:
structureInstance
- an instance of a previously registeredstructure mapping
class, or null- Returns:
StructureMappingInfo
for the instance, or null if the class was not previouslyregistered
-
getStructureDataType
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
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
Returns a namedDataType
, searching the registeredprogram
andarchive
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
nameclazz
- expected DataType class- Returns:
- DataType or null if not found
-
getType
Returns a namedDataType
, searching the registeredprogram
andarchive
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:
names
- list containing the data type name and any alternatesclazz
- expected DataType class- Returns:
- DataType or null if not found
-
getTypeOrDefault
Returns a namedDataType
, searching the registeredprogram
andarchive
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
nameclazz
- expected DataType classdefaultValue
- value to return if the requested data type was not found- Returns:
- DataType or
defaultValue
if not found
-
getDTM
Returns the program's data type manager.- Returns:
- program's
DataTypeManager
-
getStructureContextOfInstance
Returns theStructureContext
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
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
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
Reads a structure mapped object from the current position of the specified BinaryReader.- Type Parameters:
T
- type of object- Parameters:
structureClass
- structure mapped object classstructReader
-BinaryReader
positioned at the start of an object- Returns:
- new object instance of type T
- Throws:
IOException
- if error readingIllegalArgumentException
- 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 classcontainingFieldDataType
- 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 matchingStructureMappingInfo
)structReader
-BinaryReader
positioned at the start of an object- Returns:
- new object instance of type T
- Throws:
IOException
- if error readingIllegalArgumentException
- if specified structureClass is not valid
-
readStructure
Reads a structure mapped object from the specified position of the program.- Type Parameters:
T
- type of object- Parameters:
structureClass
- structure mapped object classposition
- of object- Returns:
- new object instance of type T
- Throws:
IOException
- if error readingIllegalArgumentException
- if specified structureClass is not valid
-
readStructure
Reads a structure mapped object from the specified Address of the program.- Type Parameters:
T
- type of object- Parameters:
structureClass
- structure mapped object classaddress
- location of object- Returns:
- new object instance of type T
- Throws:
IOException
- if error readingIllegalArgumentException
- if specified structureClass is not valid
-
getReader
Creates aBinaryReader
, at the specified position.- Parameters:
position
- location in the program- Returns:
- new
BinaryReader
-
getDataAddress
Converts an offset into an Address.- Parameters:
offset
- numeric offset- Returns:
Address
-
getCodeAddress
Converts an offset into an Address.- Parameters:
offset
- numeric offset- Returns:
Address
-
toString
-
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
-
createArtificialStructureContext
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
-