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(Namespace namespace, String label)`
  Deprecated.
  Use `getExternalLocations(Namespace, String)` or `getUniqueExternalLocation(Namespace, String)` since duplicate names may exist
  `ExternalLocation`
  `getExternalLocation(Symbol symbol)`
  Returns the external location associated with the given external symbol
  `ExternalLocation`
  `getExternalLocation(String libraryName, String label)`
  Deprecated.
  Use `getExternalLocations(String, String)` or `getUniqueExternalLocation(String, String)` since duplicate names may exist
  `ExternalLocationIterator`
  `getExternalLocations(Address memoryAddress)`
  Get an iterator over all external locations which have been associated to the specified memory address
  `List<ExternalLocation>`
  `getExternalLocations(Namespace namespace, String label)`
  Returns a list 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 externalName.
  `List<ExternalLocation>`
  `getExternalLocations(String libraryName, String label)`
  Returns a list of External Locations matching the given label name in the given 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`

  - ### 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 another namespace has the same name
      `InvalidInputException`

  - ### getExternalLocations

    ExternalLocationIterator getExternalLocations(String libraryName)
    Get an iterator over all external locations associated with the specified externalName.
    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

  - ### getExternalLocation

    @Deprecated ExternalLocation getExternalLocation(String libraryName, String label)
    Deprecated.
    Use `getExternalLocations(String, String)` or `getUniqueExternalLocation(String, String)` since duplicate names may exist
    Get an external location.
    Parameters:
      `libraryName` - the name of the library for which to get an external location
      `label` - the name of the external location.
    Returns:
      first matching external location

  - ### getExternalLocation

    @Deprecated ExternalLocation getExternalLocation(Namespace namespace, String label)
    Deprecated.
    Use `getExternalLocations(Namespace, String)` or `getUniqueExternalLocation(Namespace, String)` since duplicate names may exist
    Get an external location.
    Parameters:
      `namespace` - the namespace containing the external label.
      `label` - the name of the external location.
    Returns:
      first matching external location

  - ### getExternalLocations

    List<ExternalLocation> getExternalLocations(String libraryName, String label)
    Returns a list of External Locations matching the given label name in the given Library.
    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

    List<ExternalLocation> getExternalLocations(Namespace namespace, String label)
    Returns a list of External Locations matching the given label name in the given Namespace.
    Parameters:
      `namespace` - the Namespace to search
      `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
    Parameters:
      `libraryName` - the library name
      `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
    Parameters:
      `namespace` - the namespace
      `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.