Package ghidra.program.model.symbol

# Interface ReferenceManager

All Known Implementing Classes:
  `ReferenceDBManager`

public interface ReferenceManager
Interface for managing references.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `MNEMONIC`
  Operand index which corresponds to the instruction/data mnemonic.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Reference`
  `addExternalReference(Address fromAddr, int opIndex, ExternalLocation location, SourceType source, RefType type)`
  Adds an external reference.
  `Reference`
  `addExternalReference(Address fromAddr, Namespace extNamespace, String extLabel, Address extAddr, SourceType source, int opIndex, RefType type)`
  Adds an external reference.
  `Reference`
  `addExternalReference(Address fromAddr, String libraryName, String extLabel, Address extAddr, SourceType source, int opIndex, RefType type)`
  Adds an external reference to an external symbol.
  `Reference`
  `addMemoryReference(Address fromAddr, Address toAddr, RefType type, SourceType source, int opIndex)`
  Adds a memory reference.
  `Reference`
  `addOffsetMemReference(Address fromAddr, Address toAddr, boolean toAddrIsBase, long offset, RefType type, SourceType source, int opIndex)`
  Add an offset memory reference.
  `Reference`
  `addReference(Reference reference)`
  Add a memory, stack, register or external reference
  `Reference`
  `addRegisterReference(Address fromAddr, int opIndex, Register register, RefType type, SourceType source)`
  Add a reference to a register.
  `Reference`
  `addShiftedMemReference(Address fromAddr, Address toAddr, int shiftValue, RefType type, SourceType source, int opIndex)`
  Add a shifted memory reference; the "to" address is computed as the value at the operand at opIndex shifted by some number of bits, specified in the shiftValue parameter.
  `Reference`
  `addStackReference(Address fromAddr, int opIndex, int stackOffset, RefType type, SourceType source)`
  Add a reference to a stack location.
  `void`
  `delete(Reference ref)`
  Deletes the given reference object
  `ReferenceIterator`
  `getExternalReferences()`
  Returns an iterator over all external space references
  `Reference[]`
  `getFlowReferencesFrom(Address addr)`
  Get all flow references from the given address.
  `Reference`
  `getPrimaryReferenceFrom(Address addr, int opIndex)`
  Get the primary reference from the given address.
  `Reference`
  `getReference(Address fromAddr, Address toAddr, int opIndex)`
  Get the reference that has the given from and to address, and operand index.
  `int`
  `getReferenceCountFrom(Address fromAddr)`
  Returns the number of references from the specified `fromAddr`.
  `int`
  `getReferenceCountTo(Address toAddr)`
  Returns the number of references to the specified `toAddr`.
  `int`
  `getReferenceDestinationCount()`
  Return the number of references for "to" addresses.
  `AddressIterator`
  `getReferenceDestinationIterator(Address startAddr, boolean forward)`
  Returns an iterator over all addresses that are the "To" address in a reference.
  `AddressIterator`
  `getReferenceDestinationIterator(AddressSetView addrSet, boolean forward)`
  Returns an iterator over all addresses that are the "To" address in a memory reference, restricted by the given address set.
  `Variable`
  `getReferencedVariable(Reference reference)`
  Returns the referenced function variable.
  `ReferenceIterator`
  `getReferenceIterator(Address startAddr)`
  Get an iterator over references starting with the specified fromAddr.
  `byte`
  `getReferenceLevel(Address toAddr)`
  Returns the reference level for the references to the given address
  `Reference[]`
  `getReferencesFrom(Address addr)`
  Get all references "from" the specified addr.
  `Reference[]`
  `getReferencesFrom(Address fromAddr, int opIndex)`
  Returns all references "from" the given fromAddr and operand (specified by opIndex).
  `int`
  `getReferenceSourceCount()`
  Return the number of references for "from" addresses.
  `AddressIterator`
  `getReferenceSourceIterator(Address startAddr, boolean forward)`
  Returns an iterator over addresses that are the "From" address in a reference
  `AddressIterator`
  `getReferenceSourceIterator(AddressSetView addrSet, boolean forward)`
  Returns an iterator over all addresses that are the "From" address in a reference, restricted by the given address set.
  `ReferenceIterator`
  `getReferencesTo(Address addr)`
  Get an iterator over all references that have the given address as their "To" address.
  `Reference[]`
  `getReferencesTo(Variable var)`
  Returns all references to the given variable.
  `boolean`
  `hasFlowReferencesFrom(Address addr)`
  Return whether the given address has flow references from it.
  `boolean`
  `hasReferencesFrom(Address fromAddr)`
  Returns true if there are any memory references at the given address.
  `boolean`
  `hasReferencesFrom(Address fromAddr, int opIndex)`
  Returns true if there are any memory references at the given address/opIndex.
  `boolean`
  `hasReferencesTo(Address toAddr)`
  Return true if a memory reference exists with the given "to" address.
  `void`
  `removeAllReferencesFrom(Address fromAddr)`
  Remove all stack, external, and memory references for the given from address.
  `void`
  `removeAllReferencesFrom(Address beginAddr, Address endAddr)`
  Removes all references where "From address" is in the given range.
  `void`
  `removeAllReferencesTo(Address toAddr)`
  Remove all stack, external, and memory references for the given to address.
  `void`
  `removeAssociation(Reference ref)`
  Removes any symbol associations with the given reference.
  `void`
  `setAssociation(Symbol s, Reference ref)`
  Associates the given reference with the given symbol.
  `void`
  `setPrimary(Reference ref, boolean isPrimary)`
  Set the given reference's primary attribute
  `Reference`
  `updateRefType(Reference ref, RefType refType)`
  Uodate the reference type on a memory reference.

- ## Field Details

  - ### MNEMONIC

    static final int MNEMONIC
    Operand index which corresponds to the instruction/data mnemonic.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### addReference

    Reference addReference(Reference reference)
    Add a memory, stack, register or external reference
    Parameters:
      `reference` - reference to be added
    Returns:
      new reference

  - ### addStackReference

    Reference addStackReference(Address fromAddr, int opIndex, int stackOffset, RefType type, SourceType source)
    Add a reference to a stack location. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
    Parameters:
      `fromAddr` - "from" address within a function
      `opIndex` - operand index
      `stackOffset` - stack offset of the reference
      `type` - reference type - how the location is being referenced.
      `source` - the source of this reference
    Returns:
      new stack reference

  - ### addRegisterReference

    Reference addRegisterReference(Address fromAddr, int opIndex, Register register, RefType type, SourceType source)
    Add a reference to a register. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
    Parameters:
      `fromAddr` - "from" address
      `opIndex` - operand index
      `register` - register to add the reference to
      `type` - reference type - how the location is being referenced.
      `source` - the source of this reference
    Returns:
      new register reference

  - ### addMemoryReference

    Reference addMemoryReference(Address fromAddr, Address toAddr, RefType type, SourceType source, int opIndex)
    Adds a memory reference. The first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand. Certain reference `types` may not be specified (e.g., `RefType.FALL_THROUGH`).
    Parameters:
      `fromAddr` - address of the codeunit where the reference occurs
      `toAddr` - address of the location being referenced. Memory, stack, and register addresses are all permitted.
      `type` - reference type - how the location is being referenced.
      `source` - the source of this reference
      `opIndex` - the operand index display of the operand making this reference
    Returns:
      new memory reference
    Throws:
      `IllegalArgumentException` - if unsupported `type` is specified

  - ### addOffsetMemReference

    Reference addOffsetMemReference(Address fromAddr, Address toAddr, boolean toAddrIsBase, long offset, RefType type, SourceType source, int opIndex)
    Add an offset memory reference. The first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand. If toAddr corresponds to the EXTERNAL memory block (see `MemoryBlock.EXTERNAL_BLOCK_NAME`) the resulting offset reference will report to/base address as the same regardless of specified offset.
    Parameters:
      `fromAddr` - address for the "from"
      `toAddr` - address of the location being referenced.
      `toAddrIsBase` - if true toAddr is treated as base address, else treated as (base+offet). It is generally preferred to specify as a base address to ensure proper handling of EXTERNAL block case.
      `offset` - value added to a base address to get the toAddr
      `type` - reference type - how the location is being referenced
      `source` - the source of this reference
      `opIndex` - the operand index
    Returns:
      new offset reference

  - ### addShiftedMemReference

    Reference addShiftedMemReference(Address fromAddr, Address toAddr, int shiftValue, RefType type, SourceType source, int opIndex)
    Add a shifted memory reference; the "to" address is computed as the value at the operand at opIndex shifted by some number of bits, specified in the shiftValue parameter. The first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand.
    Parameters:
      `fromAddr` - source/from memory address
      `toAddr` - destination/to memory address computed as some `base offset value` shifted left by the number of bits specified by shiftValue. The least-significant bits of toAddr offset should be 0's based upon the specified shiftValue since this value is shifted right to calculate the base offset value.
      `shiftValue` - number of bits to shift
      `type` - reference type - how the location is being referenced
      `source` - the source of this reference
      `opIndex` - the operand index
    Returns:
      new shifted reference

  - ### addExternalReference

    Reference addExternalReference(Address fromAddr, String libraryName, String extLabel, Address extAddr, SourceType source, int opIndex, RefType type) throws InvalidInputException, DuplicateNameException
    Adds an external reference to an external symbol. If a reference already exists at `fromAddr` and `opIndex` the existing reference is replaced with a new reference. If the external symbol cannot be found, a new `Library` and/or `ExternalLocation` symbol will be created which corresponds to the specified library/file named `libraryName` and the location within that file identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `fromAddr` - from memory address (source of the reference)
      `libraryName` - name of external program
      `extLabel` - label within the external program, may be null if extAddr is not null
      `extAddr` - memory address within the external program, may be null
      `source` - the source of this reference
      `opIndex` - operand index
      `type` - reference type - how the location is being referenced
    Returns:
      new external space reference
    Throws:
      `InvalidInputException` - if `libraryName` is invalid or null, or an invalid `extlabel` is specified. Names with spaces or the empty string are not permitted. Neither `extLabel` nor `extAddr` was specified properly.
      `DuplicateNameException` - if another non-Library namespace has the same name
      `IllegalArgumentException` - if an invalid `extAddr` was specified.

  - ### addExternalReference

    Reference addExternalReference(Address fromAddr, Namespace extNamespace, String extLabel, Address extAddr, SourceType source, int opIndex, RefType type) throws InvalidInputException, DuplicateNameException
    Adds an external reference. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
    Parameters:
      `fromAddr` - from memory address (source of the reference)
      `extNamespace` - external namespace containing the named external label.
      `extLabel` - label within the external program, may be null if extAddr is not null
      `extAddr` - address within the external program, may be null
      `source` - the source of this reference
      `opIndex` - operand index
      `type` - reference type - how the location is being referenced
    Returns:
      new external space reference
    Throws:
      `InvalidInputException` - if an invalid `extlabel` is specified. Names with spaces or the empty string are not permitted. Neither `extLabel` nor `extAddr` was specified properly.
      `DuplicateNameException` - if another non-Library namespace has the same name
      `IllegalArgumentException` - if an invalid `extAddr` was specified.

  - ### addExternalReference

    Reference addExternalReference(Address fromAddr, int opIndex, ExternalLocation location, SourceType source, RefType type) throws InvalidInputException
    Adds an external reference. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
    Parameters:
      `fromAddr` - from memory address (source of the reference)
      `opIndex` - operand index
      `location` - external location
      `source` - the source of this reference
      `type` - reference type - how the location is being referenced
    Returns:
      external reference
    Throws:
      `InvalidInputException`

  - ### removeAllReferencesFrom

    void removeAllReferencesFrom(Address beginAddr, Address endAddr)
    Removes all references where "From address" is in the given range.
    Parameters:
      `beginAddr` - the first address in the range.
      `endAddr` - the last address in the range.

  - ### removeAllReferencesFrom

    void removeAllReferencesFrom(Address fromAddr)
    Remove all stack, external, and memory references for the given from address.
    Parameters:
      `fromAddr` - the address of the codeunit from which to remove all references.

  - ### removeAllReferencesTo

    void removeAllReferencesTo(Address toAddr)
    Remove all stack, external, and memory references for the given to address.
    Parameters:
      `toAddr` - the address for which all references to should be removed.

  - ### getReferencesTo

    Reference[] getReferencesTo(Variable var)
    Returns all references to the given variable. Only data references to storage are considered.
    Parameters:
      `var` - variable to retrieve references to
    Returns:
      array of variable references, or zero length array if no references exist

  - ### getReferencedVariable

    Variable getReferencedVariable(Reference reference)
    Returns the referenced function variable.
    Parameters:
      `reference` - variable reference
    Returns:
      function variable or null if variable not found

  - ### setPrimary

    void setPrimary(Reference ref, boolean isPrimary)
    Set the given reference's primary attribute
    Parameters:
      `ref` - the reference to make primary.
      `isPrimary` - true to make the reference primary, false to make it non-primary

  - ### hasFlowReferencesFrom

    boolean hasFlowReferencesFrom(Address addr)
    Return whether the given address has flow references from it.
    Parameters:
      `addr` - the address to test for flow references.
    Returns:
      true if the given address has flow references from it, else false

  - ### getFlowReferencesFrom

    Reference[] getFlowReferencesFrom(Address addr)
    Get all flow references from the given address.
    Parameters:
      `addr` - the address of the codeunit to get all flows from.
    Returns:
      get all flow references from the given address.

  - ### getExternalReferences

    ReferenceIterator getExternalReferences()
    Returns an iterator over all external space references
    Returns:
      reference iterator over all external space references

  - ### getReferencesTo

    ReferenceIterator getReferencesTo(Address addr)
    Get an iterator over all references that have the given address as their "To" address.
    Parameters:
      `addr` - the address that all references in the iterator refer to.
    Returns:
      reference iterator over all references to the specified address.

  - ### getReferenceIterator

    ReferenceIterator getReferenceIterator(Address startAddr)
    Get an iterator over references starting with the specified fromAddr. A forward iterator is returned with references sorted on the from address.
    Parameters:
      `startAddr` - the first from address to consider.
    Returns:
      a forward memory reference iterator.

  - ### getReference

    Reference getReference(Address fromAddr, Address toAddr, int opIndex)
    Get the reference that has the given from and to address, and operand index.
    Parameters:
      `fromAddr` - the address of the codeunit making the reference.
      `toAddr` - the address being referred to.
      `opIndex` - the operand index.
    Returns:
      reference which satisfies the specified criteria or null

  - ### getReferencesFrom

    Reference[] getReferencesFrom(Address addr)
    Get all references "from" the specified addr.
    Parameters:
      `addr` - address of code-unit making the references.
    Returns:
      array of all references "from" the specified addr.

  - ### getReferencesFrom

    Reference[] getReferencesFrom(Address fromAddr, int opIndex)
    Returns all references "from" the given fromAddr and operand (specified by opIndex).
    Parameters:
      `fromAddr` - the from which to get references
      `opIndex` - the operand from which to get references
    Returns:
      all references "from" the given fromAddr and operand.

  - ### hasReferencesFrom

    boolean hasReferencesFrom(Address fromAddr, int opIndex)
    Returns true if there are any memory references at the given address/opIndex. Keep in mind this is a rather inefficient method as it must examine all references from the specified fromAddr.
    Parameters:
      `fromAddr` - the address of the codeunit being tested
      `opIndex` - the index of the operand being tested.
    Returns:
      true if one or more reference from the specified address and opindex are defined, else false

  - ### hasReferencesFrom

    boolean hasReferencesFrom(Address fromAddr)
    Returns true if there are any memory references at the given address.
    Parameters:
      `fromAddr` - the address of the codeunit being tested
    Returns:
      true if one or more reference from the specified address are defined, else false

  - ### getPrimaryReferenceFrom

    Reference getPrimaryReferenceFrom(Address addr, int opIndex)
    Get the primary reference from the given address.
    Parameters:
      `addr` - from address
      `opIndex` - operand index
    Returns:
      the primary reference from the specified address and opindex if it exists, else null

  - ### getReferenceSourceIterator

    AddressIterator getReferenceSourceIterator(Address startAddr, boolean forward)
    Returns an iterator over addresses that are the "From" address in a reference
    Parameters:
      `startAddr` - address to position iterator.
      `forward` - true means to iterate in the forward direction
    Returns:
      address iterator where references from exist

  - ### getReferenceSourceIterator

    AddressIterator getReferenceSourceIterator(AddressSetView addrSet, boolean forward)
    Returns an iterator over all addresses that are the "From" address in a reference, restricted by the given address set.
    Parameters:
      `addrSet` - the set of address to restrict the iterator or null for all addresses.
      `forward` - true means to iterate in the forward direction address iterator where references from exist
    Returns:
      address iterator where references from exist constrained by addrSet

  - ### getReferenceDestinationIterator

    AddressIterator getReferenceDestinationIterator(Address startAddr, boolean forward)
    Returns an iterator over all addresses that are the "To" address in a reference.
    Parameters:
      `startAddr` - start of iterator
      `forward` - true means to iterate in the forward direction address iterator where references to exist
    Returns:
      address iterator where references to exist

  - ### getReferenceDestinationIterator

    AddressIterator getReferenceDestinationIterator(AddressSetView addrSet, boolean forward)
    Returns an iterator over all addresses that are the "To" address in a memory reference, restricted by the given address set.
    Parameters:
      `addrSet` - the set of address to restrict the iterator or null for all addresses.
      `forward` - true means to iterate in the forward direction
    Returns:
      address iterator where references to exist constrained by addrSet

  - ### getReferenceCountTo

    int getReferenceCountTo(Address toAddr)
    Returns the number of references to the specified `toAddr`.
    Parameters:
      `toAddr` - the address being referenced
    Returns:
      the number of references to the specified `toAddr`.

  - ### getReferenceCountFrom

    int getReferenceCountFrom(Address fromAddr)
    Returns the number of references from the specified `fromAddr`.
    Parameters:
      `fromAddr` - the address of the codeunit making the reference.
    Returns:
      the number of references from the specified `fromAddr`.

  - ### getReferenceDestinationCount

    int getReferenceDestinationCount()
    Return the number of references for "to" addresses.

  - ### getReferenceSourceCount

    int getReferenceSourceCount()
    Return the number of references for "from" addresses.

  - ### hasReferencesTo

    boolean hasReferencesTo(Address toAddr)
    Return true if a memory reference exists with the given "to" address.
    Parameters:
      `toAddr` - address being referred to.
    Returns:
      true if specified toAddr has one or more references to it, else false.

  - ### updateRefType

    Reference updateRefType(Reference ref, RefType refType)
    Uodate the reference type on a memory reference.
    Parameters:
      `ref` - reference to be updated
      `refType` - new reference type
    Returns:
      updated reference

  - ### setAssociation

    void setAssociation(Symbol s, Reference ref)
    Associates the given reference with the given symbol. Applies to memory references only where a specified label symbol must have an address which matches the reference to-address. Stack and register reference associations to variable symbols are always inferred.
    Parameters:
      `s` - the symbol to associate with the given reference.
      `ref` - the reference to associate with the given symbol
    Throws:
      `IllegalArgumentException` - If the given reference does not already exist or its "To" address is not the same as the symbol's address.

  - ### removeAssociation

    void removeAssociation(Reference ref)
    Removes any symbol associations with the given reference.
    Parameters:
      `ref` - the reference for which any symbol association is to be removed.
    Throws:
      `IllegalArgumentException` - if the given references does not exist.

  - ### delete

    void delete(Reference ref)
    Deletes the given reference object
    Parameters:
      `ref` - the reference to be deleted.

  - ### getReferenceLevel

    byte getReferenceLevel(Address toAddr)
    Returns the reference level for the references to the given address
    Parameters:
      `toAddr` - the address at which to find the highest reference level
    Returns:
      reference level for specified to address.