Class GhidraURL

java.lang.Object
ghidra.framework.protocol.ghidra.GhidraURL
public class GhidraURL extends Object
Utility class which provides support for creating Ghidra local project and remote repository URLs. Valid Ghidra URL forms include:
  • ghidra:[ext:]//<host>:<port>/<repository-name>[/<folder-path>]/[<folderItemName>[#ref]]
  • ghidra:/[X:/]<project-path>/<project-name>[?[/<folder-path>]/[<folderItemName>[#ref]]]
  • ghidra:////UNCServer/UNCshare/<project-name>[?[/<folder-path>]/[<folderItemName>[#ref]]]

NOTE: [ext:] corresponds to an optional Ghidra server extension protocol if supported. This requires a corresponding GhidraProtocolHandler extension. Helper methods within this utility are not provided for forming such URLs. A separate GhidraExtURL utility should be established if such a protocol extension is established or used. It is assumed that any such extension utilizing a compliant hierarchical URL which appears as an opaque URI element within the Ghidra URL.

Various system path utilities are also provided in support of local Ghidra project URLs and ProjectLocator.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    MARKER_FILE_EXTENSION
     
    static final String
    PROJECT_DIRECTORY_EXTENSION
     
    static final String
    PROTOCOL
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    checkLocalAbsolutePath(String absolutePath, boolean isDirectory)
    Ensure that absolute path is specified and normalize its format (e.g., Windows path separators are converted to '/').
    static String
    getDecodedReference(URL url)
    Returns Get the URL-decoded reference/fragment from the URL or null.
    static String
    getDisplayString(URL url)
    Generate preferred display string for Ghidra URLs.
    static URL
    getFolderURL(URL ghidraUrl)
    Force the specified URL to specify a folder.
    static URL
    getNormalizedURL(URL url)
    Get a normalized URL which eliminates use of host names and optional URL ref which may prevent direct comparison.
    static String
    getProjectPathname(URL ghidraUrl)
    Get the decoded project content pathname referenced by the specified Ghidra file/folder URL.
    static ProjectLocator
    getProjectStorageLocator(URL localProjectURL)
    Get the project locator which corresponds to the specified local project URL.
    static URL
    getProjectURL(URL ghidraUrl)
    Get Ghidra URL which corresponds to the local-project or repository with any file path or query details removed.
    static String
    getRepositoryName(URL url)
    Get the shared repository name associated with a repository URL or null if not applicable.
    static boolean
    isGhidraURL(String str)
    Determine if the specified string appears to be a possible Ghidra URL (starts with "ghidra:").
    static boolean
    isGhidraURL(URL url)
    Tests if the given url is using the Ghidra protocol.
    static boolean
    isLocalURL(String str)
    Determine if URL string uses a local Ghidra project URL format (e.g., ghidra:/path...).
    static boolean
    isLocalURL(URL url)
    Determine if URL string uses a local Ghidra project URL format (e.g., ghidra:/path...).
    static boolean
    isServerRepositoryURL(URL url)
    Determine if the specified URL is any type of server "repository" URL.
    static boolean
    isServerURL(String str)
    Determine if a URL string corresponds to a remote Ghidra server URL (e.g., ghidra://host..., ghidra:<extension>://host...).
    static boolean
    isServerURL(URL url)
    Determine if the specified URL is any type of supported server Ghidra URL.
    static boolean
    isWindowsOnlyPath(String path)
    Determine if the specified path is only valid on a Windows platform.
    static boolean
    localProjectExists(URL url)
    Determine if the specified URL refers to a local project and it exists.
    static URL
    makeURL(ProjectLocator projectLocator)
    Create a URL which refers to a local Ghidra project's root folder.
    static URL
    makeURL(ProjectLocator projectLocator, String projectFilePath, String ref)
    Create a URL which refers to a Ghidra project with optional project file and ref.
    static URL
    makeURL(String host, int port)
    Create a URL which refers to Ghidra Server (i.e., no specific repository).
    static URL
    makeURL(String host, int port, String repositoryName)
    Create a URL which refers to Ghidra Server named repository and its root folder.
    static URL
    makeURL(String host, int port, String repositoryName, String repositoryPath)
    Create a URL which refers to Ghidra Server repository content.
    static URL
    makeURL(String host, int port, String repositoryName, String repositoryPath, String ref)
    Create a URL which refers to Ghidra Server repository content.
    static URL
    makeURL(String host, int port, String repositoryName, String repositoryFolderPath, String childName, String ref)
    Create a URL which refers to Ghidra Server repository content.
    static URL
    makeURL(String dirPath, String projectName)
    Create a URL which refers to a local Ghidra project's root folder.
    static URL
    makeURL(String projectLocation, String projectName, String projectFilePath, String ref)
    Create a URL which refers to a local Ghidra project with optional project folder/file path and optional reference.
    static URL
    resolve(URL ghidraUrl, String projectFilePath, String ref)
    Create a new URL which is resolved from a base Ghidra project or repository URL to which the specified content folder or file path is added along with the optional reference.
    static URL
    toURL(String projectPathOrURL)
    Create a Ghidra URL from a string form of a Ghidra URL or local project path.

    Methods inherited from class Object

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

  • Field Details

  • Method Details

    • localProjectExists

      public static boolean localProjectExists(URL url)
      Determine if the specified URL refers to a local project and it exists.
      Parameters:
      url - Ghidra URL
      Returns:
      true if specified URL refers to a local project and it exists.

    • isGhidraURL

      public static boolean isGhidraURL(String str)
      Determine if the specified string appears to be a possible Ghidra URL (starts with "ghidra:").
      Parameters:
      str - string to be checked
      Returns:
      true if string is possible Ghidra URL

    • isGhidraURL

      public static boolean isGhidraURL(URL url)
      Tests if the given url is using the Ghidra protocol.
      Parameters:
      url - the url to test
      Returns:
      true if the url is using the Ghidra protocol

    • isLocalURL

      public static boolean isLocalURL(String str)
      Determine if URL string uses a local Ghidra project URL format (e.g., ghidra:/path...). Extensive validation is not performed. This method is intended to differentiate from a server URL only.
      Parameters:
      str - URL string
      Returns:
      true if string appears to be local Ghidra URL, else false

    • isLocalURL

      public static boolean isLocalURL(URL url)
      Determine if URL string uses a local Ghidra project URL format (e.g., ghidra:/path...). Extensive validation is not performed. This method is intended to differentiate from a server URL only.
      Parameters:
      url - URL
      Returns:
      true if specified URL refers to a local Ghidra project (ghidra:/path/projectName...)

    • isServerURL

      public static boolean isServerURL(String str)
      Determine if a URL string corresponds to a remote Ghidra server URL (e.g., ghidra://host..., ghidra:<extension>://host...). Extensive validation is not performed. This method is intended to differentiate between a local and remote Ghidra URL only.
      Parameters:
      str - URL string
      Returns:
      true if string appears to be remote server Ghidra URL, else false

    • isWindowsOnlyPath

      public static boolean isWindowsOnlyPath(String path)
      Determine if the specified path is only valid on a Windows platform. Such paths contain either a drive specification or UNC path (e.g., C:\, /C:/, //server/..., \\server\..). NOTE: This does not check for existence of the specified path.
      Parameters:
      path - file path specification
      Returns:
      true if path is only valid when used on a Windows system.

    • getProjectStorageLocator

      public static ProjectLocator getProjectStorageLocator(URL localProjectURL)
      Get the project locator which corresponds to the specified local project URL. Confirm local project URL with isLocalURL(URL) prior to method use.
      Parameters:
      localProjectURL - local Ghidra project URL
      Returns:
      project locator or null if invalid path specified
      Throws:
      IllegalArgumentException - URL is not a valid local project URL.

    • getDecodedReference

      public static String getDecodedReference(URL url)
      Returns Get the URL-decoded reference/fragment from the URL or null.

      NOTE: The presence of "+" in the original reference fragment is problematic and requires consistent use of this method in conjunction with the URL instantiation methods provided by this utility class.

      Parameters:
      url - Ghidra URL
      Returns:
      Get the URL-decoded reference/fragment from the URL or null

    • getRepositoryName

      public static String getRepositoryName(URL url)
      Get the shared repository name associated with a repository URL or null if not applicable. For Ghidra URL extensions it is assumed that the first path element corresponds to the repository name.
      Parameters:
      url - Ghidra URL for shared project resource
      Returns:
      repository name or null if not applicable to URL

    • isServerRepositoryURL

      public static boolean isServerRepositoryURL(URL url)
      Determine if the specified URL is any type of server "repository" URL. No checking is performed as to the existence of the server or repository.

      NOTE: ghidra protocol extensions are not currently supported (e.g., ghidra:http://...).

      Parameters:
      url - Ghidra URL
      Returns:
      true if specified URL refers to a Ghidra server repository (ghidra://host/repositoryNAME/path...)

    • isServerURL

      public static boolean isServerURL(URL url)
      Determine if the specified URL is any type of supported server Ghidra URL. If a Ghidra server extension URL is specified the corresponding GhidraProtocolHandler extension must be present or false will be returned.
      Parameters:
      url - Ghidra URL
      Returns:
      true if specified URL refers to a Ghidra server repository (e.g., ghidra://host/repositoryNAME/path..., ghidra:<extension>://host/repositoryNAME/path...)

    • checkLocalAbsolutePath

      public static String checkLocalAbsolutePath(String absolutePath, boolean isDirectory)
      Ensure that absolute path is specified and normalize its format (e.g., Windows path separators are converted to '/'). An absolute path may start with a windows drive letter (e.g., c:\a\b, c:/a/b, /c:/a/b) or without (e.g., /a/b) or a UNC path (e.g., //server/share/a/b, \\server\share\a\b).

      For Windows, the lack of a drive letter is not absolute; although, for consistency with Linux we permit this form which on Windows will use the default drive for the process. If path starts with a drive letter (e.g., "c:/") it will have a "/" prepended (e.g., "/c:/", both forms are treated the same by the File class under Windows).

      Path element naming restrictions are imposed based upon NamingUtilities.checkName(String, String) restrictions. These restrictions are imposed to ensure we can easily express the local project path in URL form.

      Parameters:
      absolutePath - path to be checked and possibly modified.
      isDirectory - true if returned path should include a trailing '/'
      Returns:
      path to be used
      Throws:
      IllegalArgumentException - if an invalid path is specified based upon NamingUtilities restrictions.

    • toURL

      public static URL toURL(String projectPathOrURL)
      Create a Ghidra URL from a string form of a Ghidra URL or local project path. This method can consume strings produced by the getDisplayString method.
      Parameters:
      projectPathOrURL - project path (<absolute-directory>/<project-name>) or string form of Ghidra URL.
      Returns:
      local Ghidra project URL
      Throws:
      IllegalArgumentException - invalid path or URL specified

    • resolve

      public static URL resolve(URL ghidraUrl, String projectFilePath, String ref)
      Create a new URL which is resolved from a base Ghidra project or repository URL to which the specified content folder or file path is added along with the optional reference.
      Parameters:
      ghidraUrl - the base Ghidra project or repository URL which will be used as the basis for forming a new Ghidra URL.
      projectFilePath - an absolute folder or file path within the project (e.g., /a/b/c, may be null for root folder). Folder paths should end with a '/' character.
      ref - optional location reference (may be null) which is appended to URL with a '#' delimiter.
      Returns:
      new resolved URL
      Throws:
      IllegalArgumentException - if an invalid Ghidra project or repository URL is specified or an invalid folder/file path is specified.

    • getProjectURL

      public static URL getProjectURL(URL ghidraUrl)
      Get Ghidra URL which corresponds to the local-project or repository with any file path or query details removed.
      Parameters:
      ghidraUrl - ghidra file/folder URL (server-only URL not permitted)
      Returns:
      local-project or repository URL
      Throws:
      IllegalArgumentException - if URL does not specify the ghidra protocol or does not properly identify a remote repository or local project.

    • getProjectPathname

      public static String getProjectPathname(URL ghidraUrl)
      Get the decoded project content pathname referenced by the specified Ghidra file/folder URL. If path is missing root folder is returned.

      NOTE: This project content pathname should not be confused with a local project storage path associated with a ProjectLocator or local project Ghidra URL.

      Parameters:
      ghidraUrl - Ghidra local or remote file/folder URL (server-only URL not permitted)
      Returns:
      pathname of file or folder

    • getFolderURL

      public static URL getFolderURL(URL ghidraUrl)
      Force the specified URL to specify a folder. This may be necessary when only folders are supported since Ghidra permits both a folder and file to have the same name within its parent folder. This method simply ensures that the URL path ends with a / character if needed.
      Parameters:
      ghidraUrl - Ghidra URL
      Returns:
      ghidra folder URL
      Throws:
      IllegalArgumentException - if specified URL is neither a valid remote server URL or local project URL.

    • getNormalizedURL

      public static URL getNormalizedURL(URL url)
      Get a normalized URL which eliminates use of host names and optional URL ref which may prevent direct comparison.
      Parameters:
      url - Ghidra URL
      Returns:
      normalized url

    • getDisplayString

      public static String getDisplayString(URL url)
      Generate preferred display string for Ghidra URLs.

      NOTE: The display-friendly string returned is intended for display use only and should not be parsed back into a URL.

      Parameters:
      url - Ghidra URL
      Returns:
      formatted URL display string
      See Also:

    • makeURL

      public static URL makeURL(String dirPath, String projectName)
      Create a URL which refers to a local Ghidra project's root folder.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain the referenced root DomainFolder.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      dirPath - absolute path of project location directory
      projectName - name of project
      Returns:
      local Ghidra project URL

    • makeURL

      public static URL makeURL(ProjectLocator projectLocator)
      Create a URL which refers to a local Ghidra project's root folder.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain the referenced root DomainFolder.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      projectLocator - absolute project location
      Returns:
      local Ghidra project root folder URL
      Throws:
      IllegalArgumentException - if projectLocator does not have an absolute location

    • makeURL

      public static URL makeURL(String projectLocation, String projectName, String projectFilePath, String ref)
      Create a URL which refers to a local Ghidra project with optional project folder/file path and optional reference.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain either the referenced DomainFolder or DomainFile.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      projectLocation - absolute path of project location directory
      projectName - name of project
      projectFilePath - an absolute folder or file path within the project (e.g., /a/b/c, may be null for root folder). Folder paths should end with a '/' character.
      ref - optional location reference (may be null) which is appended to URL with a '#' delimiter.
      Returns:
      local Ghidra project URL
      Throws:
      IllegalArgumentException - if an absolute projectLocation path is not specified

    • makeURL

      public static URL makeURL(ProjectLocator projectLocator, String projectFilePath, String ref)
      Create a URL which refers to a Ghidra project with optional project file and ref. If project locator corresponds to a transient project a server URL form will be returned.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain either the referenced DomainFolder or DomainFile.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      projectLocator - project locator (local or transient)
      projectFilePath - file path (e.g., /a/b/c, may be null). Folder paths should end with a '/' character.
      ref - location reference (may be null)
      Returns:
      local Ghidra project URL
      Throws:
      IllegalArgumentException - if invalid projectFilePath specified or if URL instantiation fails.

    • makeURL

      public static URL makeURL(String host, int port, String repositoryName, String repositoryPath)
      Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain either the referenced DomainFolder or DomainFile.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      host - server host name/address
      port - optional server port (a value <= 0 refers to the default port)
      repositoryName - repository name
      repositoryPath - absolute folder or file path within repository (may be null for root folder). Folder paths should end with a '/' character.
      Returns:
      Ghidra Server repository content URL

    • makeURL

      public static URL makeURL(String host, int port, String repositoryName, String repositoryPath, String ref)
      Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain either the referenced DomainFolder or DomainFile.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      host - server host name/address
      port - optional server port (a value <= 0 refers to the default port)
      repositoryName - repository name (required)
      repositoryPath - absolute folder or file path within repository (may be null). Folder paths should end with a '/' character.
      ref - reference (may be null)
      Returns:
      Ghidra Server repository content URL
      Throws:
      IllegalArgumentException - if arguments are specified which cannot be encoded into URL

    • makeURL

      public static URL makeURL(String host, int port, String repositoryName, String repositoryFolderPath, String childName, String ref)
      Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder. See makeURL(String, int, String, String, String) for a slightly simpler form when working with just a project folder or file pathname.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain either the referenced DomainFolder or DomainFile.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder or file object.

      Parameters:
      host - server host name/address
      port - optional server port (a value <= 0 refers to the default port)
      repositoryName - repository name (required)
      repositoryFolderPath - absolute folder path within repository (required).
      childName - name of a file or folder contained within the specified repositoryFolderPath (required)
      ref - optional URL ref or null Folder paths should end with a '/' character.
      Returns:
      Ghidra Server repository content URL
      Throws:
      IllegalArgumentException - if required arguments are blank or invalid

    • makeURL

      public static URL makeURL(String host, int port, String repositoryName)
      Create a URL which refers to Ghidra Server named repository and its root folder.

      Upon a successful URL connection, a GhidraURLWrappedContent content object will be provided from which GhidraURLWrappedContent.getContent(Object) may be invoked to obtain the repository's root DomainFolder.

      NOTE: A proper GhidraURLWrappedContent.release(Object, Object) is mandatory after retrieving the wrapped content folder.

      Parameters:
      host - server host name/address
      port - optional server port (a value <= 0 refers to the default port)
      repositoryName - repository name (required)
      Returns:
      Ghidra Server repository URL

    • makeURL

      public static URL makeURL(String host, int port)
      Create a URL which refers to Ghidra Server (i.e., no specific repository). Upon successful connection, the returned content type will be a RepositoryServerAdapter instance.
      Parameters:
      host - server host name/address
      port - optional server port (a value <= 0 refers to the default port)
      Returns:
      Ghidra Server URL