Package ghidra.formats.gfilesystem

Class FileSystemService

  • public class FileSystemService
extends java.lang.Object
    Provides methods for dealing with GFilesystem files and filesystems.

    Most methods take FSRL references to files as a way to decouple dependencies and reduce forced filesystem instantiation.

    (ie. a GFile instance is only valid if its GFileSystem is open, which means that its parent probably also has to be open, recursively, etc, whereas a FSRL is always valid and does not force the instantiation of parent objects)

    Filesystems should be used via filesystem ref handles that ensure the filesystem is pinned in memory and won't be close()ed while you are using it.

    If you are working with GFile instances, you should have a fs ref that you are using to pin the filesystem.

    Thread-safe.

    TODO list: Refactor fileInfo -> needs dialog to show properties Refactor GFile.getInfo() to return Map<> instead of String. Persistant filesystem - when reopen tool, filesystems should auto-reopen Unify GhidraFileChooser with GFileSystem add "Mounted Filesystems" button to show currently opened GFilesystems? Dockable filesystem browser in FrontEnd Reorg filesystem browser right-click popup menu to be more Eclipse action-like Show In -> Project tree Tool [CodeBrowser name] Import Open With -> Text Viewer Image Viewer Export -> To Project dir To Home dir To Dir To Eclipse Project Decompiled source ProgramMappingService - more robust, precache when open project. Make BatchImportDialog modeless, drag-and-drop to src list Testing: More format tests Large test binary support

    • Constructor Detail

      • FileSystemService

        public FileSystemService()
        Creates a FilesystemService instance, using the Application's default value for user cache directory as the cache directory.

      • FileSystemService

        public FileSystemService​(java.io.File fscacheDir)
        Creates a FilesystemService instance, using the supplied directory as its file caching root directory.
        Parameters:
        fscacheDir - Root dir to use to store files placed into cache.

    • Method Detail

      • clear

        public void clear()
        Forcefully closes all open filesystems and clears caches.

      • closeUnusedFileSystems

        public void closeUnusedFileSystems()
        Close unused filesystems.

      • getLocalFS

        public GFileSystem getLocalFS()
        Returns a direct reference to a filesystem that represents the local filesystem.
        Returns:
        GFileSystem that represents the local filesystem.

      • isFilesystemMountedAt

        public boolean isFilesystemMountedAt​(FSRL fsrl)
        Returns true of there is a filesystem mounted at the requested FSRL location.
        Parameters:
        fsrl - FSRL container to query for mounted filesystem
        Returns:
        boolean true if filesystem mounted at location.

      • getFilesystem

        public FileSystemRef getFilesystem​(FSRLRoot fsFSRL,
                                   TaskMonitor monitor)
                            throws java.io.IOException,
                                   CancelledException
        Returns a filesystem instance for the requested FSRLRoot, either from an already loaded instance in the global fscache, or by instantiating the requested filesystem from its container file (in a possibly recursive manner, depending on the depth of the FSLR)

        Never returns NULL, instead throws IOException if there is a problem.

        The caller is responsible for releasing the FileSystemRef.

        Parameters:
        fsFSRL - FSRLRoot of file system you want a reference to.
        monitor - TaskMonitor to allow the user to cancel.
        Returns:
        a new FileSystemRef that the caller is responsible for closing when no longer needed, never null.
        Throws:
        java.io.IOException - if there was an io problem.
        CancelledException - if the user cancels.

      • addFileToCache

        public FileCacheEntry addFileToCache​(GFile file,
                                     java.io.InputStream is,
                                     TaskMonitor monitor)
                              throws java.io.IOException,
                                     CancelledException
        Adds a file's stream's contents to the file cache, returning its MD5 hash.
        Parameters:
        file - GFile not really used currently
        is - InputStream to add to the cache.
        monitor - TaskMonitor to monitor and update.
        Returns:
        string with new file's md5.
        Throws:
        java.io.IOException - if IO error
        CancelledException - if user canceled.

      • addStreamToCache

        public FileCacheEntry addStreamToCache​(java.io.InputStream is,
                                       TaskMonitor monitor)
                                throws java.io.IOException,
                                       CancelledException
        Stores a stream in the file cache.

        Parameters:
        is - InputStream to store in the cache.
        monitor - TaskMonitor to watch and update.
        Returns:
        File location of the new file.
        Throws:
        java.io.IOException - if IO error
        CancelledException - if the user cancels.

      • getFile

        public java.io.File getFile​(FSRL fsrl,
                            TaskMonitor monitor)
                     throws CancelledException,
                            java.io.IOException
        Returns a java.io.file with the data from the requested FSRL. Simple local files will be returned directly, and files nested in containers will be located in the file cache directory and have a 'random' name.

        Never returns nulls, throws IOException if not found or error.

        Parameters:
        fsrl - FSRL of the desired file.
        monitor - TaskMonitor to watch and update.
        Returns:
        File of the desired file in the cache, never null.
        Throws:
        CancelledException - if user cancels.
        java.io.IOException - if IO problem.

      • getLocalFSRL

        public FSRL getLocalFSRL​(java.io.File f)
        Builds a FSRL of a file located on the local filesystem.
        Parameters:
        f - File on the local filesystem
        Returns:
        FSRL pointing to the same file, never null

      • getLocalGFile

        public GFile getLocalGFile​(java.io.File f)
        Converts a java File instance into a GFilesystem GFile hosted on the local filesystem.

        Parameters:
        f - File on the local filesystem
        Returns:
        GFile representing the same file or null if there was a problem with the file path.

      • getDerivedFile

        public FileCacheEntry getDerivedFile​(FSRL fsrl,
                                     java.lang.String derivedName,
                                     DerivedFileProducer producer,
                                     TaskMonitor monitor)
                              throws CancelledException,
                                     java.io.IOException
        Returns a reference to a file in the FileCache that contains the derived (ie. decompressed or decrypted) contents of a source file, as well as its md5.

        If the file was not present in the cache, the producer lambda will be called and it will be responsible for returning an InputStream which has the derived contents, which will be added to the file cache for next time.

        Parameters:
        fsrl - FSRL of the source (or container) file that this derived file is based on
        derivedName - a unique string identifying the derived file inside the source (or container) file
        producer - a callback or lambda that returns an InputStream that will be streamed into a file and placed into the file cache. Example: 
        (file) -> { return new XYZDecryptorInputStream(file); }
        monitor - TaskMonitor that will be monitor for cancel requests and updated with file io progress
        Returns:
        FileCacheEntry with file and md5 fields
        Throws:
        CancelledException - if the user cancels
        java.io.IOException - if there was an io error

      • getDerivedFilePush

        public FileCacheEntry getDerivedFilePush​(FSRL fsrl,
                                         java.lang.String derivedName,
                                         DerivedFilePushProducer pusher,
                                         TaskMonitor monitor)
                                  throws CancelledException,
                                         java.io.IOException
        Returns a reference to a file in the FileCache that contains the derived (ie. decompressed or decrypted) contents of a source file, as well as its md5.

        If the file was not present in the cache, the push producer lambda will be called and it will be responsible for producing and writing the derived file's bytes to a OutputStream, which will be added to the file cache for next time.

        Parameters:
        fsrl - FSRL of the source (or container) file that this derived file is based on
        derivedName - a unique string identifying the derived file inside the source (or container) file
        pusher - a callback or lambda that recieves a OutputStream. Example: 
        (os) -> { ...write to outputstream os here...; }
        monitor - TaskMonitor that will be monitor for cancel requests and updated with file io progress
        Returns:
        FileCacheEntry with file and md5 fields
        Throws:
        CancelledException - if the user cancels
        java.io.IOException - if there was an io error

      • hasDerivedFile

        public boolean hasDerivedFile​(FSRL fsrl,
                              java.lang.String derivedName,
                              TaskMonitor monitor)
                       throws CancelledException,
                              java.io.IOException
        Returns true if the specified derived file exists in the file cache.
        Parameters:
        fsrl - FSRL of the container
        derivedName - name of the derived file inside of the container
        monitor - TaskMonitor
        Returns:
        boolean true if file exists at time of query, false if file is not in cache
        Throws:
        CancelledException - if user cancels
        java.io.IOException - if other IO error

      • isFileFilesystemContainer

        public boolean isFileFilesystemContainer​(FSRL containerFSRL,
                                         TaskMonitor monitor)
                                  throws CancelledException,
                                         java.io.IOException
        Returns true if the container file probably holds one of the currently supported filesystem types.

        Parameters:
        containerFSRL - FSRL of the file being queried.
        monitor - TaskMonitor to watch and update progress.
        Returns:
        boolean true if the file probably is a container, false otherwise.
        Throws:
        CancelledException - if user cancels.
        java.io.IOException - if IO problem.

      • mountSpecificFileSystem

        public <FSTYPE extends GFileSystem> FSTYPE mountSpecificFileSystem​(FSRL containerFSRL,
                                                                   java.lang.Class<FSTYPE> fsClass,
                                                                   TaskMonitor monitor)
                                                            throws CancelledException,
                                                                   java.io.IOException
        Mount a specific file system (by class) using a specified container file.

        The newly constructed / mounted file system is not managed by this FileSystemService or controlled with FileSystemRefs.

        The caller is responsible for closing the resultant file system instance when it is no longer needed.

        Parameters:
        containerFSRL - a reference to the file that contains the file system image
        fsClass - the GFileSystem derived class that implements the specific file system
        monitor - TaskMonitor to allow the user to cancel
        Returns:
        new GFileSystem instance, caller is responsible for closing() when done.
        Throws:
        CancelledException - if user cancels
        java.io.IOException - if file io error or wrong file system type.

      • openFileSystemContainer

        public GFileSystem openFileSystemContainer​(FSRL containerFSRL,
                                           TaskMonitor monitor)
                                    throws CancelledException,
                                           java.io.IOException
        Open the file system contained at the specified location.

        The newly constructed / mounted file system is not managed by this FileSystemService or controlled with FileSystemRefs.

        The caller is responsible for closing the resultant file system instance when it is no longer needed.

        Parameters:
        containerFSRL - a reference to the file that contains the file system image
        monitor - TaskMonitor to allow the user to cancel
        Returns:
        new GFileSystem instance, caller is responsible for closing() when done.
        Throws:
        CancelledException - if user cancels
        java.io.IOException - if file io error or wrong file system type.

      • getFullyQualifiedFSRL

        public FSRL getFullyQualifiedFSRL​(FSRL fsrl,
                                  TaskMonitor monitor)
                           throws CancelledException,
                                  java.io.IOException
        Returns a cloned copy of the FSRL that should have MD5 values specified. (excluding GFile objects that don't have data streams)

        Also implements a best-effort caching of non-root filesystem FSRL's MD5 values. (ie. the md5 values of files inside of containers are cached. The md5 value of files on the real OS filesystem are not cached)

        Parameters:
        fsrl - FSRL of the file that should be forced to have a MD5
        monitor - TaskMonitor to watch and update with progress.
        Returns:
        possibly new FSRL instance with a MD5 value.
        Throws:
        CancelledException - if user cancels.
        java.io.IOException - if IO problem.

      • isLocal

        public boolean isLocal​(GFile gfile)
        Returns true if the specified file is on the local computer's filesystem.
        Parameters:
        gfile - file to query
        Returns:
        true if local, false if the path points to an embedded file in a container.

      • isLocal

        public boolean isLocal​(FSRL fsrl)
        Returns true if the specified location is a path on the local computer's filesystem.
        Parameters:
        fsrl - FSRL path to query
        Returns:
        true if local, false if the path points to an embedded file in a container.

      • getAllFilesystemNames

        public java.util.List<java.lang.String> getAllFilesystemNames()
        Returns a list of all detected GFilesystem filesystem names.

        See FileSystemFactoryMgr.getAllFilesystemNames().

        Returns:
        List of strings.

      • getMountedFilesystems

        public java.util.List<FSRLRoot> getMountedFilesystems()
        Returns a list of all currently mounted filesystems.

        As a FSRL is returned, there is no guarantee that the filesystem will still be mounted when you later use values from the list.

        Returns:
        List of FSRLRoot of currently mounted filesystems.

      • getMountedFilesystem

        public FileSystemRef getMountedFilesystem​(FSRLRoot fsFSRL)
        Returns a new FilesystemRef handle to an already mounted filesystem.

        The caller is responsible for releasing the ref.

        Returns null if there is no filesystem mounted at fsFSRL.

        Parameters:
        fsFSRL - FSRLRoot of file system to get a FileSystemRef to.
        Returns:
        new FileSystemRef or null if requested file system not mounted.