Package ghidra.plugin.importer

Class ProgramMappingService

  • public class ProgramMappingService
extends java.lang.Object
    Provides a best-effort[1] mapping / association between Ghidra Program/DomainFile objects and GFilesystem files (identified by their FSRL).

    As there is no current feature that allows you to quickly query the metadata of Programs/DomainFile objects in the current project, finding a Program by its MD5 or by a original source location string is not easily possible.

    Threadsafe.

    The current implementation searches current open Ghidra Programs and maintains a short-lived, in-memory only mapping of FSRL->DomainFile paths (manually updated by users of the ProgramMappingService when they do an import or other operation that creates a Ghidra DomainFile by calling createAssociation(FSRL, DomainFile) and friends.)

    [1] - best-effort (adverb): meaning a dirty hack.

    • Field Detail

      • PROGRAM_METADATA_MD5

        public static final java.lang.String PROGRAM_METADATA_MD5
        See Also:
        Constant Field Values

      • PROGRAM_SOURCE_FSRL

        public static final java.lang.String PROGRAM_SOURCE_FSRL
        See Also:
        Constant Field Values

    • Method Detail

      • clear

        public static void clear()
        Clears ProgramMappingService data.

        This should be done whenever the project is opened/closed.

      • isFileOpen

        public static boolean isFileOpen​(FSRL fsrl)
        Returns true if there is a current open Ghidra Program that has metadata that links it to the specified FSRL.

        (ie. an open program has a MD5 or FSRL metadata value that matches the fsrl param.)

        Parameters:
        fsrl - FSRL to search for in open program info.
        Returns:
        boolean true if found.

      • isFileImportedIntoProject

        public static boolean isFileImportedIntoProject​(FSRL fsrl)
        Returns true if the specified FSRL has a matched Ghidra DomainFile in the current project.

        Parameters:
        fsrl - FSRL to search for
        Returns:
        boolean true if file exists in project.

      • getCachedDomainFileFor

        public static DomainFile getCachedDomainFileFor​(FSRL fsrl)
        Returns a reference to a DomainFile in the current Project that matches the specified FSRL.

        This method only consults an internal fsrl-to-DomainFile mapping that is short-lived and not persisted.

        Parameters:
        fsrl - FSRL to search for
        Returns:
        DomainFile that was previously associated via createAssociation(FSRL, DomainFile) and friends.

      • createAssociation

        public static void createAssociation​(FSRL fsrl,
                                     Program program)
        Creates a short-lived association between a FSRL and an open Program.

        Parameters:
        fsrl - FSRL of where the Program was imported from.
        program - Program to associate to.

      • createAssociation

        public static void createAssociation​(FSRL fsrl,
                                     DomainFile domainFile)
        Creates a short-lived association between a FSRL and a DomainFile.
        Parameters:
        fsrl - FSRL of where the DomainFile was imported from.
        domainFile - DomainFile to associate with

      • createAutoAssocation

        public static void createAutoAssocation​(Program program)
        Attempts to create an association between the specified open program and any FSRL metadata found in the Programs properties.

        Used by event handlers that get notified about a Program being opened to opportunistically link that program to its source FSRL if the metadata is present.

        Parameters:
        program - Program to rummage around in its metadata looking for FSRL info.

      • findMatchingProgramOpenIfNeeded

        public static Program findMatchingProgramOpenIfNeeded​(FSRL fsrl,
                                                      java.lang.Object consumer,
                                                      ProgramManager programManager,
                                                      int openState)
        Returns an open Program instance that matches the specified FSRL, either from the set of currently open programs, or by requesting the specified ProgramManager to open a DomainFile that was found to match this GFile.

        Parameters:
        fsrl - FSRL of program original location.
        consumer - Object that will be used to pin the matching Program open. Caller must release the consumer when done.
        programManager - ProgramManager that will be used to open DomainFiles if necessary.
        openState - one of ProgramManager.OPEN_VISIBLE, ProgramManager.OPEN_HIDDEN, ProgramManager.OPEN_VISIBLE
        Returns:
        Program which was imported from the specified FSRL, or null if not found.

      • findMatchingProgramOpenIfNeeded

        public static Program findMatchingProgramOpenIfNeeded​(FSRL fsrl,
                                                      DomainFile domainFile,
                                                      java.lang.Object consumer,
                                                      ProgramManager programManager,
                                                      int openState)
        Returns an open Program instance that matches the specified FSRL, either from the set of currently open programs, or by requesting the specified ProgramManager to open a DomainFile that was found to match this GFile.

        Parameters:
        fsrl - FSRL of program original location.
        domainFile - optional DomainFile that corresponds to the FSRL param.
        consumer - Object that will be used to pin the matching Program open. Caller must release the consumer when done.
        programManager - ProgramManager that will be used to open DomainFiles if necessary.
        openState - one of ProgramManager.OPEN_VISIBLE, ProgramManager.OPEN_HIDDEN, ProgramManager.OPEN_VISIBLE
        Returns:
        Program which was imported from the specified FSRL, or null if not found.

      • findMatchingOpenProgram

        public static Program findMatchingOpenProgram​(FSRL fsrl,
                                              java.lang.Object consumer)
        Returns a currently open Ghidra Program that has metadata that links it to the specified file parameter.

        (ie. an open program has a MD5 or FSRL metadata value that matches the file)

        See also isFileOpen(FSRL).

        Parameters:
        fsrl - FSRL to use when inspecting each open Program's metadata.
        consumer - Object that will be used to pin the matching Program open. Caller must release the consumer when done.
        Returns:
        Already open Program that has matching metadata, or null if not found.

      • searchProjectForMatchingFiles

        public static java.util.Map<FSRL,​DomainFile> searchProjectForMatchingFiles​(java.util.List<FSRL> fsrls,
                                                                                 TaskMonitor monitor)
        Recursively searches the current active Project for DomainFiles that have metadata that matches a FSRL in the specified list.

        Warning, this operation is expensive and should only be done in a Task thread.

        Parameters:
        fsrls - List of FSRL to match against the metadata of each DomainFile in Project.
        monitor - TaskMonitor to watch for cancel and update with progress.
        Returns:
        Map of FSRLs to DomainFiles of the found files, never null.