Package ghidra.program.model.symbol

# Interface ExternalManager

All Known Implementing Classes:
  `ExternalManagerDB`

public interface ExternalManager
External manager interface. Defines methods for dealing with external programs and locations within those programs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Library`
  `addExternalLibraryName(String libraryName, SourceType source)`
  Adds a new external library name
  `ExternalLocation`
  `addExtFunction(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType)`
  Create an external `Function` in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`.
  `ExternalLocation`
  `addExtFunction(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting)`
  Get or create an external `Function` in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`.
  `ExternalLocation`
  `addExtFunction(String libraryName, String extLabel, Address extAddr, SourceType sourceType)`
  Create an external `Function` in the external `Library` namespace `libararyName` and identified by `extLabel` and/or its memory address `extAddr`.
  `ExternalLocation`
  `addExtLocation(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType)`
  Create an external location in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`.
  `ExternalLocation`
  `addExtLocation(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting)`
  Get or create an external location in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`.
  `ExternalLocation`
  `addExtLocation(String libraryName, String extLabel, Address extAddr, SourceType sourceType)`
  Get or create an external location associated with a library/file named `libraryName` and the location within that file identified by `extLabel` and/or its memory address `extAddr`.
  `boolean`
  `contains(String libraryName)`
  Determines if the indicated external library name is being managed (exists).
  `Library`
  `getExternalLibrary(String libraryName)`
  Get the Library which corresponds to the specified name
  `String[]`
  `getExternalLibraryNames()`
  Returns an array of all external names for which locations have been defined.
  `String`
  `getExternalLibraryPath(String libraryName)`
  Returns the file pathname associated with an external name.
  `ExternalLocation`
  `getExternalLocation(Symbol symbol)`
  Returns the external location associated with the given external symbol
  `ExternalLocationIterator`
  `getExternalLocations(Address memoryAddress)`
  Get an iterator over all external locations which have been associated to the specified memory address
  `Set<ExternalLocation>`
  `getExternalLocations(Namespace namespace, String label)`
  Returns a set of External Locations matching the given label name in the given Namespace.
  `ExternalLocationIterator`
  `getExternalLocations(String libraryName)`
  Get an iterator over all external locations associated with the specified Library.
  `Set<ExternalLocation>`
  `getExternalLocations(String libraryName, String label)`
  Returns a set of External Locations matching the given label name in the specified Library.
  `ExternalLocation`
  `getUniqueExternalLocation(Namespace namespace, String label)`
  Returns the unique external location associated with the given namespace and label.
  `ExternalLocation`
  `getUniqueExternalLocation(String libraryName, String label)`
  Returns the unique external location associated with the given library name and label.
  `boolean`
  `removeExternalLibrary(String libraryName)`
  Removes external name if no associated ExternalLocation's exist
  `void`
  `setExternalPath(String libraryName, String pathname, boolean userDefined)`
  Sets the file pathname associated with an existing external name.
  `void`
  `updateExternalLibraryName(String oldName, String newName, SourceType source)`
  Change the name of an existing external name.

- ## Method Details

  - ### getExternalLibraryNames

    String[] getExternalLibraryNames()
    Returns an array of all external names for which locations have been defined.
    Returns:
      array of external names

  - ### getExternalLibrary

    Library getExternalLibrary(String libraryName)
    Get the Library which corresponds to the specified name
    Parameters:
      `libraryName` - name of library
    Returns:
      library or null if not found

  - ### removeExternalLibrary

    boolean removeExternalLibrary(String libraryName)
    Removes external name if no associated ExternalLocation's exist
    Parameters:
      `libraryName` - external library name
    Returns:
      true if removed, false if unable to due to associated locations/references

  - ### getExternalLibraryPath

    String getExternalLibraryPath(String libraryName)
    Returns the file pathname associated with an external name. Null is returned if either the external name does not exist or a pathname has not been set.
    Parameters:
      `libraryName` - external name
    Returns:
      project file pathname or null

  - ### setExternalPath

    void setExternalPath(String libraryName, String pathname, boolean userDefined) throws InvalidInputException
    Sets the file pathname associated with an existing external name.
    Parameters:
      `libraryName` - the name of the library to associate with a file.
      `pathname` - the path to the program to be associated with the library name.
      `userDefined` - true if the external path is being specified by the user
    Throws:
      `InvalidInputException` - on invalid input

  - ### updateExternalLibraryName

    void updateExternalLibraryName(String oldName, String newName, SourceType source) throws DuplicateNameException, InvalidInputException
    Change the name of an existing external name.
    Parameters:
      `oldName` - the old name of the external library name.
      `newName` - the new name of the external library name.
      `source` - the source of this external library
    Throws:
      `DuplicateNameException` - if name conflicts with another symbol.
      `InvalidInputException` - if an invalid or null name specified (see `SymbolUtilities.validateName(java.lang.String)`).

  - ### getExternalLocations

    ExternalLocationIterator getExternalLocations(String libraryName)
    Get an iterator over all external locations associated with the specified Library.
    Parameters:
      `libraryName` - the name of the library to get locations for
    Returns:
      external location iterator

  - ### getExternalLocations

    ExternalLocationIterator getExternalLocations(Address memoryAddress)
    Get an iterator over all external locations which have been associated to the specified memory address
    Parameters:
      `memoryAddress` - memory address
    Returns:
      external location iterator

  - ### getExternalLocations

    Set<ExternalLocation> getExternalLocations(String libraryName, String label)
    Returns a set of External Locations matching the given label name in the specified Library. If searching for an original import name which should not be constrained to a specific library (e.g., mangled name), null may be specified for the libraryName.
    Parameters:
      `libraryName` - the name of the library
      `label` - the name of the label
    Returns:
      a list of External Locations matching the given label name in the given Library.

  - ### getExternalLocations

    Set<ExternalLocation> getExternalLocations(Namespace namespace, String label)
    Returns a set of External Locations matching the given label name in the given Namespace. If searching for an original import name which should not be constrained to a specific library (e.g., mangled name), null may be specified for the namespace. If a library sub-namespace is specified the original import name will not be searched.
    Parameters:
      `namespace` - the external Namespace to search or null
      `label` - the name of the labels to search for.
    Returns:
      a list of External Locations matching the given label name in the given Namespace.

  - ### getUniqueExternalLocation

    ExternalLocation getUniqueExternalLocation(String libraryName, String label)
    Returns the unique external location associated with the given library name and label. If searching for an original import name which should not be constrained to a specific library (e.g., mangled name), null may be specified for the libraryName.
    Parameters:
      `libraryName` - the library name or null
      `label` - the label of the external location
    Returns:
      the unique external location or null

  - ### getUniqueExternalLocation

    ExternalLocation getUniqueExternalLocation(Namespace namespace, String label)
    Returns the unique external location associated with the given namespace and label. If searching for an original import name which should not be constrained to a specific library (e.g., mangled name), null may be specified for the namespace. If a library sub-namespace is specified the original import name will not be searched.
    Parameters:
      `namespace` - the namespace or null
      `label` - the label of the external location
    Returns:
      the unique external location or null

  - ### getExternalLocation

    ExternalLocation getExternalLocation(Symbol symbol)
    Returns the external location associated with the given external symbol
    Parameters:
      `symbol` - the external symbol.
    Returns:
      the external location or null

  - ### contains

    boolean contains(String libraryName)
    Determines if the indicated external library name is being managed (exists).
    Parameters:
      `libraryName` - the external library name
    Returns:
      true if the name is defined (whether it has a path or not).

  - ### addExternalLibraryName

    Library addExternalLibraryName(String libraryName, SourceType source) throws InvalidInputException, DuplicateNameException
    Adds a new external library name
    Parameters:
      `libraryName` - the new external library name to add.
      `source` - the source of this external library
    Returns:
      library external `namespace`
    Throws:
      `InvalidInputException` - if `libraryName` is invalid or null. A library name 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

  - ### addExtLocation

    ExternalLocation addExtLocation(String libraryName, String extLabel, Address extAddr, SourceType sourceType) throws InvalidInputException, DuplicateNameException
    Get or create an external location associated with a 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:
      `libraryName` - the external library name
      `extLabel` - the external label or null
      `extAddr` - the external memory address or null
      `sourceType` - the source type of this external library's symbol
    Returns:
      external location
    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.

  - ### addExtLocation

    ExternalLocation addExtLocation(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType) throws InvalidInputException
    Create an external location in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `extNamespace` - the external namespace
      `extLabel` - the external label or null
      `extAddr` - the external memory address or null
      `sourceType` - the source type of this external library's symbol
    Returns:
      external location
    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.
      `IllegalArgumentException` - if an invalid `extAddr` was specified.

  - ### addExtLocation

    ExternalLocation addExtLocation(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting) throws InvalidInputException
    Get or create an external location in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `extNamespace` - the external namespace
      `extLabel` - the external label or null
      `extAddr` - the external memory address or null
      `sourceType` - the source type of this external library's symbol
      `reuseExisting` - if true, this will return an existing matching external location instead of creating a new one.
    Returns:
      external location
    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.
      `IllegalArgumentException` - if an invalid `extAddr` was specified.

  - ### addExtFunction

    ExternalLocation addExtFunction(String libraryName, String extLabel, Address extAddr, SourceType sourceType) throws InvalidInputException, DuplicateNameException
    Create an external `Function` in the external `Library` namespace `libararyName` and identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `libraryName` - the external library name
      `extLabel` - label within the external program, may be null if extAddr is not null
      `extAddr` - memory address within the external program, may be null
      `sourceType` - the source type of this external library's symbol
    Returns:
      external location
    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.

  - ### addExtFunction

    ExternalLocation addExtFunction(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType) throws InvalidInputException
    Create an external `Function` in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `extNamespace` - the external namespace
      `extLabel` - the external label or null
      `extAddr` - the external memory address or null
      `sourceType` - the source type of this external library's symbol
    Returns:
      external location
    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.
      `IllegalArgumentException` - if an invalid `extAddr` was specified.

  - ### addExtFunction

    ExternalLocation addExtFunction(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting) throws InvalidInputException
    Get or create an external `Function` in the indicated external parent namespace and identified by `extLabel` and/or its memory address `extAddr`. Either or both `extLabel` or `extAddr` must be specified.
    Parameters:
      `extNamespace` - the external namespace
      `extLabel` - the external label or null
      `extAddr` - the external memory address or null
      `sourceType` - the source type of this external library's symbol
      `reuseExisting` - if true, will return any existing matching location instead of creating a new one. If false, will prefer to create a new one as long as the specified address is not null and not used in an existing location.
    Returns:
      external location
    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.
      `IllegalArgumentException` - if an invalid `extAddr` was specified.