Package ghidra.program.database.external

Class ExternalManagerDB

java.lang.Object

ghidra.program.database.external.ExternalManagerDB

All Implemented Interfaces:

ManagerDB, ExternalManager

public class ExternalManagerDB
extends Object
implements ManagerDB, ExternalManager

Manages the database for external references.

Constructor Summary

Constructors

Constructor	Description
ExternalManagerDB(DBHandle handle, AddressMap addrMap, OpenMode openMode, Lock lock, TaskMonitor monitor)	Constructs a new ExternalManagerDB

Method Summary

Modifier and Type	Method	Description
Library	addExternalLibraryName(String name, SourceType source)	Adds a new external library name
ExternalLocation	addExtFunction(Namespace extParentNamespace, String extLabel, Address extAddr, SourceType sourceType)	Create an external Function in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr.
ExternalLocation	addExtFunction(Namespace extNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting)	Get or create an external Function in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr.
ExternalLocation	addExtFunction(String extLibraryName, String extLabel, Address extAddr, SourceType sourceType)	Create an external Function in the external Library namespace libararyName and identified by extLabel and/or its memory address extAddr.
ExternalLocation	addExtLocation(Namespace extParentNamespace, String extLabel, Address extAddr, SourceType sourceType)	Create an external location in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr.
ExternalLocation	addExtLocation(Namespace extParentNamespace, String extLabel, Address extAddr, SourceType sourceType, boolean reuseExisting)	Get or create an external location in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr.
ExternalLocation	addExtLocation(String extLibraryName, String extLabel, Address extAddr, SourceType sourceType)	Get or create an external location associated with a library/file named libraryName and the location within that file identified by extLabel and/or its memory address extAddr.
boolean	contains(String libraryName)	Determines if the indicated external library name is being managed (exists).
void	deleteAddressRange(Address startAddr, Address endAddr, TaskMonitor monitor)	Delete all objects which have been applied to the address range startAddr to endAddr and update the database accordingly.
static String	getDefaultExternalName(SymbolDB sym)	Get the default name for an external function or code symbol
Library	getExternalLibrary(String name)	Get the Library which corresponds to the specified name
String[]	getExternalLibraryNames()	Returns an array of all external names for which locations have been defined.
String	getExternalLibraryPath(String externalName)	Returns the file pathname associated with an external name.
ExternalLocation	getExternalLocation(Namespace extNamespace, String extLabel)	Get an external location.
ExternalLocation	getExternalLocation(Symbol symbol)	Returns the external location associated with the given external symbol
ExternalLocation	getExternalLocation(String extName, String extLabel)	Get an external location.
ExternalLocationIterator	getExternalLocations(Address memoryAddress)	Get an iterator over all external locations which have been associated to the specified memory address
List<ExternalLocation>	getExternalLocations(Namespace libScope, String extLabel)	Returns a list of External Locations matching the given label name in the given Namespace.
ExternalLocationIterator	getExternalLocations(String externalName)	Get an iterator over all external locations associated with the specified externalName.
List<ExternalLocation>	getExternalLocations(String libraryName, String label)	Returns a list of External Locations matching the given label name in the given Library.
ExternalLocation	getExtLocation(Address externalAddr)	Returns the external location associated with the given external address
ExternalLocation	getUniqueExternalLocation(Namespace namespace, String label)	Returns the unique external location associated with the given namespace and label
ExternalLocation	getUniqueExternalLocation(String libraryName, String label)	Returns the unique external location associated with the given library name and label
void	invalidateCache(boolean all)	Clears all data caches.
void	moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor)	Move all objects within an address range to a new location.
void	programReady(OpenMode openMode, int currentRevision, TaskMonitor monitor)	Callback from program made to each manager after the program has completed initialization.
boolean	removeExternalLibrary(String name)	Removes external name if no associated ExternalLocation's exist
boolean	removeExternalLocation(Address externalAddr)	Removes the external location at the given external address
void	setExternalPath(String externalName, String externalPath, boolean userDefined)	Sets the file pathname associated with an existing external name.
void	setLanguage(LanguageTranslator translator, TaskMonitor monitor)
void	setProgram(ProgramDB program)	Callback from program used to indicate all manager have been created.
void	updateExternalLibraryName(String oldName, String newName, SourceType source)	Update the external program for all references.

Methods inherited from class java.lang.Object

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

Methods inherited from interface ghidra.program.database.ManagerDB

dispose

Constructor Details

ExternalManagerDB

public ExternalManagerDB(DBHandle handle,
 AddressMap addrMap,
 OpenMode openMode,
 Lock lock,
 TaskMonitor monitor)
                  throws CancelledException,
IOException,
VersionException

Constructs a new ExternalManagerDB

Parameters:

handle - the open database handle

addrMap - the address map

openMode - the program open mode.

lock - the program synchronization lock

monitor - the progress monitor used when upgrading

Throws:

CancelledException - if the user cancelled while an upgrade was occurring

IOException - if a database io error occurs.

VersionException - if the database version does not match the expected version

Method Details

setProgram

public void setProgram(ProgramDB program)

Description copied from interface: ManagerDB

Callback from program used to indicate all manager have been created. When this method is invoked, all managers have been instantiated but may not be fully initialized.

Specified by:

setProgram in interface ManagerDB

Parameters:

program - the program is set when all the initializations have been completed.

programReady

public void programReady(OpenMode openMode,
 int currentRevision,
 TaskMonitor monitor)
                  throws IOException,
CancelledException

Description copied from interface: ManagerDB

Callback from program made to each manager after the program has completed initialization. This method may be used by managers to perform additional upgrading which may have been deferred.

Specified by:

programReady in interface ManagerDB

Parameters:

openMode - the mode that the program is being opened.

currentRevision - current program revision. If openMode is UPGRADE, this value reflects the pre-upgrade value.

monitor - the task monitor to use in any upgrade operations.

Throws:

IOException - if a database io error occurs.

CancelledException - if the user cancelled the operation via the task monitor.

invalidateCache

public void invalidateCache(boolean all)
                     throws IOException

Description copied from interface: ManagerDB

Clears all data caches.

Specified by:

invalidateCache in interface ManagerDB

Parameters:

all - if false, some managers may not need to update their cache if they can tell that its not necessary. If this flag is true, then all managers should clear their cache no matter what.

Throws:

IOException - if a database io error occurs.

deleteAddressRange

public void deleteAddressRange(Address startAddr,
 Address endAddr,
 TaskMonitor monitor)
                        throws CancelledException

Description copied from interface: ManagerDB

Delete all objects which have been applied to the address range startAddr to endAddr and update the database accordingly. The specified start and end addresses must form a valid range within a single AddressSpace.

Specified by:

deleteAddressRange in interface ManagerDB

Parameters:

startAddr - the first address in the range.

endAddr - the last address in the range.

monitor - the task monitor to use in any upgrade operations.

Throws:

CancelledException - if the user cancelled the operation via the task monitor.

moveAddressRange

public void moveAddressRange(Address fromAddr,
 Address toAddr,
 long length,
 TaskMonitor monitor)
                      throws CancelledException

Description copied from interface: ManagerDB

Move all objects within an address range to a new location.

Specified by:

moveAddressRange in interface ManagerDB

Parameters:

fromAddr - the first address of the range to be moved.

toAddr - the address where to the range is to be moved.

length - the number of addresses to move.

monitor - the task monitor to use in any upgrade operations.

Throws:

CancelledException - if the user cancelled the operation via the task monitor.

addExtLocation

public ExternalLocation addExtLocation(String extLibraryName,
 String extLabel,
 Address extAddr,
 SourceType sourceType)
                                throws InvalidInputException,
DuplicateNameException

Description copied from interface: ExternalManager

Get or create an external location associated with a library/file named libraryName and the location within that file identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtLocation in interface ExternalManager

Parameters:

extLibraryName - the external library name

extLabel - the external label or null

extAddr - the external memory address or null

sourceType - the source type of this external library's symbol

Returns:

external location

Throws:

InvalidInputException - if libraryName is invalid or null, or an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

DuplicateNameException - if another non-Library namespace has the same name

addExtLocation

public ExternalLocation addExtLocation(Namespace extParentNamespace,
 String extLabel,
 Address extAddr,
 SourceType sourceType)
                                throws InvalidInputException

Description copied from interface: ExternalManager

Create an external location in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtLocation in interface ExternalManager

Parameters:

extParentNamespace - the external namespace

extLabel - the external label or null

extAddr - the external memory address or null

sourceType - the source type of this external library's symbol

Returns:

external location

Throws:

InvalidInputException - if an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

addExtLocation

public ExternalLocation addExtLocation(Namespace extParentNamespace,
 String extLabel,
 Address extAddr,
 SourceType sourceType,
 boolean reuseExisting)
                                throws InvalidInputException

Description copied from interface: ExternalManager

Get or create an external location in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtLocation in interface ExternalManager

Parameters:

extParentNamespace - the external namespace

extLabel - the external label or null

extAddr - the external memory address or null

sourceType - the source type of this external library's symbol

reuseExisting - if true, this will return an existing matching external location instead of creating a new one.

Returns:

external location

Throws:

InvalidInputException - if an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

addExtFunction

public ExternalLocation addExtFunction(String extLibraryName,
 String extLabel,
 Address extAddr,
 SourceType sourceType)
                                throws InvalidInputException,
DuplicateNameException

Description copied from interface: ExternalManager

Create an external Function in the external Library namespace libararyName and identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtFunction in interface ExternalManager

Parameters:

extLibraryName - the external library name

extLabel - label within the external program, may be null if extAddr is not null

extAddr - memory address within the external program, may be null

sourceType - the source type of this external library's symbol

Returns:

external location

Throws:

InvalidInputException - if libraryName is invalid or null, or an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

DuplicateNameException - if another non-Library namespace has the same name

addExtFunction

public ExternalLocation addExtFunction(Namespace extParentNamespace,
 String extLabel,
 Address extAddr,
 SourceType sourceType)
                                throws InvalidInputException

Description copied from interface: ExternalManager

Create an external Function in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtFunction in interface ExternalManager

Parameters:

extParentNamespace - the external namespace

extLabel - the external label or null

extAddr - the external memory address or null

sourceType - the source type of this external library's symbol

Returns:

external location

Throws:

InvalidInputException - if an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

addExtFunction

public ExternalLocation addExtFunction(Namespace extNamespace,
 String extLabel,
 Address extAddr,
 SourceType sourceType,
 boolean reuseExisting)
                                throws InvalidInputException

Description copied from interface: ExternalManager

Get or create an external Function in the indicated external parent namespace and identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.

Specified by:

addExtFunction in interface ExternalManager

Parameters:

extNamespace - the external namespace

extLabel - the external label or null

extAddr - the external memory address or null

sourceType - the source type of this external library's symbol

reuseExisting - if true, will return any existing matching location instead of creating a new one. If false, will prefer to create a new one as long as the specified address is not null and not used in an existing location.

Returns:

external location

Throws:

InvalidInputException - if an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

getExternalLocations

public List<ExternalLocation> getExternalLocations(Namespace libScope,
 String extLabel)

Description copied from interface: ExternalManager

Returns a list of External Locations matching the given label name in the given Namespace.

Specified by:

getExternalLocations in interface ExternalManager

Parameters:

libScope - the Namespace to search

extLabel - the name of the labels to search for.

Returns:

a list of External Locations matching the given label name in the given Namespace.

getExternalLocations

public List<ExternalLocation> getExternalLocations(String libraryName,
 String label)

Description copied from interface: ExternalManager

Returns a list of External Locations matching the given label name in the given Library.

Specified by:

getExternalLocations in interface ExternalManager

Parameters:

libraryName - the name of the library

label - the name of the label

Returns:

a list of External Locations matching the given label name in the given Library.

getUniqueExternalLocation

public ExternalLocation getUniqueExternalLocation(Namespace namespace,
 String label)

Description copied from interface: ExternalManager

Returns the unique external location associated with the given namespace and label

Specified by:

getUniqueExternalLocation in interface ExternalManager

Parameters:

namespace - the namespace

label - the label of the external location

Returns:

the unique external location or null

getUniqueExternalLocation

public ExternalLocation getUniqueExternalLocation(String libraryName,
 String label)

Description copied from interface: ExternalManager

Returns the unique external location associated with the given library name and label

Specified by:

getUniqueExternalLocation in interface ExternalManager

Parameters:

libraryName - the library name

label - the label of the external location

Returns:

the unique external location or null

getExternalLocation

public ExternalLocation getExternalLocation(String extName,
 String extLabel)

Description copied from interface: ExternalManager

Get an external location.

Specified by:

getExternalLocation in interface ExternalManager

Parameters:

extName - the name of the library for which to get an external location

extLabel - the name of the external location.

Returns:

first matching external location

getExternalLocation

public ExternalLocation getExternalLocation(Namespace extNamespace,
 String extLabel)

Description copied from interface: ExternalManager

Get an external location.

Specified by:

getExternalLocation in interface ExternalManager

Parameters:

extNamespace - the namespace containing the external label.

extLabel - the name of the external location.

Returns:

first matching external location

getDefaultExternalName

public static String getDefaultExternalName(SymbolDB sym)

Get the default name for an external function or code symbol

Parameters:

sym -

Returns:

default name

getExtLocation

public ExternalLocation getExtLocation(Address externalAddr)

Returns the external location associated with the given external address

Parameters:

externalAddr - the external address.

getExternalLocation

public ExternalLocation getExternalLocation(Symbol symbol)

Description copied from interface: ExternalManager

Returns the external location associated with the given external symbol

Specified by:

getExternalLocation in interface ExternalManager

Parameters:

symbol - the external symbol.

Returns:

the external location or null

removeExternalLocation

public boolean removeExternalLocation(Address externalAddr)

Removes the external location at the given external address

Parameters:

externalAddr - the address at which to remove the external location.

removeExternalLibrary

public boolean removeExternalLibrary(String name)

Description copied from interface: ExternalManager

Removes external name if no associated ExternalLocation's exist

Specified by:

removeExternalLibrary in interface ExternalManager

Parameters:

name - external library name

Returns:

true if removed, false if unable to due to associated locations/references

updateExternalLibraryName

public void updateExternalLibraryName(String oldName,
 String newName,
 SourceType source)
                               throws DuplicateNameException,
InvalidInputException

Update the external program for all references.

Specified by:

updateExternalLibraryName in interface ExternalManager

Parameters:

oldName - old external program name

newName - new external program name

source - the source of this external library: Symbol.DEFAULT, Symbol.ANALYSIS, Symbol.IMPORTED, or Symbol.USER_DEFINED

Throws:

DuplicateNameException

InvalidInputException

addExternalLibraryName

public Library addExternalLibraryName(String name,
 SourceType source)
                               throws DuplicateNameException,
InvalidInputException

Description copied from interface: ExternalManager

Adds a new external library name

Specified by:

addExternalLibraryName in interface ExternalManager

Parameters:

name - the new external library name to add.

source - the source of this external library

Returns:

library external namespace

Throws:

DuplicateNameException - if another non-Library namespace has the same name

InvalidInputException - if libraryName is invalid or null. A library name with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.

contains

public boolean contains(String libraryName)

Description copied from interface: ExternalManager

Determines if the indicated external library name is being managed (exists).

Specified by:

contains in interface ExternalManager

Parameters:

libraryName - the external library name

Returns:

true if the name is defined (whether it has a path or not).

getExternalLibraryNames

public String[] getExternalLibraryNames()

Description copied from interface: ExternalManager

Returns an array of all external names for which locations have been defined.

Specified by:

getExternalLibraryNames in interface ExternalManager

Returns:

array of external names

getExternalLibrary

public Library getExternalLibrary(String name)

Description copied from interface: ExternalManager

Get the Library which corresponds to the specified name

Specified by:

getExternalLibrary in interface ExternalManager

Parameters:

name - name of library

Returns:

library or null if not found

getExternalLibraryPath

public String getExternalLibraryPath(String externalName)

Description copied from interface: ExternalManager

Returns the file pathname associated with an external name. Null is returned if either the external name does not exist or a pathname has not been set.

Specified by:

getExternalLibraryPath in interface ExternalManager

Parameters:

externalName - external name

Returns:

project file pathname or null

setExternalPath

public void setExternalPath(String externalName,
 String externalPath,
 boolean userDefined)
                     throws InvalidInputException

Description copied from interface: ExternalManager

Sets the file pathname associated with an existing external name.

Specified by:

setExternalPath in interface ExternalManager

Parameters:

externalName - the name of the library to associate with a file.

externalPath - the path to the program to be associated with the library name.

userDefined - true if the external path is being specified by the user

Throws:

InvalidInputException

getExternalLocations

public ExternalLocationIterator getExternalLocations(Address memoryAddress)

Description copied from interface: ExternalManager

Get an iterator over all external locations which have been associated to the specified memory address

Specified by:

getExternalLocations in interface ExternalManager

Parameters:

memoryAddress - memory address

Returns:

external location iterator

getExternalLocations

public ExternalLocationIterator getExternalLocations(String externalName)

Description copied from interface: ExternalManager

Get an iterator over all external locations associated with the specified externalName.

Specified by:

getExternalLocations in interface ExternalManager

Parameters:

externalName - the name of the library to get locations for

Returns:

external location iterator

setLanguage

public void setLanguage(LanguageTranslator translator,
 TaskMonitor monitor)
                 throws CancelledException

Throws:

CancelledException