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 closed 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.

    Files written to the fscache directory are obfuscated to prevent interference from virus scanners. See ObfuscatedInputStream or ObfuscatedOutputStream or ObfuscatedFileByteProvider.

    Thread-safe.

    • 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

      • isInitialized

        public static boolean isInitialized()
        Returns true if this service has been loaded
        Returns:
        true if this service has been loaded

      • clear

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

      • closeUnusedFileSystems

        public void closeUnusedFileSystems()
        Close unused filesystems.

      • releaseFileSystemImmediate

        public void releaseFileSystemImmediate​(FileSystemRef fsRef)
        Releases the specified FileSystemRef, and if no other references remain, removes it from the shared cache of file system instances.
        Parameters:
        fsRef - the ref to release

      • getLocalFS

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

      • 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.

      • 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

      • 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.

      • getByteProvider

        public ByteProvider getByteProvider​(FSRL fsrl,
                                    boolean fullyQualifiedFSRL,
                                    TaskMonitor monitor)
                             throws CancelledException,
                                    java.io.IOException
        Returns a ByteProvider with the contents of the requested file.

        Never returns null, throws IOException if there was a problem.

        Caller is responsible for closing() the ByteProvider when finished.

        Parameters:
        fsrl - FSRL file to wrap
        fullyQualifiedFSRL - if true, the returned ByteProvider's FSRL will always have a MD5 hash
        monitor - TaskMonitor to watch and update
        Returns:
        new ByteProvider
        Throws:
        CancelledException - if user cancels
        java.io.IOException - if IO problem

      • getDerivedByteProvider

        public ByteProvider getDerivedByteProvider​(FSRL containerFSRL,
                                           FSRL derivedFSRL,
                                           java.lang.String derivedName,
                                           long sizeHint,
                                           FileSystemService.DerivedStreamProducer producer,
                                           TaskMonitor monitor)
                                    throws CancelledException,
                                           java.io.IOException
        Returns a ByteProvider that contains the derived (ie. decompressed or decrypted) contents of the requested file.

        The resulting ByteProvider will be a cached file, either written to a temporary file, or a in-memory buffer if small enough (see FileCache.MAX_INMEM_FILESIZE).

        If the file was not present in the cache, the producer 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:
        containerFSRL - FSRL w/hash of the source (or container) file that this derived file is based on
        derivedFSRL - (optional) FSRL to assign to the resulting ByteProvider
        derivedName - a unique string identifying the derived file inside the source (or container) file
        sizeHint - the expected size of the resulting ByteProvider, or -1 if unknown
        producer - supplies an InputStream if needed. See FileSystemService.DerivedStreamProducer
        monitor - TaskMonitor that will be monitor for cancel requests and updated with file io progress
        Returns:
        a ByteProvider containing the bytes of the requested file, that has the specified derivedFSRL, or a pseudo FSRL if not specified. Never null
        Throws:
        CancelledException - if the user cancels
        java.io.IOException - if there was an io error

      • getDerivedByteProviderPush

        public ByteProvider getDerivedByteProviderPush​(FSRL containerFSRL,
                                               FSRL derivedFSRL,
                                               java.lang.String derivedName,
                                               long sizeHint,
                                               FileSystemService.DerivedStreamPushProducer pusher,
                                               TaskMonitor monitor)
                                        throws CancelledException,
                                               java.io.IOException
        Returns a ByteProvider that contains the derived (ie. decompressed or decrypted) contents of the requested file.

        The resulting ByteProvider will be a cached file, either written to a temporary file, or a in-memory buffer if small enough (see FileCache.MAX_INMEM_FILESIZE).

        If the file was not present in the cache, the pusher 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:
        containerFSRL - FSRL w/hash of the source (or container) file that this derived file is based on
        derivedFSRL - (optional) FSRL to assign to the resulting ByteProvider
        derivedName - a unique string identifying the derived file inside the source (or container) file
        sizeHint - the expected size of the resulting ByteProvider, or -1 if unknown
        pusher - writes bytes to the supplied OutputStream. See FileSystemService.DerivedStreamPushProducer
        monitor - TaskMonitor that will be monitor for cancel requests and updated with file io progress
        Returns:
        a ByteProvider containing the bytes of the requested file, that has the specified derivedFSRL, or a pseudo FSRL if not specified. Never null
        Throws:
        CancelledException - if the user cancels
        java.io.IOException - if there was an io error

      • releaseFileCache

        public void releaseFileCache​(FSRL fsrl)
        Allows the resources used by caching the specified file to be released.
        Parameters:
        fsrl - FSRL file to release cache resources for

      • pushFileToCache

        public ByteProvider pushFileToCache​(java.io.File file,
                                    FSRL fsrl,
                                    TaskMonitor monitor)
                             throws CancelledException,
                                    java.io.IOException
        Adds a plaintext (non-obfuscated) file to the cache, consuming it in the process, and returns a ByteProvider that contains the contents of the file.

        NOTE: only use this if you have no other choice and are forced to deal with already existing files in the local filesystem.

        Parameters:
        file - File to add
        fsrl - FSRL of the file that is being added
        monitor - TaskMonitor
        Returns:
        ByteProvider (hosted in the FileCache) that contains the bytes of the specified file
        Throws:
        CancelledException - if cancelled
        java.io.IOException - if error

      • hasDerivedFile

        public boolean hasDerivedFile​(FSRL containerFSRL,
                              java.lang.String derivedName,
                              TaskMonitor monitor)
                       throws CancelledException,
                              java.io.IOException
        Returns true if the specified derived file exists in the file cache.
        Parameters:
        containerFSRL - FSRL w/hash 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)

        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.

      • 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.

      • newCryptoSession

        public CryptoSession newCryptoSession()
        Returns a new CryptoSession that the caller can use to query for passwords and such. Caller is responsible for closing the instance when done.

        Later callers to this method will receive a nested CryptoSession that shares it's state with the initial CryptoSession, until the initial CryptoSession is closed().

        Returns:
        new CryptoSession instance, never null