Package ghidra.program.model.data

Interface Composite

All Superinterfaces:
DataType
All Known Subinterfaces:
CompositeInternal, Structure, StructureInternal, Union, UnionInternal
All Known Implementing Classes:
CompositeDataTypeImpl, StructureDataType, UnionDataType
public interface Composite extends DataType
Interface for common methods in Structure and Union

  • Method Details

    • setDescription

      void setDescription(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 composite. If this is Structure with packing disabled, the count will include all undefined filler components which may be present.
      Returns:
      the number of components that make up this composite

    • getNumDefinedComponents

      int getNumDefinedComponents()
      Returns the number of explicitly defined components in this composite. For Unions and packed Structures this is equivalent to getNumComponents() since they do not contain undefined components. This count will always exclude all undefined filler components which may be present within a Structure whose packing is disabled (see isPackingEnabled()).
      Returns:
      the number of explicitly defined components in this composite

    • getComponent

      DataTypeComponent getComponent(int ordinal) throws IndexOutOfBoundsException
      Returns the component of this data type with the indicated ordinal.
      Parameters:
      ordinal - the component's ordinal (numbering starts at 0).
      Returns:
      the data type component.
      Throws:
      IndexOutOfBoundsException - if the ordinal is out of bounds

    • getComponents

      DataTypeComponent[] getComponents()
      Returns an array of Data Type Components that make up this composite including undefined filler components which may be present within a Structure which has packing disabled. The number of components corresponds to getNumComponents().
      Returns:
      array all components

    • getDefinedComponents

      DataTypeComponent[] getDefinedComponents()
      Returns an array of Data Type Components that make up this composite excluding undefined filler components which may be present within Structures where packing is disabled. The number of components corresponds to getNumDefinedComponents(). For Unions and packed Structures this is equivalent to getComponents() since they do not contain undefined filler components.
      Returns:
      array all explicitly defined components

    • add

      DataTypeComponent add(DataType dataType) throws IllegalArgumentException
      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:
      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) throws IllegalArgumentException
      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:
      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, String name, String comment) throws IllegalArgumentException
      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:
      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, String componentName, String comment) throws InvalidDataTypeException
      Adds a new bitfield to the end of this composite. This method is intended to be used with packed 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 for composites with packing disabled.
      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, String name, String comment) throws IllegalArgumentException
      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:
      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) throws IndexOutOfBoundsException, IllegalArgumentException
      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 (numbering starts at 0).
      dataType - the datatype to insert.
      Returns:
      the componentDataType created.
      Throws:
      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.
      IndexOutOfBoundsException - if component ordinal is out of bounds

    • insert

      DataTypeComponent insert(int ordinal, DataType dataType, int length) throws IndexOutOfBoundsException, IllegalArgumentException
      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 (numbering starts at 0).
      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:
      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.
      IndexOutOfBoundsException - if component ordinal is out of bounds

    • insert

      DataTypeComponent insert(int ordinal, DataType dataType, int length, String name, String comment) throws IndexOutOfBoundsException, IllegalArgumentException
      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 (numbering starts at 0).
      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:
      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.
      IndexOutOfBoundsException - if component ordinal is out of bounds

    • delete

      void delete(int ordinal) throws IndexOutOfBoundsException
      Deletes the component at the given ordinal position.
      Note: Removal of bitfields from a structure with packing disabled will not shift other components causing vacated bytes to revert to undefined filler.
      Parameters:
      ordinal - the ordinal of the component to be deleted (numbering starts at 0).
      Throws:
      IndexOutOfBoundsException - if component ordinal is out of bounds

    • delete

      void delete(Set<Integer> ordinals) throws IndexOutOfBoundsException
      Deletes the specified set of components at the given ordinal positions.
      Note: Removal of bitfields from a structure with packing disabled will not shift other components causing vacated bytes to revert to undefined filler.
      Parameters:
      ordinals - the ordinals of the component to be deleted.
      Throws:
      IndexOutOfBoundsException - 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.

    • dataTypeAlignmentChanged

      void dataTypeAlignmentChanged(DataType dt)
      The alignment changed for the specified data type. If packing is enabled for this composite, the placement of the component may be affected by a change in its alignment. A non-packed composite can ignore this notification.
      Specified by:
      dataTypeAlignmentChanged in interface DataType
      Parameters:
      dt - the data type whose alignment changed.

    • repack

      void repack()
      Updates packed composite to any changes in the data organization. If the composite does not have packing enabled this method does nothing.
      NOTE: Changes to data organization is discouraged. Attempts to use this method in such cases should be performed on all composites in dependency order (ignoring pointer components).

    • getPackingType

      PackingType getPackingType()
      Returns:
      the packing type set for this composite

    • isPackingEnabled

      default boolean isPackingEnabled()
      Determine if this data type has its internal components currently packed based upon alignment and packing settings. If disabled, component placement is based upon explicit placement by offset.
      Returns:
      true if this data type's components auto-packed

    • setPackingEnabled

      void setPackingEnabled(boolean enabled)
      Sets whether this data type's internal components are currently packed. The affect of disabled packing differs between Structure and Union. When packing disabled:
      • Structures utilize explicit component offsets and produce undefined filler components where defined components do not consume space.
      • Unions always place components at offset 0 and do not pad for alignment.
      In addition, when packing is disabled the default alignment is always 1 unless a different minimum alignment has been set. When packing is enabled the overall composite length influenced by the composite's minimum alignment setting. If a change in enablement occurs, the default alignment and packing behavior will be used.
      Parameters:
      enabled - true enables packing of components respecting component alignment and pack setting, whereas false disables packing.

    • hasExplicitPackingValue

      default boolean hasExplicitPackingValue()
      Determine if packing is enabled with an explicit packing value (see getExplicitPackingValue()).
      Returns:
      true if packing is enabled with an explicit packing value, else false.

    • hasDefaultPacking

      default boolean hasDefaultPacking()
      Determine if default packing is enabled.
      Returns:
      true if default packing is enabled.

    • getExplicitPackingValue

      int getExplicitPackingValue()
      Gets the current packing value (typically a power of 2). If this isn't a packed composite with an explicit packing value (see hasExplicitPackingValue()) then the return value is undefined.
      Returns:
      the current packing value or an undefined non-positive value

    • setExplicitPackingValue

      void setExplicitPackingValue(int packingValue)
      Sets the pack value for this composite (positive value, usually a power of 2). If packing was previously disabled, packing will be enabled. This value will establish the maximum effective alignment for this composite and each of the components during the alignment computation (e.g., a value of 1 will eliminate any padding). The overall composite length may be influenced by the composite's minimum alignment setting.
      Parameters:
      packingValue - the new positive packing value.
      Throws:
      IllegalArgumentException - if a non-positive value is specified.

    • pack

      default void pack(int packingValue)
      Same as setExplicitPackingValue(int).
      Parameters:
      packingValue - the new positive packing value.
      Throws:
      IllegalArgumentException - if a non-positive value is specified.

    • setToDefaultPacking

      void setToDefaultPacking()
      Enables default packing behavior. If packing was previously disabled, packing will be enabled. Composite will automatically pack based upon the alignment requirements of its components with overall composite length possibly influenced by the composite's minimum alignment setting.

    • getAlignment

      int getAlignment()
      Get the computed alignment for this composite based upon packing and minimum alignment settings as well as component alignment. If packing is disabled, the alignment will always be 1 unless a minimum alignment has been set.
      Specified by:
      getAlignment in interface DataType
      Returns:
      this composites alignment

    • getAlignmentType

      AlignmentType getAlignmentType()
      Returns:
      the alignment type set for this composite

    • isDefaultAligned

      default boolean isDefaultAligned()
      Whether or not this data type is using the default alignment. When Structure packing is disabled the default alignment is always 1 (see setPackingEnabled(boolean).
      Returns:
      true if this data type is using its default alignment.

    • isMachineAligned

      default boolean isMachineAligned()
      Whether or not this data type is using the machine alignment value, specified by DataOrganization.getMachineAlignment(), for its alignment.
      Returns:
      true if this data type is using the machine alignment as its alignment.

    • hasExplicitMinimumAlignment

      default boolean hasExplicitMinimumAlignment()
      Determine if an explicit minimum alignment has been set (see getExplicitMinimumAlignment()). An undefined value is returned if default alignment or machine alignment is enabled.
      Returns:
      true if an explicit minimum alignment has been set, else false

    • getExplicitMinimumAlignment

      int getExplicitMinimumAlignment()
      Get the explicit minimum alignment setting for this Composite which contributes to the actual computed alignment value (see getAlignment().
      Returns:
      the minimum alignment setting for this Composite or an undefined non-positive value if an explicit minimum alignment has not been set.

    • setExplicitMinimumAlignment

      void setExplicitMinimumAlignment(int minAlignment)
      Sets this data type's explicit minimum alignment (positive value). Together with the pack setting and component alignments will affect the actual computed alignment of this composite. When packing is enabled, the alignment setting may also affect padding at the end of the composite and its length. When packing is disabled, this setting will not affect the length of this composite.
      Parameters:
      minAlignment - the minimum alignment for this Composite.
      Throws:
      IllegalArgumentException - if a non-positive value is specified

    • align

      default void align(int minAlignment)
      Same as setExplicitMinimumAlignment(int).
      Parameters:
      minAlignment - the explicit minimum alignment for this Composite.
      Throws:
      IllegalArgumentException - if a non-positive value is specified

    • setToDefaultAligned

      void setToDefaultAligned()
      Sets this data type's alignment to its default alignment. For packed composites, this data type's alignment will be based upon the components it contains and its current pack settings. This is the default state and only needs to be used when changing from a non-default alignment type.

    • setToMachineAligned

      void setToMachineAligned()
      Sets this data type's minimum alignment to the machine alignment which is specified by DataOrganization.getMachineAlignment(). The machine alignment is defined as the maximum useful alignment for the target machine.