Interface IGorgonFileSystem

The virtual file System interface.

Namespace: Gorgon.IO

Assembly: Gorgon.FileSystem.dll

Syntax

public interface IGorgonFileSystem

Remarks

This will allow the user to mount directories or packed files (such as Zip files) into a unified file system. For example, if the user has mounted MyData.zip and C:\users\Bob\Data\ into the file system then all files and/or directories from both sources would be combined into a single virtual file system. This has the advantage of being able to access disparate file systems without having to run through multiple interfaces to get at their data.

The virtual file system is a read only file system. This is done by design so that the integrity of the original physical file systems can be preserved. If your application needs to write data into the file system, then the IGorgonFileSystemWriter<T> has been provided to give access to a writable area that will integrate with this object.

Physical file systems (such as a windows directory or a Zip file) are "mounted" into this object. When a physical file system is mounted, all of the file names (and other info) and directory names will be stored in hierarchal structure similar to a Unix directory structure. Because of this, there will be some differences from the typical Windows directory setup:

• The root of the file system is not "C:\" or "\\Computer\". In this object, the root is '/' (e.g. /MyFile.txt is a file located in the root).
• The directory separators are forward slashes: / and not back slashes: \. (e.g. c:\MyDirectory\MySubDirectory\ is now /MyDirectory/MySubDirectory/)

important

The order in which file systems are mounted into the virtual file system is important. If a zip file contains SomeText.txt, and a directory contains the same file path, then if the zip file is mounted, followed by the directory, the file in the directory will override the file in the zip file. This is true for directories as well.

By default, a new file system instance will only have access to the directories and files of the hard drive via the default provider. File systems that are in packed files (e.g. Zip files) can be loaded into the file system by way of a GorgonFileSystemProvider. Providers are typically plug in objects that are loaded into the file system via the GorgonFileSystemProviderFactory. Once a provider plug in is loaded, then the contents of that file system can be mounted like a standard directory.

When a file system provider is added to the virtual file system object upon creation, the object will contain 2 providers, the default provider is always available with any additional providers.

Examples

This example shows how to create a file system with the default provider, and mount a directory to the root:

IGorgonFileSystem fileSystem = new GorgonFileSystem();

fileSystem.Mount(@"C:\MyDirectory\", "/");

This example shows how to load a provider from the provider factory and use it with the file system:

// First we need to load the assembly with the provider plug in.
using (GorgonPlugInAssemblyCache assemblies = new GorgonPlugInAssemblyCache())
{
	assemblies.Load(@"C:\PlugIns\GorgonFileSystem.Zip.dll"); 
	GorgonPlugInService plugInService = new GorgonPlugInService(assemblies);

	// We'll use the factory to get the zip plug in provider.
	IGorgonFileSystemProviderFactory factory = new GorgonFileSystemProviderFactory(plugInService);

	IGorgonFileSystemProvider zipProvider = factory.CreateProvider("Gorgon.IO.Zip.ZipProvider");

	// Now create the file system with the zip provider.
	IGorgonFileSystem fileSystem = new GorgonFileSystem(zipProvider);
	fileSystem.Mount(@"C:\ZipFiles\MyFileSystem.zip", "/");
}

Properties

DefaultProvider

Property to return the default file system provider for this file system.

Declaration

IGorgonFileSystemProvider DefaultProvider { get; }

Property Value

Type	Description
IGorgonFileSystemProvider

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

MountPoints

Property to return a list of mount points that are currently assigned to this file system.

Declaration

IEnumerable<GorgonFileSystemMountPoint> MountPoints { get; }

Property Value

Type	Description
IEnumerable<GorgonFileSystemMountPoint>

Remarks

This is a list of GorgonFileSystemMountPoint values. These values contain location of the mount point in the virtual file system, the physical location of the physical file system and the provider that mounted the physical file system.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Providers

Property to return the IGorgonFileSystemProvider installed in this file system.

Declaration

IEnumerable<IGorgonFileSystemProvider> Providers { get; }

Property Value

Type	Description
IEnumerable<IGorgonFileSystemProvider>

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

RootDirectory

Property to return the root directory for the file system.

Declaration

IGorgonVirtualDirectory RootDirectory { get; }

Property Value

Type	Description
IGorgonVirtualDirectory

Remarks

This is the beginning of the directory/file structure for the file system. Users can walk through the properties on this object to get the sub directories and files for a virtual file system as a hierarchical view.

tip

When populating a tree view, this property is useful for helping to lay out the nodes in the tree.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Methods

FindDirectories(string, string, bool)

Function to find all the directories with the name specified by the directory mask.

Declaration

IEnumerable<IGorgonVirtualDirectory> FindDirectories(string path, string directoryMask, bool recursive = true)

Parameters

Type	Name	Description
string	path	The path to the directory to start searching from.
string	directoryMask	The directory name or mask to search for.
bool	recursive	[Optional] true to search all child directories, false to search only the immediate directory.

Returns

Type	Description
IEnumerable<IGorgonVirtualDirectory>	An enumerable object containing IGorgonVirtualDirectory objects that match the directoryMask.

Remarks

This will look for all the directories specified by the directoryMask parameter. This parameter will accept wild card characters like * and ?. This allows pattern matching which can be used to find a series of directories. If the wild card is omitted, then only that name is sought out.

The path parameter is assumed to be starting from the root directory: /. If the path omits the starting root separator (e.g. MyDir/MyFile.txt instead of /MyDir/MyFile.txt), then one will be supplied automatically.

warning

The directoryMask is not a path. It is the name (or mask of the name) of the directory we wish to find. Calling FindDirectories("/", "/MyDir/ThisDir/C*w/"); will not return any results. Use the path parameter to specify the origin for the search.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the directoryMask or the path parameter is null.
ArgumentEmptyException	Thrown when the directoryMask or the path parameter are empty.
DirectoryNotFoundException	Thrown when the directory in specified by the path parameter was not found.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

FindFiles(string, string, bool)

Function to find all the files with the name specified by the file mask.

Declaration

IEnumerable<IGorgonVirtualFile> FindFiles(string path, string fileMask, bool recursive = true)

Parameters

Type	Name	Description
string	path	The path to the directory to start searching from.
string	fileMask	The file name or mask to search for.
bool	recursive	[Optional] true to search all directories, false to search only the immediate directory.

Returns

Type	Description
IEnumerable<IGorgonVirtualFile>	An enumerable object containing IGorgonVirtualFile objects that match the fileMask.

Remarks

This will look for all the files specified by the fileMask parameter. This parameter will accept wild card characters like * and ?. This allows pattern matching which can be used to find a series of files. If the wild card is omitted, then only that name is sought out.

The path parameter is assumed to be starting from the root directory: /. If the path omits the starting root separator (e.g. MyDir/MyFile.txt instead of /MyDir/MyFile.txt), then one will be supplied automatically.

warning

The fileMask is not a path. It is the name (or mask of the name) of the file we wish to find. Calling FindFiles("/", "/MyDir/C*w.txt"); will not return any results. Use the path parameter to specify the origin for the search.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the fileMask or the path parameter is null.
ArgumentEmptyException	Thrown when the fileMask or the path are empty.
DirectoryNotFoundException	Thrown when the directory in specified by the path parameter was not found.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

GetDirectory(string)

Function to retrieve a directory from the file system.

Declaration

IGorgonVirtualDirectory GetDirectory(string path)

Parameters

Type	Name	Description
string	path	Path to the directory to retrieve.

Returns

Type	Description
IGorgonVirtualDirectory	A IGorgonVirtualDirectory if found, null if not.

Remarks

This is the primary method of accessing directories from the file system. It will return a IGorgonVirtualDirectory object that will allow users retrieve the files or any sub directories under that directory.

The path parameter is assumed to be starting from the root directory: /. If the path omits the starting root separator (e.g. MyDir/MyFile.txt instead of /MyDir/MyFile.txt), then one will be supplied automatically.

Examples

This example will show how to retrieve a directory from the file system:

IGorgonFileSystem fileSystem = new GorgonFileSystem();

fileSystem.Mount(@"C:\MyDirectory\", "/");

IGorgonVirtualDirectory directory = fileSystem.GetDirectory("/ASubDirectory");

foreach(IGorgonVirtualDirectory subDirectory in directory.Directories)
{
	Console.WriteLine("Sub directory: {0}", subDirectory.FullPath);
}

Exceptions

Type	Condition
ArgumentNullException	Thrown when the path parameter is null
ArgumentEmptyException	Thrown when the path parameter is an empty string.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

GetFile(string)

Function to retrieve a IGorgonVirtualFile from the file system.

Declaration

IGorgonVirtualFile GetFile(string path)

Parameters

Type	Name	Description
string	path	Path to the file to retrieve.

Returns

Type	Description
IGorgonVirtualFile	The IGorgonVirtualFile requested or null if the file was not found.

Remarks

This is the primary method of accessing files from the file system. It will return a IGorgonVirtualFile object that will allow users to open a stream to the file and read its contents.

The path parameter is assumed to be starting from the root directory: /. If the path omits the starting root separator (e.g. MyDir/MyFile.txt instead of /MyDir/MyFile.txt), then one will be supplied automatically. This is also true for filenames without a directory in the path.

Examples

This example will show how to read a file from the file system:

IGorgonFileSystem fileSystem = new GorgonFileSystem();

fileSystem.Mount(@"C:\MyDirectory\", "/");

IGorgonVirtualFile file = fileSystem.GetFile("/ASubDirectory/MyFile.txt");

using (Stream stream = file.OpenStream())
{
   // Read the file from the stream...
}

Exceptions

Type	Condition
ArgumentNullException	Thrown when the path parameter is null.
ArgumentEmptyException	Thrown when the path parameter is empty. -or- Thrown when there is no file name in the path.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Mount(string, string)

Function to mount a physical file system into the virtual file system.

Declaration

GorgonFileSystemMountPoint Mount(string physicalPath, string mountPath = null)

Parameters

Type	Name	Description
string	physicalPath	Path to the physical file system directory or file that contains the files/directories to enumerate.
string	mountPath	[Optional] Virtual directory path to mount into.

Returns

Type	Description
GorgonFileSystemMountPoint	A mount point value for the currently mounted physical path, its mount point in the virtual file system, and the provider used to mount the physical location.

Remarks

This method is used to mount the contents of a physical file system (such as a windows directory, or a file if the appropriate provider is installed) into a virtual directory in the file system. All folders and files in the physical file system object will be made available under the virtual folder specified by the mountPath parameter.

The method will determine if the user is attempting to mount a physical directory or file. For directories, the physicalPath must end with a trailing backward slash (or forward slash depending on your native physical file system). For files, the directory should contain a file name. If mounting a file, and only the file name is supplied, then the current directory is used to locate the file. Relative paths are supported, and will be converted into absolute paths based on the current directory.

When files (e.g. zip files) are mounted, the appropriate provider must be loaded and installed via the constructor of this object. The providers can be loaded through a IGorgonFileSystemProviderFactory instance.

The physicalPath is usually a file or a directory on the operating system file system. But in some cases, this physical location may point to somewhere completely virtual. In order to mount data from those file systems, a provider-specific prefix must be prefixed to the parameter (see provider documentation for the correct prefix). This prefix must always begin with ::\\.

The mountPath parameter is optional, and if omitted, the contents of the physical file system object will be mounted into the root (/) of the virtual file system. If the mountPath is supplied, then a virtual directory is created (or used if it already exists) to host the contents of the physical file system.

Examples

This example shows how to create a file system with the default provider, and mount a directory to the root:

IGorgonFileSystem fileSystem = new GorgonFileSystem();

fileSystem.Mount(@"C:\MyDirectory\", "/");

This example shows how to load a provider from the provider factory and use it with the file system:

// First we need to load the assembly with the provider plug in.
using (GorgonPlugInAssemblyCache assemblies = new GorgonPlugInAssemblyCache())
{
	assemblies.Load(@"C:\PlugIns\GorgonFileSystem.Zip.dll"); 
	GorgonPlugInService plugInService = new GorgonPlugInService(assemblies);

	// We'll use the factory to get the zip plug in provider.
	IGorgonFileSystemProviderFactory factory = new GorgonFileSystemProviderFactory(plugInService);

	IGorgonFileSystemProvider zipProvider = factory.CreateProvider("Gorgon.IO.Zip.ZipProvider");

	// Now create the file system with the zip provider.
	IGorgonFileSystem fileSystem = new GorgonFileSystem(zipProvider);
	fileSystem.Mount(@"C:\ZipFiles\MyFileSystem.zip", "/");
}

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalPath parameter is null.
ArgumentEmptyException	Thrown when the physicalPath parameter is an empty string. -or- Thrown if mounting a directory and there is no directory in the path.
DirectoryNotFoundException	Thrown when the directory specified by physicalPath was not found.
FileNotFoundException	Thrown if a file was specified by physicalPath was not found.
IOException	Thrown when the file pointed to by the physicalPath parameter could not be read by any of the file system providers.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Refresh()

Function to reload all the files and directories in the file system.

Declaration

void Refresh()

Remarks

This will unmount and re-mount all the known mount points for the file system, effectively rebuilding the file system file/directory tree.

Any files or directories sharing the same path as those in the IGorgonFileSystemWriter<T> will be restored if they were deleted. This is because the physical file systems (other than the write area) are never changed. For example:

// Let's assume this contains a file called "MyBudget.xls"
fileSystem.Mount("MyZip.zip", "/");
// And the write area also contains a file called "MyBudget.xls".
writeArea.Mount();
// The "MyBudget.xls" in the write area overrides the file in the zip file since the write area mount
// is higher in the order list.
//
// This will now delete the MyBudget.xls from the virtual file system and from the physical write area.
writeArea.Delete("MyBudget.xls");
// Now refresh the file system...
fileSystem.Refresh();
// Now the file will be back, only this time it will belong to the zip file because
// the write area had its file deleted.
var file = fileSystem.GetFile("MyBudget.xls");

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Refresh(string)

Function to reload all the files and directories within, and optionally, under the specified directory.

Declaration

void Refresh(string path)

Parameters

Type	Name	Description
string	path	The path to the directory to refresh.

Remarks

Any files or directories sharing the same path as those in the IGorgonFileSystemWriter<T> will be restored if they were deleted. This is because the physical file systems (other than the write area) are never changed. For example:

// Let's assume this contains a file called "MyBudget.xls"
fileSystem.Mount(@"C:\MountDirectory\", "/");
// Copy an external file into out mounted directory.
File.Copy(@"C:\OtherData\MyBudget.xls", "C:\MountDirectory\Files");
// Get the file...
IGorgonVirtualFile file = fileSystem.GetFile("/Files/MyBudget.xls");
// The file does not exist yet because the file system has no idea that it's been added.
if (file is null)
{
Console.WriteLine("File does not exist.");
}
// Now refresh the file system...
fileSystem.Refresh("/Files/");
// Get the file... again.
IGorgonVirtualFile file = fileSystem.GetFile("/Files/MyBudget.xls");
// The file will now show up in the directory.
if (file is not null)
{
Console.WriteLine("File exists.");
}

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Unmount(GorgonFileSystemMountPoint)

Function to unmount the mounted virtual file system directories and files specified by the mount point.

Declaration

void Unmount(GorgonFileSystemMountPoint mountPoint)

Parameters

Type	Name	Description
GorgonFileSystemMountPoint	mountPoint	The mount point to unmount.

Remarks

This will unmount a physical file system from the virtual file system by removing all directories and files associated with that mountPoint.

When passing the mountPoint parameter, users should pass the return value from the Mount(string, string) method.

Since the mount order overrides any existing directories or files with the same paths, those files/directories will not be restored. A user should call the Refresh() method if they wish to restore any file/directory entries.

Exceptions

Type	Condition
ArgumentEmptyException	Thrown when the mountPoint was not found in the file system.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Unmount(string)

Function to unmount the mounted virtual file system directories and files pointed at by a physical path.

Declaration

void Unmount(string physicalPath)

Parameters

Type	Name	Description
string	physicalPath	The physical path to unmount.

Remarks

This overload will unmount all the mounted virtual files/directories for every mount point with the specified physicalPath.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalPath parameter is null.
ArgumentEmptyException	Thrown when the physicalPath parameter is empty. -or- Thrown when the mount point with the physicalPath was not found in the file system.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Unmount(string, string)

Function to unmount the mounted virtual file system directories and files pointed at the by the physical path specified and mounted into the mount location specified.

Declaration

void Unmount(string physicalPath, string mountLocation)

Parameters

Type	Name	Description
string	physicalPath	The physical file system path.
string	mountLocation	The virtual sub directory that the physical location is mounted under.

Remarks

This will unmount a physical file system from the virtual file system by removing all directories and files associated with that mount point physicalPath and mountLocation.

Since the mount order overrides any existing directories or files with the same paths, those files/directories will not be restored. A user should call the Refresh() method if they wish to restore any file/directory entries.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalPath or the mountLocation parameters are null.
ArgumentEmptyException	Thrown when the physicalPath or the mountLocation parameters are empty. -or- Thrown when the mount point with the physicalPath and mountLocation was not found in the file system.

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

Gorgon2DFileSystemExtensions.LoadSpriteFromFileSystem(IGorgonFileSystem, Gorgon2D, string, GorgonTexture2DLoadOptions, IEnumerable<IGorgonSpriteCodec>, IEnumerable<IGorgonImageCodec>)

Gorgon2DEditorExtensions.CreateContentLoader(IGorgonFileSystem, Gorgon2D, GorgonTextureCache<GorgonTexture2D>)

Gorgon2DEditorExtensions.LoadImage(IGorgonFileSystem, string, IReadOnlyList<IGorgonImageCodec>)

Gorgon2DEditorExtensions.LoadSprite(IGorgonFileSystem, Gorgon2D, string, ResourceUsage, IReadOnlyList<IGorgonSpriteCodec>, IReadOnlyList<IGorgonImageCodec>, GorgonTexture2DView)

IOExtensions.GetContentItems(IGorgonFileSystem, string, string, string, bool)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)

See Also

IGorgonFileSystemWriter<T>

GorgonFileSystemProvider