Package ghidra.program.model.data

Interface Composite

    • 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 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 java.lang.IndexOutOfBoundsException
        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.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 whch 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 java.lang.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:
        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)
               throws java.lang.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:
        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)
               throws java.lang.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:
        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 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,
                      java.lang.String name,
                      java.lang.String comment)
               throws java.lang.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:
        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)
                  throws java.lang.IndexOutOfBoundsException,
                         java.lang.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.
        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.IndexOutOfBoundsException - if component ordinal is out of bounds

      • insert

        DataTypeComponent insert​(int ordinal,
                         DataType dataType,
                         int length)
                  throws java.lang.IndexOutOfBoundsException,
                         java.lang.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.
        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.IndexOutOfBoundsException - if component ordinal is out of bounds

      • insert

        DataTypeComponent insert​(int ordinal,
                         DataType dataType,
                         int length,
                         java.lang.String name,
                         java.lang.String comment)
                  throws java.lang.IndexOutOfBoundsException,
                         java.lang.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.
        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.IndexOutOfBoundsException - if component ordinal is out of bounds

      • delete

        void delete​(int ordinal)
     throws java.lang.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.
        Throws:
        java.lang.IndexOutOfBoundsException - if component ordinal is out of bounds

      • delete

        void delete​(java.util.Set<java.lang.Integer> ordinals)
     throws java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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.