Package ghidra.program.database.symbol

# Class EquateManager

java.lang.Object
ghidra.program.database.symbol.EquateManager

All Implemented Interfaces:
  `ErrorHandler`, `ManagerDB`, `EquateTable`

public class EquateManager extends Object implements EquateTable, ErrorHandler, ManagerDB
Implementation of the Equate Table

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DATATYPE_TAG`
  `static final String`
  `ERROR_TAG`
  `static final String`
  `FORMAT_DELIMITER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EquateManager(DBHandle handle, AddressMap addrMap, int openMode, Lock lock, TaskMonitor monitor)`
  Constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Equate`
  `createEquate(String name, long value)`
  Creates a new equate
  `void`
  `dbError(IOException e)`
  Notification that an IO exception occurred.
  `void`
  `deleteAddressRange(Address startAddr, Address endAddr, TaskMonitor monitor)`
  Removes all equates defined in the given range.
  `static String`
  `formatNameForEquate(UniversalID dtID, long equateValue)`
  Formats a string to the equate format given the enum UUID and the value for the equate.
  `static String`
  `formatNameForEquateError(long equateValue)`
  Formats a string to the equate error format given the value.
  `static UniversalID`
  `getDataTypeUUID(String formattedEquateName)`
  Pulls out the enum data type UUID given a formatted equate name.
  `Equate`
  `getEquate(Address reference, int opIndex, long scalarValue)`
  Returns the first equate found that is associated with the given value at the given reference address and operand position;
  `Equate`
  `getEquate(String name)`
  Returns the equate with the given name, null if no such equate exists
  `AddressIterator`
  `getEquateAddresses()`
  Returns an address iterator over all the addresses where equates have been set.
  `AddressIterator`
  `getEquateAddresses(Address startAddr)`
  Return an address iterator over each address with an equate reference starting at the start address.
  `AddressIterator`
  `getEquateAddresses(AddressSetView set)`
  Return an address iterator over each address with an equate reference that is in the specified address set.
  `Iterator<Equate>`
  `getEquates()`
  Returns an iterator over all equates.
  `List<Equate>`
  `getEquates(long value)`
  Returns all equates defined for value.
  `List<Equate>`
  `getEquates(Address reference)`
  Returns the equates (one for each scalar and opIndex) at the given reference address.
  `List<Equate>`
  `getEquates(Address reference, int opIndex)`
  Returns the equates (one for each scalar) at the given reference address and operand position; For an instruction a given operand can have multiple scalars.
  `static long`
  `getEquateValueFromFormattedName(String formattedEquateName)`
  Pulls out the value of the equate given the formatted equate name.
  `void`
  `invalidateCache(boolean all)`
  Clears all data caches.
  `void`
  `moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor)`
  Move all objects within an address range to a new location.
  `void`
  `programReady(int openMode, int currentRevision, TaskMonitor monitor)`
  Callback from program made to each manager after the program has completed initialization.
  `boolean`
  `removeEquate(String name)`
  Removes the equate from the program.
  `void`
  `setProgram(ProgramDB program)`
  Callback from program used to indicate all manager have been created.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.program.database.ManagerDB

  `dispose`

- ## Field Details

  - ### DATATYPE_TAG

    public static final String DATATYPE_TAG
    See Also:
      - Constant Field Values

  - ### ERROR_TAG

    public static final String ERROR_TAG
    See Also:
      - Constant Field Values

  - ### FORMAT_DELIMITER

    public static final String FORMAT_DELIMITER
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### EquateManager

    public EquateManager(DBHandle handle, AddressMap addrMap, int openMode, Lock lock, TaskMonitor monitor) throws VersionException, IOException
    Constructor
    Parameters:
      `handle` - database handle
      `addrMap` - map that converts addresses to longs and longs to addresses
      `openMode` - one of ProgramDB.CREATE, UPDATE, UPGRADE, or READ_ONLY
      `lock` - the program synchronization lock
      `monitor` - the progress monitor used when upgrading.
    Throws:
      `VersionException` - if the database version doesn't match the current version.
      `IOException` - if a database error occurs.

- ## Method Details

  - ### setProgram

    public void setProgram(ProgramDB program)
    Description copied from interface: `ManagerDB`
    Callback from program used to indicate all manager have been created. When this method is invoked, all managers have been instantiated but may not be fully initialized.
    Specified by:
      `setProgram` in interface `ManagerDB`
    Parameters:
      `program` - the program is set when all the initializations have been completed.

  - ### programReady

    public void programReady(int openMode, int currentRevision, TaskMonitor monitor) throws IOException, CancelledException
    Description copied from interface: `ManagerDB`
    Callback from program made to each manager after the program has completed initialization. This method may be used by managers to perform additional upgrading which may have been deferred.
    Specified by:
      `programReady` in interface `ManagerDB`
    Parameters:
      `openMode` - the mode that the program is being opened.
      `currentRevision` - current program revision. If openMode is UPGRADE, this value reflects the pre-upgrade value.
      `monitor` - the task monitor to use in any upgrade operations.
    Throws:
      `IOException` - if a database io error occurs.
      `CancelledException` - if the user cancelled the operation via the task monitor.

  - ### dbError

    public void dbError(IOException e)
    Description copied from interface: `ErrorHandler`
    Notification that an IO exception occurred.
    Specified by:
      `dbError` in interface `ErrorHandler`
    Parameters:
      `e` - `IOException` which was cause of error

  - ### createEquate

    public Equate createEquate(String name, long value) throws DuplicateNameException, InvalidInputException
    Description copied from interface: `EquateTable`
    Creates a new equate
    Specified by:
      `createEquate` in interface `EquateTable`
    Parameters:
      `name` - the name to associate with the given value.
      `value` - the value to associate with the given name.
    Returns:
      the equate
    Throws:
      `DuplicateNameException` - thrown if name is already in use as an equate.
      `InvalidInputException` - if name contains blank characters, is zero length, or is null

  - ### getEquate

    public Equate getEquate(Address reference, int opIndex, long scalarValue)
    Description copied from interface: `EquateTable`
    Returns the first equate found that is associated with the given value at the given reference address and operand position;
    Specified by:
      `getEquate` in interface `EquateTable`
    Parameters:
      `reference` - address where the equate is used.
      `opIndex` - the operand index of the operand where the equate is used.
      `scalarValue` - the value where the equate is used.
    Returns:
      the equate or null if there is no such equate.

  - ### getEquates

    public List<Equate> getEquates(Address reference, int opIndex)
    Description copied from interface: `EquateTable`
    Returns the equates (one for each scalar) at the given reference address and operand position; For an instruction a given operand can have multiple scalars.
    Specified by:
      `getEquates` in interface `EquateTable`
    Parameters:
      `reference` - address where the equate is used.
      `opIndex` - the operand index of the operand where the equate is used.
    Returns:
      the list of equates or empty list if there is no such equate.

  - ### getEquates

    public List<Equate> getEquates(Address reference)
    Description copied from interface: `EquateTable`
    Returns the equates (one for each scalar and opIndex) at the given reference address. For an instruction a given operand can have multiple scalars.
    Specified by:
      `getEquates` in interface `EquateTable`
    Parameters:
      `reference` - address where the equate is used.
    Returns:
      the list of equates or empty list if there is no such equate.

  - ### getEquate

    public Equate getEquate(String name)
    Description copied from interface: `EquateTable`
    Returns the equate with the given name, null if no such equate exists
    Specified by:
      `getEquate` in interface `EquateTable`
    Parameters:
      `name` - the of the equate to be retrieved
    Returns:
      the equate

  - ### getEquateAddresses

    public AddressIterator getEquateAddresses()
    Description copied from interface: `EquateTable`
    Returns an address iterator over all the addresses where equates have been set.
    Specified by:
      `getEquateAddresses` in interface `EquateTable`
    Returns:
      the iterator

  - ### getEquateAddresses

    public AddressIterator getEquateAddresses(Address startAddr)
    Description copied from interface: `EquateTable`
    Return an address iterator over each address with an equate reference starting at the start address.
    Specified by:
      `getEquateAddresses` in interface `EquateTable`
    Parameters:
      `startAddr` - start address
    Returns:
      an AddressIterator over addresses with defined equate references

  - ### getEquateAddresses

    public AddressIterator getEquateAddresses(AddressSetView set)
    Description copied from interface: `EquateTable`
    Return an address iterator over each address with an equate reference that is in the specified address set.
    Specified by:
      `getEquateAddresses` in interface `EquateTable`
    Parameters:
      `set` - the address set
    Returns:
      AddressIterator over addresses with defined equate references

  - ### getEquates

    public Iterator<Equate> getEquates()
    Description copied from interface: `EquateTable`
    Returns an iterator over all equates.
    Specified by:
      `getEquates` in interface `EquateTable`
    Returns:
      the iterator

  - ### getEquates

    public List<Equate> getEquates(long value)
    Description copied from interface: `EquateTable`
    Returns all equates defined for value.
    Specified by:
      `getEquates` in interface `EquateTable`
    Parameters:
      `value` - the value to get all equates for.
    Returns:
      the equates

  - ### deleteAddressRange

    public void deleteAddressRange(Address startAddr, Address endAddr, TaskMonitor monitor) throws CancelledException
    Description copied from interface: `EquateTable`
    Removes all equates defined in the given range.
    Specified by:
      `deleteAddressRange` in interface `EquateTable`
    Specified by:
      `deleteAddressRange` in interface `ManagerDB`
    Parameters:
      `startAddr` - start of the range
      `endAddr` - end of the range
      `monitor` - task monitor to cancel the remove operation
    Throws:
      `CancelledException` - if the operation was cancelled.

  - ### removeEquate

    public boolean removeEquate(String name)
    Description copied from interface: `EquateTable`
    Removes the equate from the program.
    Specified by:
      `removeEquate` in interface `EquateTable`
    Parameters:
      `name` - the name of the equate to remove.
    Returns:
      true if the equate existed, false otherwise.

  - ### invalidateCache

    public void invalidateCache(boolean all)
    Description copied from interface: `ManagerDB`
    Clears all data caches.
    Specified by:
      `invalidateCache` in interface `ManagerDB`
    Parameters:
      `all` - if false, some managers may not need to update their cache if they can tell that its not necessary. If this flag is true, then all managers should clear their cache no matter what.

  - ### moveAddressRange

    public void moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor) throws CancelledException
    Description copied from interface: `ManagerDB`
    Move all objects within an address range to a new location.
    Specified by:
      `moveAddressRange` in interface `ManagerDB`
    Parameters:
      `fromAddr` - the first address of the range to be moved.
      `toAddr` - the address where to the range is to be moved.
      `length` - the number of addresses to move.
      `monitor` - the task monitor to use in any upgrade operations.
    Throws:
      `CancelledException` - if the user cancelled the operation via the task monitor.

  - ### formatNameForEquate

    public static String formatNameForEquate(UniversalID dtID, long equateValue)
    Formats a string to the equate format given the enum UUID and the value for the equate. The formatted strings are used when setting equates from datatypes so that information can be stored with an equate to point back to that datatype.
    Parameters:
      `dtID` - The enum's data type UUID
      `equateValue` - The value intended for the equate
    Returns:
      The formatted equate name

  - ### formatNameForEquateError

    public static String formatNameForEquateError(long equateValue)
    Formats a string to the equate error format given the value. Used for rendering formatted equates that do not point back to a datatype.
    Parameters:
      `equateValue` - The value of the equate
    Returns:
      The error formatted equate name

  - ### getDataTypeUUID

    public static UniversalID getDataTypeUUID(String formattedEquateName)
    Pulls out the enum data type UUID given a formatted equate name. This UUID should point back to a datatype.
    Parameters:
      `formattedEquateName` - The formatted equate name to pull the UUID from
    Returns:
      The enum data type UUID or null if the given name is not formatted.

  - ### getEquateValueFromFormattedName

    public static long getEquateValueFromFormattedName(String formattedEquateName)
    Pulls out the value of the equate given the formatted equate name. The value stored in the equate info is a decimal.
    Parameters:
      `formattedEquateName` - The formatted equate name to pull the value from
    Returns:
      The value of the equate, or -1 if the given name is not formatted.