Package ghidra.program.model.data

Interface Composite

All Superinterfaces:

DataType

All Known Subinterfaces:

Structure, Union

All Known Implementing Classes:

CompositeDataTypeImpl, StructureDataType, UnionDataType

public interface Composite
extends DataType

Interface for common methods in Structure and Union

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Composite.AlignmentType	AlignmentType defined the three states for the type of alignment of a composite data type.
static interface	Composite.NamedAlignment

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_ALIGNMENT_VALUE
static int	NOT_PACKING

Fields inherited from interface ghidra.program.model.data.DataType

CONFLICT_SUFFIX, DEFAULT, NO_LAST_CHANGE_TIME, NO_SOURCE_SYNC_TIME, VOID

Method Summary

Modifier and Type	Method	Description
DataTypeComponent	add(DataType dataType)	Adds a new datatype to the end of this composite.
DataTypeComponent	add(DataType dataType, int length)	Adds a new datatype to the end of this composite.
DataTypeComponent	add(DataType dataType, int length, java.lang.String name, java.lang.String comment)	Adds a new datatype to the end of this composite.
DataTypeComponent	add(DataType dataType, java.lang.String name, java.lang.String comment)	Adds a new datatype to the end of this composite.
DataTypeComponent	addBitField(DataType baseDataType, int bitSize, java.lang.String componentName, java.lang.String comment)	Adds a new bitfield to the end of this composite.
void	dataTypeAlignmentChanged(DataType dt)	The overall (external) alignment changed for the specified data type.
void	delete(int ordinal)	Deletes the component at the given ordinal position.
void	delete(int[] ordinals)	Deletes the components at the given ordinal positions.
default BitFieldPacking	getBitFieldPacking()	Get the bitfield packing information associated with the underlying data organization.
DataTypeComponent	getComponent(int ordinal)	Returns the component of this data type with the indicated ordinal.
DataTypeComponent[]	getComponents()	Returns an array of Data Type Components that make up this data type.
int	getMinimumAlignment()	Get the external alignment (a minimum alignment) for this DataType.
int	getNumComponents()	Gets the number of component data types in this data type.
int	getPackingValue()	Gets the current packing value (typically a power of 2).
DataTypeComponent	insert(int ordinal, DataType dataType)	Inserts a new datatype at the specified ordinal position in this composite.
DataTypeComponent	insert(int ordinal, DataType dataType, int length)	Inserts a new datatype at the specified ordinal position in this composite.
DataTypeComponent	insert(int ordinal, DataType dataType, int length, java.lang.String name, java.lang.String comment)	Inserts a new datatype at the specified ordinal position in this composite.
boolean	isDefaultAligned()	Whether or not this data type is using the default external (minimum) alignment.
boolean	isInternallyAligned()	Determine if this data type has its internal components currently aligned.
boolean	isMachineAligned()	Whether or not this data type is using the machine alignment value from the DataOrganization for its external (minimum) alignment.
boolean	isPartOf(DataType dataType)	Check if a data type is part of this data type.
void	realign()	Updates the composite to any changes in the data organization.
void	setDescription(java.lang.String desc)	Sets the string describing this data type.
void	setInternallyAligned(boolean aligned)	Sets whether this data type's internal components are currently aligned or unaligned.
void	setMinimumAlignment(int minimumAlignment)	Sets the external alignment (a minimum alignment) for this DataType.
void	setPackingValue(int packingValue)	Sets the current packing value (usually a power of 2).
void	setToDefaultAlignment()	Sets this data type's external (minimum) alignment to the default alignment.
void	setToMachineAlignment()	Sets this data type's external (minimum) alignment to a multiple of the machine alignment that is specified in the DataOrganization.

Methods inherited from interface ghidra.program.model.data.DataType

addParent, clone, copy, dataTypeDeleted, dataTypeNameChanged, dataTypeReplaced, dataTypeSizeChanged, dependsOn, getAlignment, getCategoryPath, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDefaultLabelPrefix, getDefaultLabelPrefix, getDefaultOffcutLabelPrefix, getDefaultSettings, getDescription, getDisplayName, getDocs, getLastChangeTime, getLastChangeTimeInSourceArchive, getLength, getMnemonic, getName, getParents, getPathName, getRepresentation, getSettingsDefinitions, getSourceArchive, getUniversalID, getValue, getValueClass, isDeleted, isDynamicallySized, isEquivalent, isNotYetDefined, removeParent, replaceWith, setCategoryPath, setDefaultSettings, setLastChangeTime, setLastChangeTimeInSourceArchive, setName, setNameAndCategory, setSourceArchive

Field Detail

DEFAULT_ALIGNMENT_VALUE

static final int DEFAULT_ALIGNMENT_VALUE

See Also:

Constant Field Values

NOT_PACKING

static final int NOT_PACKING

See Also:

Constant Field Values

Method Detail

setDescription

void setDescription(java.lang.String desc)

Sets the string describing this data type.

Specified by:

setDescription in interface DataType

Parameters:

desc - the new description.

getNumComponents

int getNumComponents()

Gets the number of component data types in this data type.

Returns:

the number of components that make up this data prototype

getComponent

DataTypeComponent getComponent(int ordinal)

Returns the component of this data type with the indicated ordinal.

Parameters:

ordinal - the component's ordinal (zero based).

Returns:

the data type component.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the ordinal is out of bounds

getComponents

DataTypeComponent[] getComponents()

Returns an array of Data Type Components that make up this data type. Returns an array of length 0 if there are no subcomponents.

add

DataTypeComponent add(DataType dataType)

Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for fixed-length dataTypes.

Parameters:

dataType - the datatype to add.

Returns:

the DataTypeComponent created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be added to this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

add

DataTypeComponent add(DataType dataType,
                      int length)

Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for dynamic dataTypes such as strings whose length must be specified.

Parameters:

dataType - the datatype to add.

length - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be added to this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

add

DataTypeComponent add(DataType dataType,
                      java.lang.String name,
                      java.lang.String comment)

Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for fixed-length dataTypes.

Parameters:

dataType - the datatype to add.

name - the field name to associate with this component.

comment - the comment to associate with this component.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be added to this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

addBitField

DataTypeComponent addBitField(DataType baseDataType,
                              int bitSize,
                              java.lang.String componentName,
                              java.lang.String comment)
                       throws InvalidDataTypeException

Adds a new bitfield to the end of this composite. This method is intended to be used with aligned structures/unions only where the bitfield will be appropriately packed. The minimum storage storage byte size will be applied. It will not provide useful results within unaligned composites.

Parameters:

baseDataType - the bitfield base datatype (certain restrictions apply).

bitSize - the bitfield size in bits

componentName - the field name to associate with this component.

comment - the comment to associate with this component.

Returns:

the componentDataType created whose associated data type will be BitFieldDataType.

Throws:

InvalidDataTypeException - if the specified data type is not a valid base type for bitfields.

add

DataTypeComponent add(DataType dataType,
                      int length,
                      java.lang.String name,
                      java.lang.String comment)

Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for dynamic dataTypes such as strings whose length must be specified.

Parameters:

dataType - the datatype to add.

length - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.

name - the field name to associate with this component.

comment - the comment to associate with this component.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be added to this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

insert

DataTypeComponent insert(int ordinal,
                         DataType dataType)

Inserts a new datatype at the specified ordinal position in this composite.
Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.

Parameters:

ordinal - the ordinal where the new datatype is to be inserted.

dataType - the datatype to insert.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be inserted into this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.

java.lang.ArrayIndexOutOfBoundsException - if component ordinal is out of bounds

insert

DataTypeComponent insert(int ordinal,
                         DataType dataType,
                         int length)

Inserts a new datatype at the specified ordinal position in this composite.
Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.

Parameters:

ordinal - the ordinal where the new datatype is to be inserted.

dataType - the datatype to insert.

length - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be inserted into this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.

java.lang.ArrayIndexOutOfBoundsException - if component ordinal is out of bounds

insert

DataTypeComponent insert(int ordinal,
                         DataType dataType,
                         int length,
                         java.lang.String name,
                         java.lang.String comment)

Inserts a new datatype at the specified ordinal position in this composite.
Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.

Parameters:

ordinal - the ordinal where the new datatype is to be inserted.

dataType - the datatype to insert.

length - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.

name - the field name to associate with this component.

comment - the comment to associate with this component.

Returns:

the componentDataType created.

Throws:

java.lang.IllegalArgumentException - if the specified data type is not allowed to be inserted into this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.

java.lang.ArrayIndexOutOfBoundsException - if component ordinal is out of bounds

delete

void delete(int ordinal)

Deletes the component at the given ordinal position.
Note: Removal of bitfields from an unaligned structure will not shift other components with vacated bytes reverting to undefined.

Parameters:

ordinal - the ordinal of the component to be deleted.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if component ordinal is out of bounds

delete

void delete(int[] ordinals)

Deletes the components at the given ordinal positions.
Note: Removal of bitfields from an unaligned structure will not shift other components with vacated bytes reverting to undefined.

Parameters:

ordinals - the ordinals of the component to be deleted.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if any specified component ordinal is out of bounds

isPartOf

boolean isPartOf(DataType dataType)

Check if a data type is part of this data type. A data type could be part of another by:
Being the same data type.
containing the data type directly
containing another data type that has the data type as a part of it.

Parameters:

dataType - the data type to look for.

Returns:

true if the indicated data type is part of a sub-component of this data type.

realign

void realign()

Updates the composite to any changes in the data organization. If the composite is not internally aligned, this method does nothing.

isInternallyAligned

boolean isInternallyAligned()

Determine if this data type has its internal components currently aligned.

Returns:

true if this data type's components are aligned relative to each other using the current data organization. When internally aligned the end of this data type will be padded to a multiple of its actual alignment.

setInternallyAligned

void setInternallyAligned(boolean aligned)

Sets whether this data type's internal components are currently aligned or unaligned.

Parameters:

aligned - true means align the internal components of this data type. false means don't align it. True also causes the end of this data type to be padded to a multiple of its actual alignment.

dataTypeAlignmentChanged

void dataTypeAlignmentChanged(DataType dt)

The overall (external) alignment changed for the specified data type. In other words, the data type has a different alignment when placed inside other structures.

Parameters:

dt - the data type whose alignment changed.

getPackingValue

int getPackingValue()

Gets the current packing value (typically a power of 2). If this isn't a packed data type then NOT_PACKING is returned. The packing value only pertains to internally aligned composite data types. Aligned structures allow packing.

Returns:

the current packing value or NOT_PACKING.

setPackingValue

void setPackingValue(int packingValue)

Sets the current packing value (usually a power of 2). A value of NOT_PACKING should be passed if this isn't a packed data type. Otherwise this value indicates a maximum alignment for any component within this data type. Calling this method will cause the data type to become an internally aligned data type.
Note: If a component's data type has a specific external alignment, it will override this value if necessary.

Parameters:

packingValue - the new packing value or 0 for NOT_PACKING. A negative value will be treated the same as 0.

getMinimumAlignment

int getMinimumAlignment()

Get the external alignment (a minimum alignment) for this DataType. This controls where this data type will get aligned within other data types. It also causes the end of this data type to get padded so its length is a multiple of the alignment.

Returns:

the external alignment for this DataType or DEFAULT_ALIGNMENT_VALUE.

setMinimumAlignment

void setMinimumAlignment(int minimumAlignment)

Sets the external alignment (a minimum alignment) for this DataType. This controls where this data type will get aligned within other data types. It also causes the end of this data type to get padded so its length is a multiple of the alignment. Calling this method will cause the data type to become an internally aligned data type.

Parameters:

minimumAlignment - the external (minimum) alignment for this DataType. Any value less than 1 will revert to default alignment.

setToDefaultAlignment

void setToDefaultAlignment()

Sets this data type's external (minimum) alignment to the default alignment. This data type's external alignment will be based upon the components it contains. This should be used when a data type doesn't have an alignment attribute specified. Calling this method will cause the data type to become an internally aligned data type.

setToMachineAlignment

void setToMachineAlignment()

Sets this data type's external (minimum) alignment to a multiple of the machine alignment that is specified in the DataOrganization. The machine alignment is defined as the maximum useful alignment for the target machine. This should be used when a data type has an alignment attribute specified without a size (indicating to use the machine alignment). Calling this method will cause the data type to become an internally aligned data type.

isDefaultAligned

boolean isDefaultAligned()

Whether or not this data type is using the default external (minimum) alignment.

Returns:

true if this data type has the default external alignment.

isMachineAligned

boolean isMachineAligned()

Whether or not this data type is using the machine alignment value from the DataOrganization for its external (minimum) alignment.

Returns:

true if this data type is using the machine alignment as the minimum alignment.

getBitFieldPacking

default BitFieldPacking getBitFieldPacking()

Get the bitfield packing information associated with the underlying data organization.

Returns:

bitfield packing information