Package ghidra.debug.api.watch

# Interface WatchRow

public interface WatchRow
A row in the Watches table

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Address`
  `getAddress()`
  Get the address of the value, if it exists at one (memory or register)
  `String`
  `getComment()`
  Get the user-defined comment for this row
  `DataType`
  `getDataType()`
  Get the data type for interpreting the value
  `Throwable`
  `getError()`
  If the watch could not be evaluated, get the cause
  `String`
  `getErrorMessage()`
  If the watch could not be evaluated, get a message explaining why
  `String`
  `getExpression()`
  Get the Sleigh expression
  `AddressRange`
  `getRange()`
  Get the address range of the value, if it exists at an address (memory or register)
  `String`
  `getRawValueString()`
  Get the raw value displayed as a string
  `AddressSetView`
  `getReads()`
  Get the complete set of all addresses read to evaluate the expression
  `Settings`
  `getSettings()`
  Get the settings on the data type
  `Symbol`
  `getSymbol()`
  Get the nearest symbol before the value's address, if applicable
  `byte[]`
  `getValue()`
  Get the raw value
  `int`
  `getValueLength()`
  Get the number of bytes in the value
  `Object`
  `getValueObject()`
  Get the value as returned by the data type
  `String`
  `getValueString()`
  Get the value as represented by the data type
  `boolean`
  `isChanged()`
  Check if the value has changed
  `boolean`
  `isKnown()`
  Check if the value given is actually known to be the value
  `boolean`
  `isRawValueEditable()`
  Check if `setRawValueString(String)` is supported
  `boolean`
  `isValueEditable()`
  Check if `setValueString(String)` is supported
  `void`
  `setComment(String comment)`
  Set the user-defined comment for this row
  `void`
  `setDataType(DataType dataType)`
  Set the data type for interpreting the value
  `void`
  `setExpression(String expression)`
  Set the Sleigh expression
  `void`
  `setRawValueString(String value)`
  Patch memory or register values such that the expression evaluates to the given raw value
  `void`
  `settingsChanged()`
  Notify the row that the settings were changed
  `void`
  `setValueString(String value)`
  Patch memory or register values such that the expression evaluates to the given value

- ## Method Details

  - ### getExpression

    String getExpression()
    Get the Sleigh expression
    Returns:
      the expression

  - ### setExpression

    void setExpression(String expression)
    Set the Sleigh expression
    Parameters:
      `expression` - the expression

  - ### getDataType

    DataType getDataType()
    Get the data type for interpreting the value
    Returns:
      the data type

  - ### setDataType

    void setDataType(DataType dataType)
    Set the data type for interpreting the value
    Parameters:
      `dataType` - the data type

  - ### getSettings

    Settings getSettings()
    Get the settings on the data type

    The returned settings may be modified, after which `settingsChanged()` must be called. There is no `setSettings` method.

    Returns:
      the settings

  - ### settingsChanged

    void settingsChanged()
    Notify the row that the settings were changed
    See Also:
      - `getSettings()`

  - ### getAddress

    Address getAddress()
    Get the address of the value, if it exists at one (memory or register)
    Returns:
      the address, or null

  - ### getRange

    AddressRange getRange()
    Get the address range of the value, if it exists at an address (memory or register)
    Returns:
      the range, or null

  - ### getReads

    AddressSetView getReads()
    Get the complete set of all addresses read to evaluate the expression
    Returns:
      the address set, or null

  - ### getSymbol

    Symbol getSymbol()
    Get the nearest symbol before the value's address, if applicable
    Returns:
      the symbol, or null

  - ### getValue

    byte[] getValue()
    Get the raw value
    Returns:
      the value, or null

  - ### getRawValueString

    String getRawValueString()
    Get the raw value displayed as a string

    For values in memory, this is a list of hex bytes. For others, it is a hex integer subject to the platform's endian.

    Returns:
      the value, or null

  - ### getValueLength

    int getValueLength()
    Get the number of bytes in the value
    Returns:
      the length, or 0 if evaluation failed

  - ### setRawValueString

    void setRawValueString(String value)
    Patch memory or register values such that the expression evaluates to the given raw value

    This is only supported when `isRawValueEditable()` returns true. The given value must be a list of hex bytes (as returned by `getRawValueString()`), or a hex integer subject to the platform's endian. Either is accepted, regardless of whether the value resides in memory.

    Parameters:
      `value` - the raw value as returned by `getRawValueString()`
    See Also:
      - `getAddress()`

  - ### isRawValueEditable

    boolean isRawValueEditable()
    Check if `setRawValueString(String)` is supported

    Setting the value may not be supported for many reasons: 1) The expression is not valid, 2) The expression could not be evaluated, 3) The value has no address or register. Reason 3 is somewhat strict, but reasonable, lest we have to implement a solver.

    Returns:
      whether or not the value can be modified

  - ### getValueObject

    Object getValueObject()
    Get the value as returned by the data type
    Returns:
      the data-type defined value

  - ### getValueString

    String getValueString()
    Get the value as represented by the data type
    Returns:
      the value's data-type-defined representation

  - ### setValueString

    void setValueString(String value)
    Patch memory or register values such that the expression evaluates to the given value

    This is only supported when `isValueEditable()` returns true. The given value must be encodable by the data type.

    Parameters:
      `value` - the desired value, as returned by `getValueString()`

  - ### isValueEditable

    boolean isValueEditable()
    Check if `setValueString(String)` is supported

    In addition to those reasons given in `isRawValueEditable()`, setting the value may not be supported because: 1) No data type is set, or 2) The selected data type does not support encoding.

    Returns:
      whether or not the data-type interpreted value can be modified

  - ### getError

    Throwable getError()
    If the watch could not be evaluated, get the cause
    Returns:
      the error

  - ### getErrorMessage

    String getErrorMessage()
    If the watch could not be evaluated, get a message explaining why

    This is essentially the message given by `getError()`. If the exception does not provide a message, this will at least give the name of the exception class.

    Returns:
      the error message, or an empty string

  - ### isKnown

    boolean isKnown()
    Check if the value given is actually known to be the value

    If the value itself or any value encountered during the evaluation of the expression is stale, then the final value is considered stale, i.e., not known.

    Returns:
      true all memory and registers involved in the evaluation are known, false otherwise.

  - ### isChanged

    boolean isChanged()
    Check if the value has changed

    "Changed" technically deals in navigation. In the case of a step, resume-and-break, patch, etc. This will detect the changes as expected. When manually navigating, this compares the two most recent times visited. Only the value itself is compared, without consideration for any intermediate values encountered during evaluation. Consider an array whose elements are all currently 0. An expression that dereferences an index in that array will be considered unchanged, even if the index did change.

    Returns:
      true if the value changed, false otherwise.

  - ### getComment

    String getComment()
    Get the user-defined comment for this row
    Returns:
      the comment

  - ### setComment

    void setComment(String comment)
    Set the user-defined comment for this row
    Parameters:
      `comment` - the comment