Package ghidra.plugin.importer

Class ProgramMappingService

java.lang.Object
ghidra.plugin.importer.ProgramMappingService
public class ProgramMappingService extends 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 Details

  • Method Details

    • 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, 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, 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, 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 Map<FSRL,DomainFile> searchProjectForMatchingFiles(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.