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
,Omf51Loader
,OmfLoader
,PefLoader
,PeLoader
,XmlLoader
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
Modifier and TypeFieldDescriptionstatic final String
A string prefixed to each loader headless command line argument to avoid naming conflicts with other headless command line argument namesstatic final boolean
System property used to disable the loaders' message logs being echoed to the application.log filestatic final String
Key used to lookup and store all loader options in the project's saved state -
Method Summary
Modifier and TypeMethodDescriptiondefault int
findSupportedLoadSpecs
(ByteProvider provider) If thisLoader
supports loading the givenByteProvider
, this methods returns aCollection
of all supportedLoadSpec
s that contain discovered load specification information that thisLoader
will need to load.getDefaultOptions
(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram) Gets the defaultLoader
options.getName()
default String
getPreferredFileName
(ByteProvider provider) The preferred file name to use when loading.getTier()
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).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 newLoaded
DomainObject
.void
loadInto
(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor) Loads bytes into the specifiedProgram
.default boolean
default boolean
Deprecated.default boolean
supportsLoadIntoProgram
(Program program) validateOptions
(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.
-
Field Details
-
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
Key used to lookup and store all loader options in the project's saved state- See Also:
-
loggingDisabled
static final boolean loggingDisabledSystem property used to disable the loaders' message logs being echoed to the application.log file
-
-
Method Details
-
findSupportedLoadSpecs
If thisLoader
supports loading the givenByteProvider
, this methods returns aCollection
of all supportedLoadSpec
s that contain discovered load specification information that thisLoader
will need to load. If thisLoader
cannot support loading the givenByteProvider
, an emptyCollection
is returned.- Parameters:
provider
- The bytes being loaded.- Returns:
- A
Collection
ofLoadSpec
s that thisLoader
supports loading, or an emptyCollection
if thisLoader
doesn't support loading the givenByteProvider
. - Throws:
IOException
- if there was an IO-related issue finding theLoadSpec
s.
-
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 newLoaded
DomainObject
. MultipleDomainObject
s may end up getting created, depending on the nature of the format. TheLoaded
DomainObject
s are bundled together in aLoadResults
object which provides convenience methods to operate on the entire group ofLoaded
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 (seeLoadResults.save(Project, Object, MessageLog, TaskMonitor)
).It is also the responsibility of the caller to release the returned
Loaded
DomainObject
s withLoadResults.release(Object)
when they are no longer needed.- Parameters:
provider
- The bytes to load.loadedName
- A suggested name for the primaryLoaded
DomainObject
. This is just a suggestion, and aLoader
implementation reserves the right to change it. TheLoadResults
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
DomainObject
s. This is just a suggestion, and aLoader
implementation reserves the right to change it for eachLoaded
result. TheLoadResults
should be queried for their true project folder paths usingLoaded.getProjectFolderPath()
.loadSpec
- TheLoadSpec
to use during load.options
- The load options.messageLog
- The message log.consumer
- A consumer object for generatedDomainObject
s.monitor
- A task monitor.- Returns:
- The
LoadResults
which contains one or moreLoaded
DomainObject
s (created but not saved). - Throws:
LoadException
- if the load failed in an expected wayIOException
- if there was an IO-related problem loading.CancelledException
- if the user cancelled the load.VersionException
- if the load process tried to open an existingDomainFile
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 specifiedProgram
. This method will not create any newProgram
s. It is only for adding to an existingProgram
.- Parameters:
provider
- The bytes to load into theProgram
.loadSpec
- TheLoadSpec
to use during load.options
- The load options.messageLog
- The message log.program
- TheProgram
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 defaultLoader
options.- 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
String validateOptions(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.- 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.
-
getName
String getName()Gets theLoader
's name, which is used both for display purposes, and to identify theLoader
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
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.usesupportsLoadIntoProgram(Program)
instead so you can restrict what types ofProgram
s can get loaded into other types ofProgram
s -
supportsLoadIntoProgram
-
loadsIntoNewFolder
default boolean loadsIntoNewFolder()- Returns:
- True if this
Loader
loads into a newDomainFolder
instead of a newDomainFile
-
compareTo
- Specified by:
compareTo
in interfaceComparable<Loader>
-
supportsLoadIntoProgram(Program)
instead so you can restrict what types ofProgram
s can get loaded into other types ofProgram
s