Package ghidra.program.model.pcode

Interface Decoder

All Superinterfaces:
ByteIngest
All Known Implementing Classes:
PackedDecode, PackedDecodeOverlay
public interface Decoder extends ByteIngest
An interface for reading structured data from a stream All data is loosely structured as with an XML document. A document contains a nested set of elements, with labels corresponding to the ElementId class. A single element can hold zero or more attributes and zero or more child elements. An attribute holds a primitive data element (boolean, long, String) and is labeled by an AttributeId. The document is traversed using a sequence of openElement() and closeElement() calls, intermixed with read*() calls to extract the data. The elements are traversed in a depth first order. Attributes within an element can be traversed in order using repeated calls to the getNextAttributeId() method, followed by a calls to one of the read*(void) methods to extract the data. Alternately a read*(AttributeId) call can be used to extract data for an attribute known to be in the element. There is a special content attribute whose data can be extracted using a read*(AttributeId) call that is passed the special ATTRIB_CONTENT id. This attribute will not be traversed by getNextAttributeId().

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    closeElement(int id)
    Close the current element The data for the current element is considered fully processed.
    void
    closeElementSkipping(int id)
    Close the current element, skipping any child elements that have not yet been parsed.
    AddressFactory
    getAddressFactory()
     
    int
    getIndexedAttributeId(AttributeId attribId)
    Get the id for the (current) attribute, assuming it is indexed.
    int
    getNextAttributeId()
    Get the next attribute id for the current element Attributes are automatically set up for traversal using this method, when the element is opened.
    int
    openElement()
    Open (traverse into) the next child element of the current parent.
    int
    openElement(ElementId elemId)
    Open (traverse into) the next child element, which must be of a specific type The child becomes the current parent, and its attributes are initialized for use with getNextAttributeId.
    int
    peekElement()
    Peek at the next child element of the current parent, without traversing in (opening) it.
    boolean
    readBool()
    Parse the current attribute as a boolean value The last attribute, as returned by getNextAttributeId, is treated as a boolean, and its value is returned.
    boolean
    readBool(AttributeId attribId)
    Find and parse a specific attribute in the current element as a boolean value The set of attributes for the current element is searched for a match to the given attribute id.
    int
    readOpcode()
    Parse the current attribute is a p-code opcode The last attribute, as returned by getNextAttributeId, is returned as an opcode.
    int
    readOpcode(AttributeId attribId)
    Find the specific attribute in the current element and return it as an opcode Search attributes from the current element for a match to the given attribute id.
    long
    readSignedInteger()
    Parse the current attribute as a signed integer value The last attribute, as returned by getNextAttributeId, is treated as a signed integer, and its value is returned.
    long
    readSignedInteger(AttributeId attribId)
    Find and parse a specific attribute in the current element as a signed integer The set of attributes for the current element is searched for a match to the given attribute id.
    long
    readSignedIntegerExpectString(AttributeId attribId, String expect, long expectval)
    Find and parse a specific attribute in the current element as either a signed integer or a string.
    long
    readSignedIntegerExpectString(String expect, long expectval)
    Parse the current attribute as either a signed integer value or a string.
    AddressSpace
    readSpace()
    Parse the current attribute as an address space The last attribute, as returned by getNextAttributeId, is returned as an address space.
    AddressSpace
    readSpace(AttributeId attribId)
    Find the specific attribute in the current element and return it as an address space Search attributes from the current element for a match to the given attribute id.
    String
    readString()
    Parse the current attribute as a string The last attribute, as returned by getNextAttributeId, is returned as a string.
    String
    readString(AttributeId attribId)
    Find the specific attribute in the current element and return it as a string The set of attributes for the current element is searched for a match to the given attribute id.
    long
    readUnsignedInteger()
    Parse the current attribute as an unsigned integer value The last attribute, as returned by getNextAttributeId, is treated as an unsigned integer, and its value is returned.
    long
    readUnsignedInteger(AttributeId attribId)
    Find and parse a specific attribute in the current element as an unsigned integer The set of attributes for the current element is searched for a match to the given attribute id.
    void
    rewindAttributes()
    Reset attribute traversal for the current element Attributes for a single element can be traversed more than once using the getNextAttributeId method.
    void
    setAddressFactory(AddressFactory addrFactory)
     
    default void
    skipElement()
    Skip parsing of the next element The element skipped is the one that would be opened by the next call to openElement.

    Methods inherited from interface ghidra.program.model.pcode.ByteIngest

    clear, endIngest, ingestBytes, ingestStream, ingestStreamToNextTerminator, isEmpty, open

  • Method Details

    • getAddressFactory

      AddressFactory getAddressFactory()

    • setAddressFactory

      void setAddressFactory(AddressFactory addrFactory)

    • peekElement

      int peekElement() throws DecoderException
      Peek at the next child element of the current parent, without traversing in (opening) it. The element id is returned, which can be compared to ElementId labels. If there are no remaining child elements to traverse, 0 is returned.
      Returns:
      the element id or 0
      Throws:
      DecoderException - for an unexpected end of stream

    • openElement

      int openElement() throws DecoderException
      Open (traverse into) the next child element of the current parent. The child becomes the current parent. The list of attributes is initialized for use with getNextAttributeId.
      Returns:
      the id of the child element or 0 if there are no additional children
      Throws:
      DecoderException - for an unexpected end of stream

    • openElement

      int openElement(ElementId elemId) throws DecoderException
      Open (traverse into) the next child element, which must be of a specific type The child becomes the current parent, and its attributes are initialized for use with getNextAttributeId. The child must match the given element id or an exception is thrown.
      Parameters:
      elemId - is the given element id to match
      Returns:
      the id of the child element
      Throws:
      DecoderException - if the expected element is not the next element

    • closeElement

      void closeElement(int id) throws DecoderException
      Close the current element The data for the current element is considered fully processed. If the element has additional children, an exception is thrown. The stream must indicate the end of the element in some way.
      Parameters:
      id - is the id of the element to close (which must be the current element)
      Throws:
      DecoderException - if not at end of expected element

    • closeElementSkipping

      void closeElementSkipping(int id) throws DecoderException
      Close the current element, skipping any child elements that have not yet been parsed. This closes the given element, which must be current. If there are child elements that have not been parsed, this is not considered an error, and they are skipped over in the parse.
      Parameters:
      id - is the id of the element to close (which must be the current element)
      Throws:
      DecoderException - if the indicated element is not the current element

    • getNextAttributeId

      int getNextAttributeId() throws DecoderException
      Get the next attribute id for the current element Attributes are automatically set up for traversal using this method, when the element is opened. If all attributes have been traversed (or there are no attributes), 0 is returned.
      Returns:
      the id of the next attribute or 0
      Throws:
      DecoderException - for unexpected end of stream

    • getIndexedAttributeId

      int getIndexedAttributeId(AttributeId attribId) throws DecoderException
      Get the id for the (current) attribute, assuming it is indexed. Assuming the previous call to getNextAttributeId() returned the id of ATTRIB_UNKNOWN, reinterpret the attribute as being an indexed form of the given attribute. If the attribute matches, return this indexed id, otherwise return ATTRIB_UNKNOWN.
      Parameters:
      attribId - is the attribute being indexed
      Returns:
      the indexed id or ATTRIB_UNKNOWN
      Throws:
      DecoderException - for unexpected end of stream

    • rewindAttributes

      void rewindAttributes()
      Reset attribute traversal for the current element Attributes for a single element can be traversed more than once using the getNextAttributeId method.

    • readBool

      boolean readBool() throws DecoderException
      Parse the current attribute as a boolean value The last attribute, as returned by getNextAttributeId, is treated as a boolean, and its value is returned.
      Returns:
      the boolean value associated with the current attribute.
      Throws:
      DecoderException - if the expected value is not present

    • readBool

      boolean readBool(AttributeId attribId) throws DecoderException
      Find and parse a specific attribute in the current element as a boolean value The set of attributes for the current element is searched for a match to the given attribute id. This attribute is then parsed as a boolean and its value returned. If there is no attribute matching the id, an exception is thrown. Parsing via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the boolean value
      Throws:
      DecoderException - if the expected value is not present

    • readSignedInteger

      long readSignedInteger() throws DecoderException
      Parse the current attribute as a signed integer value The last attribute, as returned by getNextAttributeId, is treated as a signed integer, and its value is returned.
      Returns:
      the signed integer value associated with the current attribute.
      Throws:
      DecoderException - if the expected value is not present

    • readSignedInteger

      long readSignedInteger(AttributeId attribId) throws DecoderException
      Find and parse a specific attribute in the current element as a signed integer The set of attributes for the current element is searched for a match to the given attribute id. This attribute is then parsed as a signed integer and its value returned. If there is no attribute matching the id, an exception is thrown. Parsing via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the signed integer value
      Throws:
      DecoderException - if the expected value is not present

    • readSignedIntegerExpectString

      long readSignedIntegerExpectString(String expect, long expectval) throws DecoderException
      Parse the current attribute as either a signed integer value or a string. If the attribute is an integer, its value is returned. If the attribute is a string, it must match an expected string passed to the method, and a predetermined integer value associated with the string is returned. If the attribute string does not match, or the attribute is encoded as anything other than a string or signed integer, an exception is thrown.
      Parameters:
      expect - is the string value to expect if the attribute is encoded as a string
      expectval - is the integer value to return if the attribute matches the expected string
      Returns:
      the encoded integer or the integer value associated with the expected string
      Throws:
      DecoderException - is an integer value or expected string cannot be parsed

    • readSignedIntegerExpectString

      long readSignedIntegerExpectString(AttributeId attribId, String expect, long expectval) throws DecoderException
      Find and parse a specific attribute in the current element as either a signed integer or a string. If the attribute is an integer, its value is returned. If the attribute is encoded as a string, it must match an expected string passed to this method. In this case, a predetermined integer value is passed back, indicating a matching string was parsed. If the attribute string does not match, or the attribute is encoded as anything other than a string or signed integer, an exception is thrown.
      Parameters:
      attribId - is the specific attribute id to match
      expect - is the string to expect, if the attribute is not encoded as an integer
      expectval - is the integer value to return if the attribute matches the expected string
      Returns:
      the encoded integer or the integer value associated with the expected string
      Throws:
      DecoderException - if an integer value or expected string cannot be parsed

    • readUnsignedInteger

      long readUnsignedInteger() throws DecoderException
      Parse the current attribute as an unsigned integer value The last attribute, as returned by getNextAttributeId, is treated as an unsigned integer, and its value is returned.
      Returns:
      the unsigned integer value associated with the current attribute.
      Throws:
      DecoderException - if the expected value is not present

    • readUnsignedInteger

      long readUnsignedInteger(AttributeId attribId) throws DecoderException
      Find and parse a specific attribute in the current element as an unsigned integer The set of attributes for the current element is searched for a match to the given attribute id. This attribute is then parsed as an unsigned integer and its value returned. If there is no attribute matching the id, an exception is thrown. Parsing via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the unsigned integer value
      Throws:
      DecoderException - if the expected value is not present

    • readString

      String readString() throws DecoderException
      Parse the current attribute as a string The last attribute, as returned by getNextAttributeId, is returned as a string.
      Returns:
      the string associated with the current attribute.
      Throws:
      DecoderException - if the expected value is not present

    • readString

      String readString(AttributeId attribId) throws DecoderException
      Find the specific attribute in the current element and return it as a string The set of attributes for the current element is searched for a match to the given attribute id. This attribute is then returned as a string. If there is no attribute matching the id, and exception is thrown. Parse via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the string associated with the attribute
      Throws:
      DecoderException - if the expected value is not present

    • readSpace

      AddressSpace readSpace() throws DecoderException
      Parse the current attribute as an address space The last attribute, as returned by getNextAttributeId, is returned as an address space.
      Returns:
      the address space associated with the current attribute.
      Throws:
      DecoderException - if the expected value is not present

    • readSpace

      AddressSpace readSpace(AttributeId attribId) throws DecoderException
      Find the specific attribute in the current element and return it as an address space Search attributes from the current element for a match to the given attribute id. Return this attribute as an address space. If there is no attribute matching the id, an exception is thrown. Parse via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the address space associated with the attribute
      Throws:
      DecoderException - if the expected value is not present

    • readOpcode

      int readOpcode() throws DecoderException
      Parse the current attribute is a p-code opcode The last attribute, as returned by getNextAttributeId, is returned as an opcode. The opcode is one of the constants specified in PcodeOp
      Returns:
      the opcode associated with the current attribute
      Throws:
      DecoderException - if the expected value is not present

    • readOpcode

      int readOpcode(AttributeId attribId) throws DecoderException
      Find the specific attribute in the current element and return it as an opcode Search attributes from the current element for a match to the given attribute id. Return this attribute as an opcode constant from PcodeOp. If there is no matching attribute id, an exception is thrown. Parse via getNextAttributeId is reset.
      Parameters:
      attribId - is the specific attribute id to match
      Returns:
      the opcode associated with the attribute
      Throws:
      DecoderException - if the expected value is not present

    • skipElement

      default void skipElement() throws DecoderException
      Skip parsing of the next element The element skipped is the one that would be opened by the next call to openElement.
      Throws:
      DecoderException - if there is no new element