Package ghidra.app.util.opinion

# Interface Loader

All Superinterfaces:
  `Comparable<Loader>`, `ExtensionPoint`

All Known Implementing Classes:
  `AbstractLibrarySupportLoader`, `AbstractOrdinalSupportLoader`, `AbstractProgramLoader`, `AbstractProgramWrapperLoader`, `BinaryLoader`, `CoffLoader`, `DbgLoader`, `DecompileDebugXmlLoader`, `DefLoader`, `DyldCacheLoader`, `ElfLoader`, `GdtLoader`, `GzfLoader`, `IntelHexLoader`, `MachoLoader`, `MapLoader`, `MotorolaHexLoader`, `MSCoffLoader`, `MzLoader`, `NeLoader`, `Omf51Loader`, `OmfLoader`, `PefLoader`, `PeLoader`, `SomLoader`, `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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static final record`
  `Loader.ImporterSettings`
  A `Loader` configuration

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `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
  `static final boolean`
  `loggingDisabled`
  System property used to disable the loaders' message logs being echoed to the application.log file
  `static final String`
  `OPTIONS_PROJECT_SAVE_STATE_KEY`
  Key used to lookup and store all loader options in the project's saved state

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default int`
  `compareTo(Loader o)`
  `Collection<LoadSpec>`
  `findSupportedLoadSpecs(ByteProvider provider)`
  If this `Loader` supports loading the given `ByteProvider`, this methods returns a `Collection` of all supported `LoadSpec`s that contain discovered load specification information that this `Loader` will need to load.
  `List<Option>`
  `getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram, boolean mirrorFsLayout)`
  Gets the default `Loader` options.
  `String`
  `getName()`
  Gets the `Loader`'s name, which is used both for display purposes, and to identify the `Loader` in the opinion files.
  `default String`
  `getPreferredFileName(ByteProvider provider)`
  The preferred file name to use when loading.
  `LoaderTier`
  `getTier()`
  For ordering purposes; lower tier numbers are more important (and listed first).
  `int`
  `getTierPriority()`
  For ordering purposes; lower numbers are more important (and listed first, within its tier).
  `LoadResults<? extends DomainObject>`
  `load(Loader.ImporterSettings settings)`
  Loads bytes in a particular format as a new `Loaded` `DomainObject`.
  `void`
  `loadInto(Program program, Loader.ImporterSettings settings)`
  Loads bytes into the specified `Program`.
  `default boolean`
  `loadsIntoNewFolder()`
  Checks to see if this `Loader` loads into a new `DomainFolder` instead of a new `DomainFile`
  `default boolean`
  `supportsLoadIntoProgram()`
  Deprecated.
  use `supportsLoadIntoProgram(Program)` instead so you can restrict what types of `Program`s can get loaded into other types of `Program`s
  `default boolean`
  `supportsLoadIntoProgram(Program program)`
  Checks to see if this `Loader` supports loading into the given `Program`.
  `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.

- ## 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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 `LoadSpec`s 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 `LoadSpec`s 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 `LoadSpec`s.

  - ### 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 `DomainObject`s may end up getting created, depending on the nature of the format. The `Loaded` `DomainObject`s are bundled together in a `LoadResults` object which provides convenience methods to operate on the entire group of `Loaded` `DomainObject`s.

    Note that when the load completes, the returned `Loaded` `DomainObject`s 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` `DomainObject`s with `LoadResults.close()` when they are no longer needed.

    Parameters:
      `settings` - The `Loader.ImporterSettings`.
    Returns:
      The `LoadResults` which contains one or more `Loaded` `DomainObject`s (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 `Program`s. 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 `Option`s 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 `Option`s 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

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

    @Deprecated(since="10.4") default boolean supportsLoadIntoProgram()
    Deprecated.
    use `supportsLoadIntoProgram(Program)` instead so you can restrict what types of `Program`s can get loaded into other types of `Program`s
    Checks to see if this `Loader` supports loading into an existing `Program`.

    The default behavior of this method is to return false.

    Returns:
      True if this `Loader` supports loading into an existing `Program`; otherwise, false.

  - ### 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`

  - ### compareTo

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