Package ghidra.app.util.opinion

Interface Loader

All Superinterfaces:

Comparable<Loader>, ExtensionPoint

All Known Implementing Classes:

AbstractLibrarySupportLoader, AbstractOrdinalSupportLoader, AbstractProgramLoader, AbstractProgramWrapperLoader, BinaryLoader, CoffLoader, DbgLoader, DefLoader, DyldCacheLoader, ElfLoader, GdtLoader, GzfLoader, IntelHexLoader, MachoLoader, MapLoader, MotorolaHexLoader, MSCoffLoader, MzLoader, NeLoader, OmfLoader, PefLoader, PeLoader, 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 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 LoadSpecs that contain discovered load specification information that this Loader will need to load.
List<Option>	getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram)	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(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Object consumer, TaskMonitor monitor)	Loads bytes in a particular format as a new Loaded DomainObject.
void	loadInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor)	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 Programs can get loaded into other types of Programs
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 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(ByteProvider provider,
 String loadedName,
 Project project,
 String projectFolderPath,
 LoadSpec loadSpec,
 List<Option> options,
 MessageLog messageLog,
 Object consumer,
 TaskMonitor monitor)
                                  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(Project, Object, MessageLog, TaskMonitor)).

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

Parameters:

provider - The bytes to load.

loadedName - A suggested name for the primary Loaded DomainObject. This is just a suggestion, and a Loader implementation reserves the right to change it. The LoadResults 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 DomainObjects. This is just a suggestion, and a Loader implementation reserves the right to change it for each Loaded result. The LoadResults should be queried for their true project folder paths using Loaded.getProjectFolderPath().

loadSpec - The LoadSpec to use during load.

options - The load options.

messageLog - The message log.

consumer - A consumer object for generated DomainObjects.

monitor - A task monitor.

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(ByteProvider provider,
 LoadSpec loadSpec,
 List<Option> options,
 MessageLog messageLog,
 Program program,
 TaskMonitor monitor)
       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:

provider - The bytes to load into the Program.

loadSpec - The LoadSpec to use during load.

options - The load options.

messageLog - The message log.

program - The Program to load into.

monitor - A cancelable task monitor.

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)

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.

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

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.

supportsLoadIntoProgram

@Deprecated(since="10.4")
default boolean supportsLoadIntoProgram()

Deprecated.

use supportsLoadIntoProgram(Program) instead so you can restrict what types of Programs can get loaded into other types of Programs

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>