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
-
Nested Class Summary
Modifier and TypeClassDescriptionprotected static final record
A file system search path -
Field Summary
Modifier and TypeFieldDescriptionstatic final String
static final String
static final String
static final String
static final String
static final String
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, loggingDisabled, OPTIONS_PROJECT_SAVE_STATE_KEY
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected ByteProvider
createLibraryByteProvider
(FSRL libFsrl, LoadSpec loadSpec, MessageLog log, TaskMonitor monitor) Creates aByteProvider
for the given libraryFSRL
getCustomLibrarySearchPaths
(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor) Gets aList
of priority-ordered customAbstractLibrarySupportLoader.FileSystemSearchPath
s used to search for libraries.getDefaultOptions
(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram) Gets the defaultLoader
options.protected String
getLibraryDestinationFolderPath
(Project project, String projectFolderPath, List<Option> options) Gets the project folder path to load the libraries into.protected DomainFolder
getLibraryDestinationSearchFolder
(Project project, String libraryDestinationFolderPath, List<Option> options) Gets theproject folder
that libraries are loaded into, to search for existing libraries.protected int
getLibraryLoadDepth
(List<Option> options) Gets the desired recursive library load depthprotected DomainFolder
getLinkSearchFolder
(Project project, String projectFolderPath, List<Option> options) Gets theproject folder
to search for existing librariesgetTier()
For ordering purposes; lower tier numbers are more important (and listed first).int
For ordering purposes; lower numbers are more important (and listed first, within its tier).protected boolean
Specifies if the library filenames specified by this loader should be exact case match or case-insensitive.protected boolean
isLinkExistingLibraries
(List<Option> options) Checks to see if existing libraries should be linkedprotected boolean
isLoadLibraries
(List<Option> options) Checks to see if libraries from disk should be loadedprotected boolean
Specifies if this loader can refer to library filenames without filename extensions.protected abstract void
load
(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program, TaskMonitor monitor, MessageLog log) Loads bytes in a particular format into the givenProgram
.loadProgram
(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) protected void
loadProgramInto
(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor) Loads program bytes into the specifiedProgram
.protected LoadSpec
matchSupportedLoadSpec
(LoadSpec desiredLoadSpec, ByteProvider provider) Ensures the givenLoadSpec
matches one supported by the loaderprotected void
postLoadProgramFixups
(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor) This gets called after the given list ofloaded programs
s is finished loading.protected void
processLibrary
(Program library, String libraryName, FSRL libraryFsrl, ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor) Performs optional follow-on actions after an the given library has been loadedprotected FSRL
resolveLibraryFile
(GFileSystem fs, Path libraryParentPath, String libraryName) Resolves the given library path to an existingFSRL
.protected boolean
shouldSearchAllPaths
(List<Option> options) Checks whether or not to search for libraries using all possible search paths, regardless of what options are setvalidateOptions
(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program) Validates theLoader
'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
concatenatePaths, createDefaultMemoryBlocks, createProgram, generateBlockName, getLanguageService, load, loadInto, markAsFunction, postLoadCleanup, release, setProgramProperties, 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, loadsIntoNewFolder, supportsLoadIntoProgram, supportsLoadIntoProgram
-
Field Details
-
LINK_EXISTING_OPTION_NAME
- See Also:
-
LINK_SEARCH_FOLDER_OPTION_NAME
- See Also:
-
LOAD_LIBRARY_OPTION_NAME
- See Also:
-
LIBRARY_SEARCH_PATH_DUMMY_OPTION_NAME
- See Also:
-
DEPTH_OPTION_NAME
- See Also:
-
LIBRARY_DEST_FOLDER_OPTION_NAME
- See Also:
-
-
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 givenProgram
.- Parameters:
provider
- The bytes to load.loadSpec
- TheLoadSpec
to use during load.options
- The load options.program
- TheProgram
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<Loaded<Program>> loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) throws CancelledException, IOException Description copied from class:AbstractProgramLoader
Loads bytes in a particular format as a newLoaded
Program
. MultipleProgram
s may end up getting created, depending on the nature of the format.Note that when the load completes, the returned
Loaded
Program
s are not saved to a project. That is the responsibility of the caller (seeLoaded.save(Project, MessageLog, TaskMonitor)
).It is also the responsibility of the caller to release the returned
Loaded
Program
s withLoaded.release(Object)
when they are no longer needed.- Specified by:
loadProgram
in classAbstractProgramLoader
- Parameters:
provider
- The bytes to load.loadedName
- A suggested name for the primaryLoaded
Program
. This is just a suggestion, and aLoader
implementation reserves the right to change it. TheLoaded
Program
s should be queried for their true names usingLoaded.getName()
.project
- TheProject
. Loaders can use this to take advantage of existingDomainFolder
s andDomainFile
s to do custom behaviors such as loading libraries. Could be null if there is no project.projectFolderPath
- A suggested project folder path for theLoaded
Program
s. This is just a suggestion, and aLoader
implementation reserves the right to change it for eachLoaded
result. TheLoaded
Program
s should be queried for their true project folder paths usingLoaded.getProjectFolderPath()
.loadSpec
- TheLoadSpec
to use during load.options
- The load options.log
- The message log.consumer
- A consumer object for generatedProgram
s.monitor
- A task monitor.- Returns:
- A
List
of one or moreLoaded
Program
s (created but not saved). - Throws:
CancelledException
- if the user cancelled the load.IOException
- if there was an IO-related problem loading.
-
loadProgramInto
protected void loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor) throws CancelledException, LoadException, IOException Description copied from class:AbstractProgramLoader
Loads program bytes into the specifiedProgram
. This method will not create any newProgram
s. It is only for adding to an existingProgram
.NOTE: The loading that occurs in this method will automatically be done in a transaction.
- Specified by:
loadProgramInto
in classAbstractProgramLoader
- Parameters:
provider
- The bytes to load into theProgram
.loadSpec
- TheLoadSpec
to use during load.options
- The load options.log
- The message log.program
- TheProgram
to load into.monitor
- A cancelable task monitor.- Throws:
CancelledException
- if the user cancelled the load.LoadException
- if the load failed in an expected way.IOException
- if there was an IO-related problem loading.
-
postLoadProgramFixups
protected void postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor) throws CancelledException, IOException Description copied from class:AbstractProgramLoader
This gets called after the given list ofloaded programs
s is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.- Overrides:
postLoadProgramFixups
in classAbstractProgramLoader
- Parameters:
loadedPrograms
- Theloaded programs
to be fixed up.project
- TheProject
to load into. Could be null if there is no project.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
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 defaultLoader
options.- Specified by:
getDefaultOptions
in interfaceLoader
- Overrides:
getDefaultOptions
in classAbstractProgramLoader
- Parameters:
provider
- The bytes of the thing being loaded.loadSpec
- TheLoadSpec
.domainObject
- TheDomainObject
being loaded.loadIntoProgram
- True if the load is adding to an existingDomainObject
; 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 theLoader
's options and returns null if all options are valid; otherwise, an error message describing the problem is returned.- Specified by:
validateOptions
in interfaceLoader
- Overrides:
validateOptions
in classAbstractProgramLoader
- Parameters:
provider
- The bytes of the thing being loaded.loadSpec
- The proposedLoadSpec
.options
- The list ofOption
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.
-
isLinkExistingLibraries
Checks to see if existing libraries should be linked -
getLinkSearchFolder
protected DomainFolder getLinkSearchFolder(Project project, String projectFolderPath, List<Option> options) Gets theproject folder
to search for existing libraries- Parameters:
project
- TheProject
. Could be null if there is no project.projectFolderPath
- The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.options
- aList
ofOption
s- Returns:
- The path of the project folder to search for existing libraries, or null if no project folders can be or should be searched
-
isLoadLibraries
Checks to see if libraries from disk should be loaded -
getLibraryLoadDepth
Gets the desired recursive library load depth -
getLibraryDestinationFolderPath
protected String getLibraryDestinationFolderPath(Project project, String projectFolderPath, List<Option> options) Gets the project folder path to load the libraries into. It does not have to exist in the project yet.- Parameters:
project
- TheProject
. Could be null if there is no project.projectFolderPath
- The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.options
- aList
ofOption
s- Returns:
- The path of the project folder to load the libraries into. Could be null if the specified project is null or a destination folder path could not be determined.
-
getLibraryDestinationSearchFolder
protected DomainFolder getLibraryDestinationSearchFolder(Project project, String libraryDestinationFolderPath, List<Option> options) Gets theproject folder
that libraries are loaded into, to search for existing libraries. It will only be returned if the options to load new libraries into the project are set.- Parameters:
project
- TheProject
. Could be null if there is no project.libraryDestinationFolderPath
- The path of the project folder to load the libraries into. Could be null (@see #getLibraryDestinationFolderPath(Project, String, List)).options
- aList
ofOption
s- Returns:
- The path of the destination project folder to search for existing libraries, or null if the destination folder is not being used or should not be searched
-
shouldSearchAllPaths
Checks whether or not to search for libraries using all possible search paths, 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(FSRL libFsrl, LoadSpec loadSpec, MessageLog log, TaskMonitor monitor) throws IOException, CancelledException Creates aByteProvider
for the given libraryFSRL
- Parameters:
libFsrl
- The libraryFSRL
to get aByteProvider
forloadSpec
- An optionalLoadSpec
theByteProvider
should conform tolog
- The logmonitor
- A cancellable monitor- Returns:
- A
ByteProvider
for the given libraryFSRL
, or null if one could not be created that matches the givenLoadSpec
- Throws:
IOException
- If there was an IO-related issueCancelledException
- If the user cancelled the operation
-
processLibrary
protected void processLibrary(Program library, String libraryName, FSRL libraryFsrl, 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 libraryProgram
libraryName
- The name of the librarylibraryFsrl
- The libraryFSRL
provider
- The library bytesloadSpec
- TheLoadSpec
used for the loadoptions
- The optionslog
- The logmonitor
- A cancelable monitor- Throws:
IOException
- If an IO-related error occurredCancelledException
- If the user cancelled the action
-
getCustomLibrarySearchPaths
protected List<AbstractLibrarySupportLoader.FileSystemSearchPath> getCustomLibrarySearchPaths(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor) throws CancelledException Gets aList
of priority-ordered customAbstractLibrarySupportLoader.FileSystemSearchPath
s used to search for libraries. The default implementation of this method returns an emptyList
. Subclasses can override it as needed.- Parameters:
provider
- TheByteProvider
of the program being loadedoptions
- The optionslog
- The logmonitor
- A cancelable task monitor- Returns:
- A
List
of priority-ordered customAbstractLibrarySupportLoader.FileSystemSearchPath
s used to search for libraries - Throws:
CancelledException
- if the user cancelled the load
-
matchSupportedLoadSpec
protected LoadSpec matchSupportedLoadSpec(LoadSpec desiredLoadSpec, ByteProvider provider) throws IOException Ensures the givenLoadSpec
matches one supported by the loader- Parameters:
desiredLoadSpec
- The desiredLoadSpec
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
-
resolveLibraryFile
protected FSRL resolveLibraryFile(GFileSystem fs, Path libraryParentPath, String libraryName) throws IOException Resolves the given library path to an existingFSRL
. SomeLoader
s have relaxed requirements on what counts as a valid library filename match. For example, case-insensitive lookup may be allowed, and filename extensions may be optional.- Parameters:
fs
- Thefile system
to resolve inlibraryParentPath
- ThePath
of the library's parent directory, relative to the given file system (could be null)libraryName
- The library name- Returns:
- The library resolved to an existing
FSRL
, or null if it did not resolve - Throws:
IOException
- If an IO-related problem occurred
-