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<AbstractProgramLoader.LoadedProgram> loadProgram(ByteProvider provider, String programName, DomainFolder programFolder, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) throws CancelledException, IOException
      Description copied from class: AbstractProgramLoader
      Loads program bytes in a particular format as a new Program. Multiple Programs may end up getting created, depending on the nature of the format.
      Specified by:
      loadProgram in class AbstractProgramLoader
      Parameters:
      provider - The bytes to load.
      programName - The name of the Program that's being loaded.
      programFolder - The DomainFolder where the loaded thing should be saved. Could be null if the thing should not be pre-saved.
      loadSpec - The LoadSpec to use during load.
      options - The load options.
      log - The message log.
      consumer - A consumer object for Programs generated.
      monitor - A cancelable task monitor.
      Returns:
      A list of loaded programs (element 0 corresponds to primary loaded Program).
      Throws:
      CancelledException - if the user cancelled the load.
      IOException - if there was an IO-related problem loading.

    • loadProgramInto

      protected boolean loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor) throws CancelledException, 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.
      Returns:
      True if the file was successfully loaded; otherwise, false.
      Throws:
      CancelledException - if the user cancelled the load.
      IOException - if there was an IO-related problem loading.

    • postLoadProgramFixups

      protected void postLoadProgramFixups(List<AbstractProgramLoader.LoadedProgram> loadedPrograms, List<Option> options, MessageLog messageLog, TaskMonitor monitor) throws CancelledException, IOException
      Description copied from class: AbstractProgramLoader
      This gets called after the given list of programss is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.
      Overrides:
      postLoadProgramFixups in class AbstractProgramLoader
      Parameters:
      loadedPrograms - The programs that got loaded.
      options - The load options.
      messageLog - 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(DomainFolder programFolder, List<Option> options)
      Gets the project folder to search for existing libraries
      Parameters:
      programFolder - The DomainFolder that the main program is being loaded into
      options - a List of Options
      Returns:
      The path of the project folder to search for existing libraries, or null if no project folders should be searched

    • isLoadLocalLibraries

      protected boolean isLoadLocalLibraries(List<Option> options)
      Checks to see if local libraries should be loaded. Local libraries are libraries that live in the same directory as the imported program.
      Parameters:
      options - a List of Options
      Returns:
      True if local libraries should be loaded; otherwise, false

    • isLoadSystemLibraries

      protected boolean isLoadSystemLibraries(List<Option> options)
      Checks to see if system libraries should be loaded. System libraries are libraries that live in the directories specified in the GUI path list.
      Parameters:
      options - a List of Options
      Returns:
      True if system 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

    • getLibraryDestinationFolder

      protected DomainFolder getLibraryDestinationFolder(DomainFolder programFolder, List<Option> options)
      Gets the project folder to load the libraries into
      Parameters:
      programFolder - The DomainFolder that the main program is being loaded into
      options - a List of Options
      Returns:
      The path of the project folder to load the libraries into

    • shouldSearchAllPaths

      protected boolean shouldSearchAllPaths(List<Option> options)
      Checks whether or not to search for libraries using all possible search paths, regardless of what options are set
      Parameters:
      options - a List of Options
      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(File libFile, LoadSpec loadSpec, MessageLog log) throws IOException
      Creates a ByteProvider for the given library file
      Parameters:
      libFile - The library file to get a ByteProvider for
      loadSpec - An optional LoadSpec the ByteProvider should conform to
      log - The log
      Returns:
      A ByteProvider for the given library file, or null if one could not be created that matches the given LoadSpec
      Throws:
      IOException - If there was an IO-related issue

    • shouldLoadLibrary

      protected boolean shouldLoadLibrary(String libraryName, File libraryFile, ByteProvider provider, LoadSpec desiredLoadSpec, MessageLog log) throws IOException
      Checks whether or not the given library should be loaded.

      It may be appropriate to not load a specific library after examining its bytes.

      Parameters:
      libraryName - The name of the library
      libraryFile - The library File
      provider - The library bytes
      desiredLoadSpec - The desired LoadSpec
      log - The log
      Returns:
      True if the given library should be loaded; otherwise, false
      Throws:
      IOException - If an IO-related error occurred

    • processLibrary

      protected boolean processLibrary(Program library, String libraryName, File libraryFile, ByteProvider provider, 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
      libraryFile - The library File
      provider - The library bytes
      loadSpec - The LoadSpec used for the load
      options - The options
      log - The log
      monitor - A cancel.able monitor
      Returns:
      True if the library should be saved to the project; otherwise, false
      Throws:
      IOException - If an IO-related error occurred
      CancelledException - If the user cancelled the action

    • 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