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 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.