Package ghidra.app.util.opinion

Class AbstractLibrarySupportLoader

java.lang.Object
ghidra.app.util.opinion.AbstractProgramLoader
ghidra.app.util.opinion.AbstractLibrarySupportLoader
All Implemented Interfaces:
Loader, ExtensionPoint, Comparable<Loader>
Direct Known Subclasses:
AbstractOrdinalSupportLoader, CoffLoader, ElfLoader, MachoLoader, MzLoader
public abstract class AbstractLibrarySupportLoader extends AbstractProgramLoader
An abstract Loader that provides a framework to conveniently load Programs with support for linking against libraries contained in other Programs.

Subclasses may override various protected methods to customize how libraries are loaded.

  • Field Details

  • Constructor Details

    • AbstractLibrarySupportLoader

      public AbstractLibrarySupportLoader()

  • Method Details

    • load

      protected abstract void load(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program, TaskMonitor monitor, MessageLog log) throws CancelledException, IOException
      Loads bytes in a particular format into the given Program.
      Parameters:
      provider - The bytes to load.
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      program - The Program to load into.
      monitor - A cancelable task monitor.
      log - The message log.
      Throws:
      IOException - if there was an IO-related problem loading.
      CancelledException - if the user cancelled the load.

    • loadProgram

      protected List<Loaded<Program>> loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) throws CancelledException, IOException
      Description copied from class: AbstractProgramLoader
      Loads bytes in a particular format as a new Loaded Program. Multiple Programs may end up getting created, depending on the nature of the format.

      Note that when the load completes, the returned Loaded Programs are not saved to a project. That is the responsibility of the caller (see Loaded.save(Project, MessageLog, TaskMonitor)).

      It is also the responsibility of the caller to release the returned Loaded Programs with Loaded.release(Object) when they are no longer needed.

      Specified by:
      loadProgram in class AbstractProgramLoader
      Parameters:
      provider - The bytes to load.
      loadedName - A suggested name for the primary Loaded Program. This is just a suggestion, and a Loader implementation reserves the right to change it. The Loaded Programs should be queried for their true names using Loaded.getName().
      project - The Project. Loaders can use this to take advantage of existing DomainFolders and DomainFiles to do custom behaviors such as loading libraries. Could be null if there is no project.
      projectFolderPath - A suggested project folder path for the Loaded Programs. This is just a suggestion, and a Loader implementation reserves the right to change it for each Loaded result. The Loaded Programs should be queried for their true project folder paths using Loaded.getProjectFolderPath().
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      log - The message log.
      consumer - A consumer object for generated Programs.
      monitor - A task monitor.
      Returns:
      A List of one or more Loaded Programs (created but not saved).
      Throws:
      CancelledException - if the user cancelled the load.
      IOException - if there was an IO-related problem loading.

    • loadProgramInto

      protected void loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor) throws CancelledException, LoadException, IOException
      Description copied from class: AbstractProgramLoader
      Loads program bytes into the specified Program. This method will not create any new Programs. It is only for adding to an existing Program.

      NOTE: The loading that occurs in this method will automatically be done in a transaction.

      Specified by:
      loadProgramInto in class AbstractProgramLoader
      Parameters:
      provider - The bytes to load into the Program.
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      log - The message log.
      program - The Program to load into.
      monitor - A cancelable task monitor.
      Throws:
      CancelledException - if the user cancelled the load.
      LoadException - if the load failed in an expected way.
      IOException - if there was an IO-related problem loading.

    • postLoadProgramFixups

      protected void postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor) throws CancelledException, IOException
      This gets called after the given list of loaded programss is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.

      Fix up program's external library entries so that they point to a path in the project.

      Overrides:
      postLoadProgramFixups in class AbstractProgramLoader
      Parameters:
      loadedPrograms - The loaded programs to be fixed up.
      project - The Project to load into. Could be null if there is no project.
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      log - The message log.
      monitor - A cancelable task monitor.
      Throws:
      CancelledException - if the user cancelled the load.
      IOException - if there was an IO-related problem loading.

    • getTier

      public LoaderTier getTier()
      Description copied from interface: Loader
      For ordering purposes; lower tier numbers are more important (and listed first).
      Returns:
      the tier of the loader

    • getTierPriority

      public int getTierPriority()
      Description copied from interface: Loader
      For ordering purposes; lower numbers are more important (and listed first, within its tier).
      Returns:
      the ordering of the loader within its tier

    • getDefaultOptions

      public List<Option> getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram)
      Description copied from interface: Loader
      Gets the default Loader options.
      Specified by:
      getDefaultOptions in interface Loader
      Overrides:
      getDefaultOptions in class AbstractProgramLoader
      Parameters:
      provider - The bytes of the thing being loaded.
      loadSpec - The LoadSpec.
      domainObject - The DomainObject being loaded.
      loadIntoProgram - True if the load is adding to an existing DomainObject; otherwise, false.
      Returns:
      A list of the Loader's default options.

    • validateOptions

      public String validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)
      Description copied from interface: Loader
      Validates the Loader's options and returns null if all options are valid; otherwise, an error message describing the problem is returned.
      Specified by:
      validateOptions in interface Loader
      Overrides:
      validateOptions in class AbstractProgramLoader
      Parameters:
      provider - The bytes of the thing being loaded.
      loadSpec - The proposed LoadSpec.
      options - The list of Options to validate.
      program - existing program if the loader is adding to an existing program. If it is a fresh import, then this will be null.
      Returns:
      null if all Options are valid; otherwise, an error message describing the problem is returned.

    • isLinkExistingLibraries

      protected boolean isLinkExistingLibraries(List<Option> options)
      Checks to see if existing libraries should be linked
      Parameters:
      options - a List of Options
      Returns:
      True if existing libraries should be linked; otherwise, false

    • getLinkSearchFolder

      protected DomainFolder getLinkSearchFolder(Project project, Program program, String projectFolderPath, List<Option> options, MessageLog log)
      Gets the project folder to search for existing libraries
      Parameters:
      project - The Project. Could be null if there is no project.
      program - The Program being loaded
      projectFolderPath - The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.
      options - a List of Options
      log - The log
      Returns:
      The path of the project folder to search for existing libraries, or null if no project folders can be or should be searched

    • isLoadLibraries

      protected boolean isLoadLibraries(List<Option> options)
      Checks to see if libraries from disk should be loaded
      Parameters:
      options - a List of Options
      Returns:
      True if libraries from disk should be loaded; otherwise, false

    • shouldLoadOnlyLibraries

      protected boolean shouldLoadOnlyLibraries(List<Option> options)
      Checks to see if only libraries should be loaded (i.e., not the main program)
      Parameters:
      options - a List of Options
      Returns:
      True if only libraries should be loaded; otherwise, false

    • getLibraryLoadDepth

      protected int getLibraryLoadDepth(List<Option> options)
      Gets the desired recursive library load depth
      Parameters:
      options - a List of Options
      Returns:
      The desired recursive library load depth

    • getLibraryDestinationFolderPath

      protected String getLibraryDestinationFolderPath(Project project, String projectFolderPath, List<Option> options)
      Gets the project folder path to load the libraries into. It does not have to exist in the project yet.
      Parameters:
      project - The Project. Could be null if there is no project.
      projectFolderPath - The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.
      options - a List of Options
      Returns:
      The path of the project folder to load the libraries into. Could be null if the specified project is null or a destination folder path could not be determined.

    • getLibraryDestinationSearchFolder

      protected DomainFolder getLibraryDestinationSearchFolder(Project project, String libraryDestinationFolderPath, List<Option> options)
      Gets the project folder that libraries are loaded into, to search for existing libraries. It will only be returned if the options to load new libraries into the project are set.
      Parameters:
      project - The Project. Could be null if there is no project.
      libraryDestinationFolderPath - The path of the project folder to load the libraries into. Could be null (@see #getLibraryDestinationFolderPath(Project, String, List)).
      options - a List of Options
      Returns:
      The path of the destination project folder to search for existing libraries, or null if the destination folder is not being used or should not be searched

    • getLibrarySearchFolders

      protected List<DomainFolder> getLibrarySearchFolders(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog log)
      Gets a List of library search folders based on the current options
      Parameters:
      loadedPrograms - the list of Loaded Programs
      project - The Project to load into. Could be null if there is no project.
      options - The List of Options
      log - The log
      Returns:
      A List of library search folders based on the current options

    • shouldSearchAllPaths

      protected boolean shouldSearchAllPaths(Program program, List<Option> options, MessageLog log)
      Checks whether or not to search for libraries using all possible search paths, regardless of what options are set
      Parameters:
      program - The Program being loaded
      options - a List of Options
      log - The log
      Returns:
      True if all possible search paths should be used, regardless of what options are set

    • isCaseInsensitiveLibraryFilenames

      protected boolean isCaseInsensitiveLibraryFilenames()
      Specifies if the library filenames specified by this loader should be exact case match or case-insensitive.

      Derived loader classes should override this method and specify if the OS that normally handles this type of binary is case-insensitive.

      Returns:
      True if case-insensitive or false if case-sensitive.

    • isOptionalLibraryFilenameExtensions

      protected boolean isOptionalLibraryFilenameExtensions()
      Specifies if this loader can refer to library filenames without filename extensions.

      Derived loader classes should override this method if library filename extensions are optional. If they are required, there is no need to override this method.

      Returns:
      True if library filename extensions are optional; otherwise, false

    • createLibraryByteProvider

      protected ByteProvider createLibraryByteProvider(FSRL libFsrl, LoadSpec loadSpec, MessageLog log, TaskMonitor monitor) throws IOException, CancelledException
      Creates a ByteProvider for the given library FSRL
      Parameters:
      libFsrl - The library FSRL to get a ByteProvider for
      loadSpec - An optional LoadSpec the ByteProvider should conform to
      log - The log
      monitor - A cancellable monitor
      Returns:
      A ByteProvider for the given library FSRL, or null if one could not be created that matches the given LoadSpec
      Throws:
      IOException - If there was an IO-related issue
      CancelledException - If the user cancelled the operation

    • processLibrary

      protected void processLibrary(Program library, String libraryName, FSRL libraryFsrl, ByteProvider provider, Queue<AbstractLibrarySupportLoader.UnprocessedLibrary> unprocessed, int depth, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor) throws IOException, CancelledException
      Performs optional follow-on actions after an the given library has been loaded
      Parameters:
      library - The loaded library Program
      libraryName - The name of the library
      libraryFsrl - The library FSRL
      provider - The library bytes
      unprocessed - The Queue of unprocessed libraries
      depth - The load depth of the library to load
      loadSpec - The LoadSpec used for the load
      options - The options
      log - The log
      monitor - A cancelable monitor
      Throws:
      IOException - If an IO-related error occurred
      CancelledException - If the user cancelled the action

    • findLibraryInProject

      protected DomainFile findLibraryInProject(String library, DomainFolder rootSearchFolder, List<AbstractLibrarySupportLoader.LibrarySearchPath> searchPaths, List<Option> options, TaskMonitor monitor) throws CancelledException
      Find the library within the specified root search folder. This method will handle relative path normalization.

      If the library path is a simple name without any path separators, only the given folder will be searched.

      If the library path has a path, it will be treated as a relative path under given folder and if found that DomainFile will be returned.

      If the library path has a path and it wasn't found under the given folder, the filename part of library path will be used to search the given folder for matches.

      Parameters:
      library - library to find
      rootSearchFolder - root folder within which imported libraries will be searched. If null this method will return null.
      searchPaths - A List of AbstractLibrarySupportLoader.LibrarySearchPaths that will be searched
      options - The load options
      monitor - A cancelable task monitor
      Returns:
      The found DomainFile or null if not found
      Throws:
      CancelledException - if the user cancelled the load

    • getCustomLibrarySearchPaths

      protected List<AbstractLibrarySupportLoader.LibrarySearchPath> getCustomLibrarySearchPaths(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor) throws CancelledException
      Gets a List of priority-ordered custom AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries. The default implementation of this method returns an empty List. Subclasses can override it as needed.
      Parameters:
      provider - The ByteProvider of the program being loaded
      options - The options
      log - The log
      monitor - A cancelable task monitor
      Returns:
      A List of priority-ordered custom AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries
      Throws:
      CancelledException - if the user cancelled the load

    • isValidSearchPath

      protected boolean isValidSearchPath(FSRL fsrl, LoadSpec loadSpec, TaskMonitor monitor) throws CancelledException
      Checks to make sure the given search path FSRL is valid before processing it. Subclasses can override it as needed.
      Parameters:
      fsrl - The search path FSRL
      loadSpec - The LoadSpec to use during load.
      monitor - A cancelable task monitor
      Returns:
      True is the search path is valid; otherwise, false
      Throws:
      CancelledException - if the user cancelled the load

    • getLibrarySearchPaths

      protected List<AbstractLibrarySupportLoader.LibrarySearchPath> getLibrarySearchPaths(Program program, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor) throws CancelledException
      Gets a List of priority-ordered AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries
      Parameters:
      program - The Program being loaded
      loadSpec - The LoadSpec to use during load
      options - The options
      log - The log
      monitor - A cancelable task monitor
      Returns:
      A List of priority-ordered AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries
      Throws:
      CancelledException - if the user cancelled the load

    • findLibraryInLoadedList

      protected Loaded<Program> findLibraryInLoadedList(List<Loaded<Program>> loadedPrograms, String libraryName)
      Find the library within the given List of Loaded Programs
      Parameters:
      loadedPrograms - the list of Loaded Programs
      libraryName - The library name to lookup. Depending on the type of library, this could be a simple filename or an absolute path.
      Returns:
      The found Loaded Program or null if not found

    • matchSupportedLoadSpec

      protected LoadSpec matchSupportedLoadSpec(LoadSpec desiredLoadSpec, ByteProvider provider) throws IOException
      Ensures the given LoadSpec matches one supported by the loader
      Parameters:
      desiredLoadSpec - The desired LoadSpec
      provider - The provider
      Returns:
      A supported LoadSpec that matches the desired one, or null of none matched
      Throws:
      IOException - if there was an IO-related error

    • resolveLibraryFile

      protected FSRL resolveLibraryFile(GFileSystem fs, String library) throws IOException
      Resolves the given library path to an existing FSRL. Some Loaders have relaxed requirements on what counts as a valid library filename match. For example, case-insensitive lookup may be allowed, and filename extensions may be optional.
      Parameters:
      fs - The file system to resolve in
      library - The library. This will be either an absolute path, a relative path, or just a filename.
      Returns:
      The library resolved to an existing FSRL, or null if it did not resolve
      Throws:
      IOException - If an IO-related problem occurred