Package ghidra.program.model.data

Interface Structure

  • All Superinterfaces:
    Composite, DataType
    All Known Implementing Classes:
    StructureDataType
    public interface Structure
extends Composite
    The structure interface. NOTE: Structures containing only a flexible array will report a length of 1 which will result in improper code unit sizing since we are unable to support a defined data of length 0.

    • Method Detail

      • getComponent

        DataTypeComponent getComponent​(int ordinal)
        Returns the component of this structure with the indicated ordinal. If the specified ordinal equals getNumComponents() the defined flexible array component will be returned, otherwise an out of bounds exception will be thrown. Use of getFlexibleArrayComponent() is preferred for obtaining this special trailing component.
        Specified by:
        getComponent in interface Composite
        Parameters:
        ordinal - the component's ordinal (zero based).
        Returns:
        the data type component.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the ordinal is out of bounds

      • getComponentAt

        DataTypeComponent getComponentAt​(int offset)
        Gets the immediate child component that contains the byte at the given offset.
        Parameters:
        offset - the byte offset into this data type
        Returns:
        the immediate child component.

      • getDataTypeAt

        DataTypeComponent getDataTypeAt​(int offset)
        Returns the primitive Data Type that is at this offset. This is useful for prototypes that have components that are made up of other components
        Parameters:
        offset - the byte offset into this data type.
        Returns:
        the primitive data type at the offset.

      • insert

        DataTypeComponent insert​(int index,
                         DataType dataType)
        Description copied from interface: Composite
        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.
        Specified by:
        insert in interface Composite
        Parameters:
        index - the ordinal where the new datatype is to be inserted.
        dataType - the datatype to insert.
        Returns:
        the componentDataType created.
        See Also:
        Composite.insert(int, ghidra.program.model.data.DataType)

      • insert

        DataTypeComponent insert​(int index,
                         DataType dataType,
                         int length)
        Description copied from interface: Composite
        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.
        Specified by:
        insert in interface Composite
        Parameters:
        index - the ordinal where the new datatype is to be inserted.
        dataType - the datatype to insert.
        length - the length to associate with the datatype.
        Returns:
        the componentDataType created.
        See Also:
        Composite.insert(int, ghidra.program.model.data.DataType, int)

      • insert

        DataTypeComponent insert​(int index,
                         DataType dataType,
                         int length,
                         java.lang.String name,
                         java.lang.String comment)
        Description copied from interface: Composite
        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.
        Specified by:
        insert in interface Composite
        Parameters:
        index - the ordinal where the new datatype is to be inserted.
        dataType - the datatype to insert.
        length - the length to associate with the datatype.
        name - the field name to associate with this component.
        comment - the comment to associate with this component.
        Returns:
        the componentDataType created.
        See Also:
        Composite.insert(int, ghidra.program.model.data.DataType, int, java.lang.String, java.lang.String)

      • insert

        void insert​(int ordinal,
            DataType dataType,
            int length,
            java.lang.String name,
            java.lang.String comment,
            int numCopies)

      • delete

        void delete​(int index)
        Deletes the ComponentDataType at the given index
        Specified by:
        delete in interface Composite
        Parameters:
        index - the index of the component to be deleted.

      • insertAtOffset

        DataTypeComponent insertAtOffset​(int offset,
                                 DataType dataType,
                                 int length)
        Inserts a new datatype at the specified offset into this structure.
        Parameters:
        offset - the byte offset into the structure 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.

      • insertAtOffset

        DataTypeComponent insertAtOffset​(int offset,
                                 DataType dataType,
                                 int length,
                                 java.lang.String name,
                                 java.lang.String comment)
        Inserts a new datatype at the specified offset into this structure.
        Parameters:
        offset - the byte offset into the structure where the new datatype is to be inserted.
        dataType - the datatype to insert.
        length - the length to associate with the 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 dataType.getLength() is positive and does not match the given length parameter.
        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.

      • deleteAtOffset

        void deleteAtOffset​(int offset)
        Deletes the datatype at the specified offset in this structure.
        Parameters:
        offset - the byte offset into the structure where the datatype is to be deleted.

      • deleteAll

        void deleteAll()
        Remove all components from this structure, effectively setting the length to zero.

      • clearComponent

        void clearComponent​(int index)
        clears the defined component at the given component index. Clearing a component causes a defined component to be replaced with a number of undefined dataTypes to offset the removal of the defined dataType.
        Parameters:
        index - the index of the component to clear.

      • replace

        DataTypeComponent replace​(int index,
                          DataType dataType,
                          int length)
        Replaces the component at the given component index with a new component of the indicated data type.
        Parameters:
        index - the index where the datatype is to be replaced.
        dataType - the datatype to insert.
        length - the length of the dataType to insert
        Returns:
        the new componentDataType at the index.
        Throws:
        java.lang.IllegalArgumentException - if the specified data type is not allowed to replace a component in this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to replace a dt2 component with dt1 since this would cause a cyclic dependency.

      • replace

        DataTypeComponent replace​(int index,
                          DataType dataType,
                          int length,
                          java.lang.String name,
                          java.lang.String comment)
        Replaces the component at the given component index with a new component of the indicated data type.
        Parameters:
        index - the index where the datatype is to be replaced.
        dataType - the datatype to insert.
        length - the length to associate with the dataType;
        name - the field name to associate with this component.
        comment - the comment to associate with this component.
        Returns:
        the new componentDataType at the index.
        Throws:
        java.lang.IllegalArgumentException - if the dataType.getLength() is positive and does not match the given length parameter.
        java.lang.IllegalArgumentException - if the specified data type is not allowed to replace a component in this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to replace a dt2 component with dt1 since this would cause a cyclic dependency.

      • replaceAtOffset

        DataTypeComponent replaceAtOffset​(int offset,
                                  DataType dataType,
                                  int length,
                                  java.lang.String name,
                                  java.lang.String comment)
        Replaces the component at the specified byte offset with a new component of the indicated data type.
        Parameters:
        offset - the byte offset into the structure where the datatype is to be replaced.
        dataType - the datatype to insert.
        length - the length to associate with the dataType;
        name - the field name to associate with this component.
        comment - the comment to associate with this component.
        Returns:
        the new componentDataType at the index.
        Throws:
        java.lang.IllegalArgumentException - if the dataType.getLength() is positive and does not match the given length parameter.
        java.lang.IllegalArgumentException - if the specified data type is not allowed to replace a component in this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to replace a dt2 component with dt1 since this would cause a cyclic dependency.

      • getComponents

        DataTypeComponent[] getComponents()
        Returns a list of all components that make up this data type excluding any trailing flexible array component if present.
        Specified by:
        getComponents in interface Composite
        Returns:
        an array containing the components

      • getDefinedComponents

        DataTypeComponent[] getDefinedComponents()
        Returns the list of components that are defined. (As opposed to "filler" undefined bytes.). Any trailing flexible array component will be omitted.

      • hasFlexibleArrayComponent

        boolean hasFlexibleArrayComponent()
        Determine if a trailing flexible array component has been defined.
        Returns:
        true if trailing flexible array component has been defined.

      • getFlexibleArrayComponent

        DataTypeComponent getFlexibleArrayComponent()
        Get the optional trailing flexible array component associated with this structure.
        Returns:
        optional trailing flexible array component associated with this structure or null if not present.

      • setFlexibleArrayComponent

        DataTypeComponent setFlexibleArrayComponent​(DataType flexType,
                                            java.lang.String name,
                                            java.lang.String comment)
        Set the optional trailing flexible array component associated with this structure.
        Parameters:
        flexType - the flexible array dataType (example: for 'char[0]' the type 'char' should be specified)
        name - component field name or null for default name
        comment - component comment
        Returns:
        updated flexible array component

      • clearFlexibleArrayComponent

        void clearFlexibleArrayComponent()
        Remove the optional trailing flexible array component associated with this structure.

      • getNumComponents

        int getNumComponents()
        Gets the number of component data types in this data type excluding any trailing flexible array component if present.
        Specified by:
        getNumComponents in interface Composite
        Returns:
        the number of components that make up this data prototype

      • getNumDefinedComponents

        int getNumDefinedComponents()
        Returns the number of non-undefined components in this composite. For example, say a structure has an int (4 bytes) at offset 0 and another int at offset 8. This structure would have 6 total components (one for each undefined between the two ints), but only 2 defined components. Any trailing flexible array component will not be included in this count.
        Returns:
        the number of non-undefined components in this composite

      • growStructure

        void growStructure​(int amount)
        Increases the size of the structure by the given amount by adding undefined datatypes at the end of the structure.
        Parameters:
        amount - the amount by which to grow the structure.
        Throws:
        java.lang.IllegalArgumentException - if amount < 1