Package ghidra.app.services

Interface ProgramManager

All Known Implementing Classes:
ProgramMergeManagerPlugin
public interface ProgramManager
Service for managing programs. Multiple programs may be open in a tool, but only one is active at any given time.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    OPEN_CURRENT
    Program will be open as the currently active program within the tool.
    static final int
    OPEN_HIDDEN
    Program will be open in a Hidden state if not already open.
    static final int
    OPEN_VISIBLE
    Program will be open within the tool but no change will be made to the currently active program.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    closeAllPrograms(boolean ignoreChanges)
    Closes all open programs in this tool.
    boolean
    closeOtherPrograms(boolean ignoreChanges)
    Closes all open programs in this tool except the current program.
    boolean
    closeProgram()
    Closes the currently active program
    boolean
    closeProgram(Program program, boolean ignoreChanges)
    Closes the given program with the option of saving any changes.
    Program[]
    getAllOpenPrograms()
    Returns a list of all open program.
    Program
    getCurrentProgram()
    Return the program that is currently active.
    Program
    getProgram(Address addr)
    Returns the first program in the list of open programs that contains the given address.
    boolean
    isVisible(Program program)
    Returns true if the specified program is open and considered visible to the user.
    Program
    openCachedProgram(DomainFile domainFile, Object consumer)
    Opens a program or retrieves it from a cache.
    Program
    openCachedProgram(URL ghidraURL, Object consumer)
    Opens a program or retrieves it from a cache.
    Program
    openProgram(DomainFile domainFile)
    Open the program for the given domainFile.
    Program
    openProgram(DomainFile df, int version)
    Opens the specified version of the program represented by the given DomainFile.
    Program
    openProgram(DomainFile domainFile, int version, int state)
    Open the program for the given domainFile
    void
    openProgram(Program program)
    Opens the program to the tool.
    void
    openProgram(Program program, int state)
    Open the specified program in the tool.
    Program
    openProgram(URL ghidraURL, int state)
    Open the program corresponding to the given url.
    void
    releaseProgram(Program program, Object persistentOwner)
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method is no longer used by the system
    void
    saveProgram()
    Saves the current program, possibly prompting the user for a new name.
    void
    saveProgram(Program program)
    Saves the specified program, possibly prompting the user for a new name.
    void
    saveProgramAs()
    Prompts the user to save the current program to a selected file.
    void
    saveProgramAs(Program program)
    Prompts the user to save the specified program to a selected file.
    void
    setCurrentProgram(Program p)
    Sets the given program to be the current active program in the tool.
    boolean
    setPersistentOwner(Program program, Object owner)
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method is no longer used by the system

  • Field Details

    • OPEN_HIDDEN

      static final int OPEN_HIDDEN
      Program will be open in a Hidden state if not already open. This mode is generally used in conjunction with a persistent program owner.
      See Also:

    • OPEN_CURRENT

      static final int OPEN_CURRENT
      Program will be open as the currently active program within the tool.
      See Also:

    • OPEN_VISIBLE

      static final int OPEN_VISIBLE
      Program will be open within the tool but no change will be made to the currently active program. If this is the only program open, it will become the currently active program.
      See Also:

  • Method Details

    • getCurrentProgram

      Program getCurrentProgram()
      Return the program that is currently active.
      Returns:
      may return null if no program is open

    • isVisible

      boolean isVisible(Program program)
      Returns true if the specified program is open and considered visible to the user.
      Parameters:
      program - the program
      Returns:
      true if the specified program is open and considered visible to the user

    • closeProgram

      boolean closeProgram()
      Closes the currently active program
      Returns:
      true if the close is successful. false if the close fails or if there is no program currently active.

    • openProgram

      Program openProgram(URL ghidraURL, int state)
      Open the program corresponding to the given url.
      Parameters:
      ghidraURL - valid server-based program URL
      state - initial open state (OPEN_HIDDEN, OPEN_CURRENT, OPEN_VISIBLE). The visibility states will be ignored if the program is already open.
      Returns:
      the opened program or null if the user canceled the "open" or an error occurred
      See Also:

    • openProgram

      Program openProgram(DomainFile domainFile)
      Open the program for the given domainFile. Once open it will become the active program.
      Parameters:
      domainFile - domain file that has the program
      Returns:
      the opened program or null if the user canceled the "open" or an error occurred

    • openCachedProgram

      Program openCachedProgram(DomainFile domainFile, Object consumer)
      Opens a program or retrieves it from a cache. If the program is in the cache, the consumer will be added the program before returning it. Otherwise, the program will be opened with the consumer. In addition, opening or accessing a cached program, will guarantee that it will remain open for period of time, even if the caller of this method releases it from the consumer that was passed in. If the program isn't accessed again, it will be eventually be released from the cache. If the program is still in use when the timer expires, the program will remain in the cache with a new full expiration time. Calling this method does not open the program in the tool.
      Parameters:
      domainFile - the DomainFile from which to open a program.
      consumer - the consumer that is using the program. The caller is responsible for releasing (See DomainObject.release(Object)) the consumer when done with the program.
      Returns:
      the program for the given domainFile or null if unable to open the program

    • openCachedProgram

      Program openCachedProgram(URL ghidraURL, Object consumer)
      Opens a program or retrieves it from a cache. If the program is in the cache, the consumer will be added the program before returning it. Otherwise, the program will be opened with the consumer. In addition, opening or accessing a cached program, will guarantee that it will remain open for period of time, even if the caller of this method releases it from the consumer that was passed in. If the program isn't accessed again, it will be eventually be released from the cache. If the program is still in use when the timer expires, the program will remain in the cache with a new full expiration time. Calling this method does not open the program in the tool.
      Parameters:
      ghidraURL - the ghidra URL from which to open a program.
      consumer - the consumer that is using the program. The caller is responsible for releasing (See DomainObject.release(Object)) the consumer when done with the program.
      Returns:
      the program for the given URL or null if unable to open the program

    • openProgram

      Program openProgram(DomainFile df, int version)
      Opens the specified version of the program represented by the given DomainFile. This method should be used for shared DomainFiles. The newly opened file will be made the active program.
      Parameters:
      df - the DomainFile to open
      version - the version of the Program to open
      Returns:
      the opened program or null if the user canceled the "open" or an error occurred

    • openProgram

      Program openProgram(DomainFile domainFile, int version, int state)
      Open the program for the given domainFile
      Parameters:
      domainFile - domain file that has the program
      version - the version of the Program to open. Specify DomainFile.DEFAULT_VERSION for file update mode.
      state - initial open state (OPEN_HIDDEN, OPEN_CURRENT, OPEN_VISIBLE). The visibility states will be ignored if the program is already open.
      Returns:
      the opened program or null if the user canceled the "open" or an error occurred

    • openProgram

      void openProgram(Program program)
      Opens the program to the tool. In this case the program is already open, but this tool may not have it registered as open. The program is made the active program.
      Parameters:
      program - the program to register as open with the tool.

    • openProgram

      void openProgram(Program program, int state)
      Open the specified program in the tool.
      Parameters:
      program - the program
      state - initial open state (OPEN_HIDDEN, OPEN_CURRENT, OPEN_VISIBLE). The visibility states will be ignored if the program is already open.

    • saveProgram

      void saveProgram()
      Saves the current program, possibly prompting the user for a new name.

    • saveProgram

      void saveProgram(Program program)
      Saves the specified program, possibly prompting the user for a new name.
      Parameters:
      program - the program

    • saveProgramAs

      void saveProgramAs()
      Prompts the user to save the current program to a selected file.

    • saveProgramAs

      void saveProgramAs(Program program)
      Prompts the user to save the specified program to a selected file.
      Parameters:
      program - the program

    • setPersistentOwner

      @Deprecated(forRemoval=true, since="10.2") boolean setPersistentOwner(Program program, Object owner)
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method is no longer used by the system
      Establish a persistent owner on an open program. This will cause the program manager to imply make a program hidden if it is closed.
      Parameters:
      program - the program
      owner - the owner
      Returns:
      true if program is open and another object is not already the owner, or the specified owner is already the owner.
      See Also:

    • releaseProgram

      @Deprecated(forRemoval=true, since="10.2") void releaseProgram(Program program, Object persistentOwner)
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method is no longer used by the system
      Release the persistent ownership of a program.

      The program will automatically be closed if it is hidden or was marked as temporary. If any of these closures corresponds to a program with changes the user will be given an opportunity to save or keep the program open.

      If persistentOwner is not the correct owner, the method will have no affect.

      Parameters:
      program - the program
      persistentOwner - the owner defined by setPersistentOwner(Program, Object)

    • closeProgram

      boolean closeProgram(Program program, boolean ignoreChanges)
      Closes the given program with the option of saving any changes. The exact behavior of this method depends on several factors. First of all, if any other tool has this program open, then the program is closed for this tool only and the user is not prompted to save the program regardless of the ignoreChanges flag. Otherwise, if ignoreChanges is false and changes have been made, the user is prompted to save the program.
      Parameters:
      program - the program to close.
      ignoreChanges - if true, the program is closed without saving any changes.
      Returns:
      true if the program was closed. Returns false if the user canceled the close while being prompted to save. Also returns false if the program passed in as a parameter is null.

    • closeOtherPrograms

      boolean closeOtherPrograms(boolean ignoreChanges)
      Closes all open programs in this tool except the current program. If this tool is the only tool with a program open and that program has changes, then the user will be prompted to close each such file. (Providing the ignoreChanges flag is false)
      Parameters:
      ignoreChanges - if true, the programs will be closed without saving changes.
      Returns:
      true if all other programs were closed. Returns false if the user canceled the close while being prompted to save.

    • closeAllPrograms

      boolean closeAllPrograms(boolean ignoreChanges)
      Closes all open programs in this tool. If this tool is the only tool with a program open and that program has changes, then the user will be prompted to close each such file. (Providing the ignoreChanges flag is false)
      Parameters:
      ignoreChanges - if true, the programs will be closed without saving changes.
      Returns:
      true if all programs were closed. Returns false if the user canceled the close while being prompted to save.

    • setCurrentProgram

      void setCurrentProgram(Program p)
      Sets the given program to be the current active program in the tool.
      Parameters:
      p - the program to make active.

    • getProgram

      Program getProgram(Address addr)
      Returns the first program in the list of open programs that contains the given address. Programs are searched in the order they were opened within a given priority. Program are initially opened with the PRIORITY_NORMAL priority, but can be set to have PRIORITY_HIGH or PRIORITY_LOW.
      Parameters:
      addr - the address for which to search.
      Returns:
      the first program that can be found to contain the given address.

    • getAllOpenPrograms

      Program[] getAllOpenPrograms()
      Returns a list of all open program.
      Returns:
      the programs