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, java.lang.Comparable<Loader>

Direct Known Subclasses:

CoffLoader, DbgLoader, DefLoader, DyldCacheLoader, ElfLoader, MachoLoader, MapLoader, MzLoader, NeLoader, OmfLoader, PefLoader, PeLoader

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 are responsible for the actual load.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	LIB_OPTION_NAME
static java.lang.String	SYM_OPTION_NAME

Fields inherited from class ghidra.app.util.opinion.AbstractProgramLoader

ANCHOR_LABELS_OPTION_NAME, APPLY_LABELS_OPTION_NAME

Fields inherited from interface ghidra.app.util.opinion.Loader

COMMAND_LINE_ARG_PREFIX

Constructor Summary

Constructors

Constructor	Description
AbstractLibrarySupportLoader()

Method Summary

Modifier and Type	Method	Description
protected void	createExportsFile(java.lang.String libName, java.io.File libFile, MessageLog log, TaskMonitor monitor, int size, Program program)	Creates the library exports file, if necessary
protected DomainFile	findAlreadyImportedLibrary(java.lang.String libPathFilename, DomainFolder domainFolder)	Find the libPathFilename within the specified importFolder.
java.util.List<Option>	getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram)	Gets the default Loader options.
protected LoadSpec	getLoadSpec(LoadSpec loadSpec, ByteProvider provider)
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).
protected boolean	importLibrary(java.lang.String libName, DomainFolder libFolder, java.io.File libFile, ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, MessageLog log, java.lang.Object consumer, java.util.Set<java.lang.String> unprocessedLibs, java.util.List<Program> programList, TaskMonitor monitor)	Imports a library file into a ghidra project.
protected boolean	importLibrary(java.lang.String libName, DomainFolder libFolder, java.io.File libFile, LoadSpec loadSpec, java.util.List<Option> options, MessageLog log, java.lang.Object consumer, java.util.Set<java.lang.String> unprocessedLibs, java.util.List<Program> programList, TaskMonitor monitor)	Imports a library file into a ghidra project.
protected boolean	isCaseInsensitiveLibraryFilenames()	Specifies if the library filenames specified by this loader should be exact case match or case-insensitive.
protected abstract void	load(ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, Program program, TaskMonitor monitor, MessageLog log)	Loads bytes in a particular format into the given Program.
protected java.util.List<Program>	loadProgram(ByteProvider provider, java.lang.String programName, DomainFolder programFolder, LoadSpec loadSpec, java.util.List<Option> options, MessageLog log, java.lang.Object consumer, TaskMonitor monitor)	Loads program bytes in a particular format as a new Program.
protected boolean	loadProgramInto(ByteProvider provider, LoadSpec loadSpec, java.util.List<Option> options, MessageLog log, Program program, TaskMonitor monitor)	Loads program bytes into the specified Program.
protected void	postLoadProgramFixups(java.util.List<Program> loadedPrograms, DomainFolder folder, java.util.List<Option> options, MessageLog messageLog, TaskMonitor monitor)	This gets called after the given list of Programs is finished loading.
java.lang.String	validateOptions(ByteProvider provider, LoadSpec loadSpec, java.util.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.

Methods inherited from class ghidra.app.util.opinion.AbstractProgramLoader

createDefaultMemoryBlocks, createProgram, generateBlockName, getLanguageService, load, loadInto, markAsFunction, release, shouldApplyProcessorLabelsByDefault

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ghidra.app.util.opinion.Loader

compareTo, findSupportedLoadSpecs, getName, getPreferredFileName, supportsLoadIntoProgram

Field Detail

SYM_OPTION_NAME

public static final java.lang.String SYM_OPTION_NAME

See Also:

Constant Field Values

LIB_OPTION_NAME

public static final java.lang.String LIB_OPTION_NAME

See Also:

Constant Field Values

Constructor Detail

AbstractLibrarySupportLoader

public AbstractLibrarySupportLoader()

Method Detail

load

protected abstract void load(ByteProvider provider,
                             LoadSpec loadSpec,
                             java.util.List<Option> options,
                             Program program,
                             TaskMonitor monitor,
                             MessageLog log)
                      throws CancelledException,
                             java.io.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:

java.io.IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

loadProgram

protected java.util.List<Program> loadProgram(ByteProvider provider,
                                              java.lang.String programName,
                                              DomainFolder programFolder,
                                              LoadSpec loadSpec,
                                              java.util.List<Option> options,
                                              MessageLog log,
                                              java.lang.Object consumer,
                                              TaskMonitor monitor)
                                       throws CancelledException,
                                              java.io.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.

java.io.IOException - if there was an IO-related problem loading.

loadProgramInto

protected boolean loadProgramInto(ByteProvider provider,
                                  LoadSpec loadSpec,
                                  java.util.List<Option> options,
                                  MessageLog log,
                                  Program program,
                                  TaskMonitor monitor)
                           throws CancelledException,
                                  java.io.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.

java.io.IOException - if there was an IO-related problem loading.

getDefaultOptions

public java.util.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 java.lang.String validateOptions(ByteProvider provider,
                                        LoadSpec loadSpec,
                                        java.util.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.

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

postLoadProgramFixups

protected void postLoadProgramFixups(java.util.List<Program> loadedPrograms,
                                     DomainFolder folder,
                                     java.util.List<Option> options,
                                     MessageLog messageLog,
                                     TaskMonitor monitor)
                              throws CancelledException,
                                     java.io.IOException

Description copied from class: AbstractProgramLoader

This gets called after the given list of Programs 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.

folder - The folder the programs were loaded to.

options - The load options.

messageLog - The message log.

monitor - A cancelable task monitor.

Throws:

CancelledException - if the user cancelled the load.

java.io.IOException - if there was an IO-related problem loading.

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.

findAlreadyImportedLibrary

protected DomainFile findAlreadyImportedLibrary(java.lang.String libPathFilename,
                                                DomainFolder domainFolder)

Find the libPathFilename within the specified importFolder. This method will handle relative path normalization.

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

If libPathFilename has a path, it will be treated as a relative path under importFolder and if found that DomainFile will be returned.

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

Parameters:

libPathFilename - String path with filename of the library to find

domainFolder - DomainFolder folder within which imported libraries will be searched. If null this method will return null.

Returns:

found DomainFile or null if not found

importLibrary

protected boolean importLibrary(java.lang.String libName,
                                DomainFolder libFolder,
                                java.io.File libFile,
                                LoadSpec loadSpec,
                                java.util.List<Option> options,
                                MessageLog log,
                                java.lang.Object consumer,
                                java.util.Set<java.lang.String> unprocessedLibs,
                                java.util.List<Program> programList,
                                TaskMonitor monitor)
                         throws CancelledException,
                                java.io.IOException

Imports a library file into a ghidra project.

Parameters:

libName - the name of the library to import

libFolder - the library folder

libFile - the library file to load

loadSpec - the LoadSpec

options - the load options

log - the message log

consumer - consumer object for the Program generated

unprocessedLibs - list of libraries that need to be loaded

programList - list of programs to add the imported library to

monitor - the task monitor

Returns:

true if the load was successful

Throws:

CancelledException - if the user cancelled the load operation

java.io.IOException - if there was an error during the load

importLibrary

protected boolean importLibrary(java.lang.String libName,
                                DomainFolder libFolder,
                                java.io.File libFile,
                                ByteProvider provider,
                                LoadSpec loadSpec,
                                java.util.List<Option> options,
                                MessageLog log,
                                java.lang.Object consumer,
                                java.util.Set<java.lang.String> unprocessedLibs,
                                java.util.List<Program> programList,
                                TaskMonitor monitor)
                         throws CancelledException,
                                java.io.IOException

Imports a library file into a ghidra project. Use this method if you already have a ByteProvider available.

Parameters:

libName - the name of the library to import

libFolder - the library folder

libFile - the library file to load

provider - the byte provider

loadSpec - the LoadSpec

options - the load options

log - the message log

consumer - consumer object for the Program generated

unprocessedLibs - list of libraries that need to be loaded

programList - list of programs to add the imported library to

monitor - the task monitor

Returns:

true if the load was successful

Throws:

CancelledException - if the user cancelled the load operation

java.io.IOException - if there was an error during the load

createExportsFile

protected void createExportsFile(java.lang.String libName,
                                 java.io.File libFile,
                                 MessageLog log,
                                 TaskMonitor monitor,
                                 int size,
                                 Program program)
                          throws CancelledException

Creates the library exports file, if necessary

Parameters:

libName - the name of the library

libFile - the library file

log - the message log

monitor - the task monitor

size - the language size

program - the loaded library program

Throws:

CancelledException - thrown is task cancelled

getLoadSpec

protected LoadSpec getLoadSpec(LoadSpec loadSpec,
                               ByteProvider provider)
                        throws java.io.IOException

Throws:

java.io.IOException