Package ghidra.program.model.symbol

# Interface ExternalLocation

All Known Implementing Classes:
  `ExternalLocationDB`

public interface ExternalLocation
`ExternalLocation` defines a location within an external program (i.e., library). The external program is uniquely identified by a program name, and the location within the program is identified by label, address or both.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Function`
  `createFunction()`
  Create an external function associated with this location or return the existing function if one already exists
  `Address`
  `getAddress()`
  Returns the external address if known, or null
  `DataType`
  `getDataType()`
  Returns the DataType which has been associated with this location.
  `Address`
  `getExternalSpaceAddress()`
  Returns the address in "External" (fake) space where this location is stored.
  `Function`
  `getFunction()`
  Returns the external function associated with this location or null if this is a data location.
  `String`
  `getLabel()`
  Returns the external label associated with this location.
  `String`
  `getLibraryName()`
  Returns the name of the external program containing this location.
  `String`
  `getOriginalImportedName()`
  Returns the original name for this location.
  `String`
  `getParentName()`
  Returns the name of the parent namespace containing this location.
  `Namespace`
  `getParentNameSpace()`
  Returns the parent namespace containing this location.
  `SourceType`
  `getSource()`
  Returns the source of this location.
  `Symbol`
  `getSymbol()`
  Returns the symbol associated with this external location or null.
  `boolean`
  `isEquivalent(ExternalLocation other)`
  Returns true if the given external location has the same name, namespace, original import name, and external address.
  `boolean`
  `isFunction()`
  `void`
  `restoreOriginalName()`
  If this external location has a replacement name, then the primary symbol will be deleted and the original symbol will become the primary symbol, effectively restoring the location to it's original name.
  `void`
  `setAddress(Address address)`
  Sets the address in the external program associated with this location.
  `void`
  `setDataType(DataType dt)`
  Associate the specified data type with this location.
  `void`
  `setLocation(String label, Address addr, SourceType source)`
  Set the external label which defines this location.
  `void`
  `setName(Namespace namespace, String name, SourceType sourceType)`
  Set a new name for this external location.

- ## Method Details

  - ### getSymbol

    Symbol getSymbol()
    Returns the symbol associated with this external location or null.
    Returns:
      the symbol associated with this external location or null.

  - ### getLibraryName

    String getLibraryName()
    Returns the name of the external program containing this location.
    Returns:
      the name of the external program containing this location.

  - ### getParentNameSpace

    Namespace getParentNameSpace()
    Returns the parent namespace containing this location.
    Returns:
      the parent namespace containing this location.

  - ### getParentName

    String getParentName()
    Returns the name of the parent namespace containing this location.
    Returns:
      the name of the parent namespace containing this location.

  - ### getLabel

    String getLabel()
    Returns the external label associated with this location.
    Returns:
      the external label associated with this location.

  - ### getOriginalImportedName

    String getOriginalImportedName()
    Returns the original name for this location. Will be null if the name was never changed.
    Returns:
      the original name for this location. Will be null if the name was never changed.

  - ### getSource

    SourceType getSource()
    Returns the source of this location.
    Returns:
      the source

  - ### getAddress

    Address getAddress()
    Returns the external address if known, or null
    Returns:
      the external address if known, or null

  - ### setAddress

    void setAddress(Address address) throws InvalidInputException
    Sets the address in the external program associated with this location. The address may not be null if location has a default label.
    Parameters:
      `address` - the address to set.
    Throws:
      `InvalidInputException` - if address is null and location currently has a default name

  - ### setLocation

    void setLocation(String label, Address addr, SourceType source) throws DuplicateNameException, InvalidInputException
    Set the external label which defines this location.
    Parameters:
      `label` - external label, may be null if addr is not null. Label may also be namespace qualified and best effort will be used to parse namespace (see `SymbolPath`). If a namespace is not included within label, the current namespace will be preserved. Note that this method does not properly handle the presence of template information within the label.
      `addr` - external address, may be null
      `source` - the source of the external label name
    Throws:
      `DuplicateNameException` - if another location with this label has already been defined
      `InvalidInputException`

  - ### isFunction

    boolean isFunction()
    Returns:
      true if location corresponds to a function

  - ### getDataType

    DataType getDataType()
    Returns the DataType which has been associated with this location.

  - ### setDataType

    void setDataType(DataType dt)
    Associate the specified data type with this location.
    Parameters:
      `dt` - data type

  - ### getFunction

    Function getFunction()
    Returns the external function associated with this location or null if this is a data location.
    Returns:
      external function associated with this location or null if this is a data location.

  - ### createFunction

    Function createFunction()
    Create an external function associated with this location or return the existing function if one already exists
    Returns:
      external function

  - ### getExternalSpaceAddress

    Address getExternalSpaceAddress()
    Returns the address in "External" (fake) space where this location is stored.
    Returns:
      the address that represents this location in "External" space.

  - ### setName

    void setName(Namespace namespace, String name, SourceType sourceType) throws InvalidInputException
    Set a new name for this external location. The new name will become the primary symbol for this location. The current name for this location will be saved as the original symbol for this location.
    Parameters:
      `namespace` - the namespace for the original symbol. Can be different than original symbol
      `name` - the user-friendly name.
      `sourceType` - the SourceType for the new name.
    Throws:
      `InvalidInputException` - if the name contains illegal characters (space for example)

  - ### restoreOriginalName

    void restoreOriginalName()
    If this external location has a replacement name, then the primary symbol will be deleted and the original symbol will become the primary symbol, effectively restoring the location to it's original name.

  - ### isEquivalent

    boolean isEquivalent(ExternalLocation other)
    Returns true if the given external location has the same name, namespace, original import name, and external address.
    Parameters:
      `other` - the other ExternalLocation to compare
    Returns:
      true if the other location is equivalent to this one.