Package ghidra.framework.plugintool.dialog

Class ExtensionUtils

java.lang.Object

ghidra.framework.plugintool.dialog.ExtensionUtils

public class ExtensionUtils
extends java.lang.Object

Utility class for managing Ghidra Extensions.

Extensions are defined as any archive or folder that contains an extension.properties file. This properties file can contain the following attributes:

• name (required)
• description
• author
• createdOn (format: mm/dd/yyyy)

Extensions may be installed/uninstalled by users at runtime, using the ExtensionTableProvider. Installation consists of unzipping the extension archive to an installation folder, currently Ghidra/Extensions. To uninstall, the unpacked folder is simply removed.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	PROPERTIES_FILE_NAME
static java.lang.String	PROPERTIES_FILE_NAME_UNINSTALLED

Constructor Summary

Constructors

Constructor	Description
ExtensionUtils()

Method Summary

Modifier and Type	Method	Description
static void	cleanupUninstalledExtensions()	Attempts to delete any extension directories that do not contain a Module.manifest file.
static ExtensionDetails	createExtensionDetailsFromProperties(java.util.Properties props)	Extracts properties from a Java Properties file to create an ExtensionDetails object.
static ExtensionDetails	createExtensionDetailsFromPropertyFile(ResourceFile resourceFile)	Extracts information from a Java Properties file to create an ExtensionDetails object.
static ExtensionDetails	createExtensionDetailsFromPropertyFile(java.io.File file)	Extracts information from a Java Properties file to create an ExtensionDetails object.
static java.util.List<ResourceFile>	findExtensionPropertyFiles(ResourceFile sourceFile, boolean includeUninstalled)	Returns a list of files representing all the extension.properties files found under a given directory.
static void	findFilesWithName(java.io.File root, java.lang.String fileName, java.util.List<java.io.File> foundFiles)
static java.util.Set<ExtensionDetails>	getArchivedExtensions()	Returns all archived extensions.
static java.util.Set<ExtensionDetails>	getExtensions()	Returns a set of all extensions known to Ghidra, represented by ExtensionDetails objects.
static java.util.Set<ExtensionDetails>	getExtensionsInstalledSinceLastToolLaunch(PluginTool tool)	Finds any extensions that have been installed since the last time a given tool was launched.
static java.util.Set<ExtensionDetails>	getInstalledExtensions(boolean includeUninstalled)	Returns all installed extensions.
static java.util.Properties	getPropertiesFromArchive(java.io.File file)	Given a zip file, returns the Properties defined in the embedded extension.properties file.
static boolean	install(ResourceFile rFile)	Installs the given extension file.
static boolean	install(ExtensionDetails extension, boolean overwrite)	Installs the given extension.
static boolean	isExtension(ResourceFile rFile)	Returns true if the given file or directory is a valid ghidra extension.
static boolean	isInstalled(java.lang.String extensionName)	Returns true if an extension with the given name exists in the install folder.
static boolean	isZip(java.io.File file)	Returns true if the given file is a valid .zip archive.
static boolean	removeStateFiles(ExtensionDetails extension)	Recursively searches a given directory for any module manifest and extension properties files that are in an installed state and converts them to an uninstalled state.
static boolean	restoreStateFiles(java.io.File rootDir)	Recursively searches a given directory for any module manifest and extension properties files that are in an uninstalled state and restores them.
static boolean	uninstall(ExtensionDetails extension)	Uninstalls a given extension.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTIES_FILE_NAME

public static java.lang.String PROPERTIES_FILE_NAME

PROPERTIES_FILE_NAME_UNINSTALLED

public static java.lang.String PROPERTIES_FILE_NAME_UNINSTALLED

Constructor Detail

ExtensionUtils

public ExtensionUtils()

Method Detail

getExtensions

public static java.util.Set<ExtensionDetails> getExtensions()
                                                     throws ExtensionException

Returns a set of all extensions known to Ghidra, represented by ExtensionDetails objects. This will include all installed AND archived extensions.

Note that this method will only look in the known extension folder locations:

• ApplicationLayout.getExtensionArchiveDir()
• ApplicationLayout.getExtensionInstallationDirs()

If users install extensions from other locations, the installed version of the extension will be known, but the source archive location will not be retained.

Returns:

list of unique extensions

Throws:

ExtensionException - if extensions cannot be retrieved

getInstalledExtensions

public static java.util.Set<ExtensionDetails> getInstalledExtensions(boolean includeUninstalled)
                                                              throws ExtensionException

Returns all installed extensions. These are all the extensions found in ApplicationLayout.getExtensionInstallationDirs().

Parameters:

includeUninstalled - if true, include extensions that have been marked for removal

Returns:

set of installed extensions

Throws:

ExtensionException - if the extension details cannot be retrieved

getArchivedExtensions

public static java.util.Set<ExtensionDetails> getArchivedExtensions()
                                                             throws ExtensionException

Returns all archived extensions. These are all the extensions found in ApplicationLayout.getExtensionArchiveDir().

Returns:

set of archived extensions

Throws:

ExtensionException - if the extension details cannot be retrieved

isInstalled

public static boolean isInstalled(java.lang.String extensionName)

Returns true if an extension with the given name exists in the install folder.

Parameters:

extensionName - the name of the extension

Returns:

true if installed

install

public static boolean install(ResourceFile rFile)

Installs the given extension file. This can be either an archive (zip) or a directory that contains an extension.properties file.

Parameters:

rFile - the extension to install

Returns:

true if the extension was successfully installed

install

public static boolean install(ExtensionDetails extension,
                              boolean overwrite)

Installs the given extension.

Parameters:

extension - the extension to install

overwrite - if true, any existing extension will be overwritten

Returns:

true if the install was successful

uninstall

public static boolean uninstall(ExtensionDetails extension)

Uninstalls a given extension.

Parameters:

extension - the extension to uninstall

Returns:

true if successfully uninstalled

isExtension

public static boolean isExtension(ResourceFile rFile)
                           throws ExtensionException

Returns true if the given file or directory is a valid ghidra extension.

Note: This means that the zip or directory contains an extension.properties file.

Parameters:

rFile - the resource zip or directory to inspect

Returns:

true if the given file represents a valid extension

Throws:

ExtensionException - if there's an error processing a zip file

isZip

public static boolean isZip(java.io.File file)
                     throws ExtensionException

Returns true if the given file is a valid .zip archive.

Parameters:

file - the file to test

Returns:

true if file is a valid zip

Throws:

ExtensionException - if there's an error reading the zip file

findExtensionPropertyFiles

public static java.util.List<ResourceFile> findExtensionPropertyFiles(ResourceFile sourceFile,
                                                                      boolean includeUninstalled)

Returns a list of files representing all the extension.properties files found under a given directory. This will ONLY search the given directory and its immediate children. The conops are as follows:

• If sourceFile is a directory and it contains an extension.properties file, then that file is returned
• If sourceFile does not contain an extension.properties file, then any immediate directories are searched (ignoring Skeleton directory)

Note: This will NOT search zip files. If you have a zip, call getPropertiesFromArchive(File) instead.

Parameters:

sourceFile - the directory to inspect

includeUninstalled - if true, include extensions that have been marked for removal

Returns:

list of extension.properties files

removeStateFiles

public static boolean removeStateFiles(ExtensionDetails extension)

Recursively searches a given directory for any module manifest and extension properties files that are in an installed state and converts them to an uninstalled state. Specifically, the following will be renamed:

• Module.manifest to Module.manifest.uninstalled
• extension.properties = extension.properties.uninstalled

Parameters:

extension - the extension to modify

Returns:

false if any renames fail

restoreStateFiles

public static boolean restoreStateFiles(java.io.File rootDir)

Recursively searches a given directory for any module manifest and extension properties files that are in an uninstalled state and restores them. Specifically, the following will be renamed:

• Module.manifest.uninstalled to Module.manifest
• extension.properties.uninstalled = extension.properties

Parameters:

rootDir - the directory to search

Returns:

false if any renames fail

findFilesWithName

public static void findFilesWithName(java.io.File root,
                                     java.lang.String fileName,
                                     java.util.List<java.io.File> foundFiles)

Parameters:

root - the starting directory to search recursively

fileName - the file name search for

foundFiles - list of all matching files

getPropertiesFromArchive

public static java.util.Properties getPropertiesFromArchive(java.io.File file)
                                                     throws ExtensionException

Given a zip file, returns the Properties defined in the embedded extension.properties file.

Parameters:

file - the extension archive file

Returns:

the properties file, or null if doesn't exist

Throws:

ExtensionException - if there's a problem unpacking the zip file

createExtensionDetailsFromPropertyFile

public static ExtensionDetails createExtensionDetailsFromPropertyFile(java.io.File file)

Extracts information from a Java Properties file to create an ExtensionDetails object.

Parameters:

file - the file to parse

Returns:

a new extension details object

getExtensionsInstalledSinceLastToolLaunch

public static java.util.Set<ExtensionDetails> getExtensionsInstalledSinceLastToolLaunch(PluginTool tool)

Finds any extensions that have been installed since the last time a given tool was launched.

Parameters:

tool - the tool to check

Returns:

set of new extensions

createExtensionDetailsFromPropertyFile

public static ExtensionDetails createExtensionDetailsFromPropertyFile(ResourceFile resourceFile)

Extracts information from a Java Properties file to create an ExtensionDetails object.

Parameters:

resourceFile - the resource file file to parse

Returns:

a new extension details object

cleanupUninstalledExtensions

public static void cleanupUninstalledExtensions()

Attempts to delete any extension directories that do not contain a Module.manifest file. This indicates that the extension was slated to be uninstalled by the user.

See Also:

uninstall(ghidra.framework.plugintool.dialog.ExtensionDetails)

createExtensionDetailsFromProperties

public static ExtensionDetails createExtensionDetailsFromProperties(java.util.Properties props)

Extracts properties from a Java Properties file to create an ExtensionDetails object.

Parameters:

props - the java properties object

Returns:

a new extension details object