Interface Loader

All Superinterfaces:
Comparable<Loader>, ExtensionPoint
All Known Implementing Classes:
AbstractLibrarySupportLoader, AbstractOrdinalSupportLoader, AbstractProgramLoader, AbstractProgramWrapperLoader, BinaryLoader, CoffLoader, ComLoader, DbgLoader, DecompileDebugXmlLoader, DefLoader, DyldCacheLoader, ElfLoader, GdtLoader, GzfLoader, IntelHexLoader, MachoLoader, MapLoader, MotorolaHexLoader, MSCoffLoader, MzLoader, NeLoader, Omf51Loader, OmfLoader, PefLoader, PeLoader, SomLoader, TenetLoader, TenetPlusPlusLoader, UnixAoutLoader, XmlLoader
public interface Loader extends ExtensionPoint, Comparable<Loader>
An interface that all loaders must implement. A particular loader implementation should be designed to identify one and only one file format.

NOTE: ALL loader CLASSES MUST END IN "Loader". If not, the ClassSearcher will not find them.

  • Field Details

    • COMMAND_LINE_ARG_PREFIX

      static final String COMMAND_LINE_ARG_PREFIX
      A string prefixed to each loader headless command line argument to avoid naming conflicts with other headless command line argument names
      See Also:

    • OPTIONS_PROJECT_SAVE_STATE_KEY

      static final String OPTIONS_PROJECT_SAVE_STATE_KEY
      Key used to lookup and store all loader options in the project's saved state
      See Also:

    • loggingDisabled

      static final boolean loggingDisabled
      System property used to disable the loaders' message logs being echoed to the application.log file

  • Method Details

    • findSupportedLoadSpecs

      Collection<LoadSpec> findSupportedLoadSpecs(ByteProvider provider) throws IOException
      If this Loader supports loading the given ByteProvider, this methods returns a Collection of all supported LoadSpecs that contain discovered load specification information that this Loader will need to load. If this Loader cannot support loading the given ByteProvider, an empty Collection is returned.
      Parameters:
      provider - The bytes being loaded.
      Returns:
      A Collection of LoadSpecs that this Loader supports loading, or an empty Collection if this Loader doesn't support loading the given ByteProvider.
      Throws:
      IOException - if there was an IO-related issue finding the LoadSpecs.

    • load

      LoadResults<? extends DomainObject> load(Loader.ImporterSettings settings) throws IOException, CancelledException, VersionException, LoadException
      Loads bytes in a particular format as a new Loaded DomainObject. Multiple DomainObjects may end up getting created, depending on the nature of the format. The Loaded DomainObjects are bundled together in a LoadResults object which provides convenience methods to operate on the entire group of Loaded DomainObjects.

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

      It is also the responsibility of the caller to close the returned Loaded DomainObjects with LoadResults.close() when they are no longer needed.

      Parameters:
      settings - The Loader.ImporterSettings.
      Returns:
      The LoadResults which contains one or more Loaded DomainObjects (created but not saved).
      Throws:
      LoadException - if the load failed in an expected way
      IOException - if there was an IO-related problem loading.
      CancelledException - if the user cancelled the load.
      VersionException - if the load process tried to open an existing DomainFile which was created with a newer or unsupported version of Ghidra

    • loadInto

      void loadInto(Program program, Loader.ImporterSettings settings) throws IOException, LoadException, CancelledException
      Loads bytes into the specified Program. This method will not create any new Programs. It is only for adding to an existing Program.
      Parameters:
      program - The Program to load into.
      settings - The Loader.ImporterSettings.
      Throws:
      LoadException - if the load failed in an expected way.
      IOException - if there was an IO-related problem loading.
      CancelledException - if the user cancelled the load.

    • getDefaultOptions

      List<Option> getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram, boolean mirrorFsLayout)
      Gets the default Loader options.
      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.
      mirrorFsLayout - True if the filesystem layout should be mirrored when loading; otherwise, false
      Returns:
      A list of the Loader's default options.

    • validateOptions

      String validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)
      Validates the Loader's options and returns null if all options are valid; otherwise, an error message describing the problem is returned.
      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.

    • getName

      String getName()
      Gets the Loader's name, which is used both for display purposes, and to identify the Loader in the opinion files.
      Returns:
      The Loader's name.

    • getTier

      LoaderTier getTier()
      For ordering purposes; lower tier numbers are more important (and listed first).
      Returns:
      the tier of the loader

    • getTierPriority

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

    • isFallback NEW

      default boolean isFallback()
      Returns whether or not this is a "fallback" Loader.

      Fallback loaders are only considered during the import process if no other non-fallback loaders were compatible with the thing being imported.

      Returns:
      whether or not this is a "fallback" Loader

    • getPreferredFileName

      default String getPreferredFileName(ByteProvider provider)
      The preferred file name to use when loading.

      The default behavior of this method is to return the (cleaned up) name of the given ByteProvider.

      NOTE: This method may get called frequently, so only parse the given ByteProvider if absolutely necessary.

      Parameters:
      provider - The bytes to load.
      Returns:
      The preferred file name to use when loading, or null if a name could not be determined from the provider.

    • supportsLoadIntoProgram

      default boolean supportsLoadIntoProgram(Program program)
      Checks to see if this Loader supports loading into the given Program.

      The default behavior of this method is to return false.

      Parameters:
      program - The Program to load into
      Returns:
      True if this Loader supports loading into the given Program; otherwise, false.

    • loadsIntoNewFolder

      default boolean loadsIntoNewFolder()
      Checks to see if this Loader loads into a new DomainFolder instead of a new DomainFile
      Returns:
      True if this Loader loads into a new DomainFolder instead of a new DomainFile

    • createArg NEW

      default String createArg(String arg)
      Returns the given argument with COMMAND_LINE_ARG_PREFIX prepended.

      This is a convenience method to make working with Loader command line options less verbose.

      Parameters:
      arg - the argument
      Returns:
      the given argument with COMMAND_LINE_ARG_PREFIX prepended

    • getAssociatedFileExtensions NEW

      default Collection<String> getAssociatedFileExtensions()
      Returns a Collection of file extensions associated with this Loader.
      Returns:
      a Collection of file extensions associated with this Loader

    • compareTo

      default int compareTo(Loader o)
      Specified by:
      compareTo in interface Comparable<Loader>