Class GorgonFileSystemProvider

A file system provider that mounts Windows file system directories.

Inheritance

object

GorgonPlugIn

GorgonFileSystemProvider

Implements

IGorgonFileSystemProvider

IGorgonNamedObject

Inherited Members

GorgonPlugIn.Name

GorgonPlugIn.Assembly

GorgonPlugIn.PlugInPath

GorgonPlugIn.Description

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.IO.Providers

Assembly: Gorgon.FileSystem.dll

Syntax

public abstract class GorgonFileSystemProvider : GorgonPlugIn, IGorgonFileSystemProvider, IGorgonNamedObject

Remarks

IGorgonFileSystemProvider implementors must inherit from this type to create a provider plug in.

File system providers provide access to a physical file system, and provides the communications necessary to read data from that physical file system. When used in conjunction with the IGorgonFileSystem object, a provider enables access to multiple types of physical file systems so they seamlessly appear to be from a single file system. The underlying system has no idea if the file is a standard file system file, or a file inside of a zip archive.

important

As the documentation states, providers can read data from a file system. However, no mechanism is available to write to a file system through a provider. This is by design. The IGorgonFileSystemWriter<T> type allows writing to a file system via a predefined area in a physical file system.

When this type is implemented, it can be made to read any type of file system, including those that store their contents in a packed file format (e.g. Zip). And since this type inherits from GorgonPlugIn, the file system provider can be loaded dynamically through Gorgon's plug in system.

This type allows the mounting of a directory so that data can be read from the native operating system file system. This is the default provider for any IGorgonFileSystem.

Constructors

GorgonFileSystemProvider(string)

Initializes a new instance of the GorgonFileSystemProvider class.

Declaration

protected GorgonFileSystemProvider(string providerDescription)

Parameters

Type	Name	Description
string	providerDescription	The human readable description for the file system provider.

Properties

IsReadOnly

Property to return whether this provider only gives read only access to the physical file system.

Declaration

public abstract bool IsReadOnly { get; }

Property Value

Type	Description
bool

MemoryStreamManager

Property to return a memory stream manager for efficient usage of the MemoryStream type.

Declaration

protected RecyclableMemoryStreamManager MemoryStreamManager { get; }

Property Value

Type	Description
RecyclableMemoryStreamManager

Remarks

Developers should use this instead of creating new MemoryStream objects.

PreferredExtensions

Property to return a list of preferred file extensions (if applicable).

Declaration

public IGorgonNamedObjectReadOnlyDictionary<GorgonFileExtension> PreferredExtensions { get; protected set; }

Property Value

Type	Description
IGorgonNamedObjectReadOnlyDictionary<GorgonFileExtension>

Remarks

Implementors of a GorgonFileSystemProvider that reads from a packed file should supply a list of well known file name extensions wrapped in GorgonFileExtension objects for that physical file system type. This list can then be then used in an application to filter the types of files to open with a IGorgonFileSystem. If the file system reads directories on the native file system, then this collection should remain empty.

ProviderPath

Property to return the path to the provider assembly (if applicable).

Declaration

public string ProviderPath { get; }

Property Value

Type	Description
string

Methods

CanReadFileSystem(string)

Function to determine if a physical file system can be read by this provider.

Declaration

public bool CanReadFileSystem(string physicalPath)

Parameters

Type	Name	Description
string	physicalPath	Path to the packed file containing the file system.

Returns

Type	Description
bool	true if the provider can read the packed file, false if not.

Remarks

This will test a physical file system (e.g. a Zip file) to see if the provider can open it or not. If used with a directory on an operating system file system, this method should always return false.

Exceptions

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

Enumerate(string, IGorgonVirtualDirectory)

Function to enumerate the files and directories from a physical location and map it to a virtual location.

Declaration

public GorgonPhysicalFileSystemData Enumerate(string physicalLocation, IGorgonVirtualDirectory mountPoint)

Parameters

Type	Name	Description
string	physicalLocation	The physical location containing files and directories to enumerate.
IGorgonVirtualDirectory	mountPoint	A IGorgonVirtualDirectory that the directories and files from the physical file system will be mounted into.

Returns

Type	Description
GorgonPhysicalFileSystemData	A GorgonPhysicalFileSystemData object containing information about the directories and files contained within the physical file system.

Remarks

This will return a GorgonPhysicalFileSystemData representing the paths to directories and IGorgonPhysicalFileInfo objects under the virtual file system. Each file system file and directory is mapped from its physicalLocation on the physical file system to a mountPoint on the virtual file system. For example, if the mount point is set to /MyMount/, and the physical location of a file is c:\SourceFileSystem\MyDirectory\MyTextFile.txt, then the returned value should be /MyMount/MyDirectory/MyTextFile.txt.

Implementors of a GorgonFileSystemProvider plug in can override this method to read the list of files from another type of file system, like a Zip file.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalLocation, or the mountPoint parameters are null.
ArgumentEmptyException	Thrown when the physicalLocation parameter is empty.

EnumerateFiles(string, IGorgonVirtualDirectory)

Function to enumerate the files for a given directory.

Declaration

public IReadOnlyDictionary<string, IGorgonPhysicalFileInfo> EnumerateFiles(string physicalLocation, IGorgonVirtualDirectory mountPoint)

Parameters

Type	Name	Description
string	physicalLocation	The physical location containing files to enumerate.
IGorgonVirtualDirectory	mountPoint	A IGorgonVirtualDirectory that the files from the physical file system will be mounted into.

Returns

Type	Description
IReadOnlyDictionary<string, IGorgonPhysicalFileInfo>	A list of files contained within the physical file system.

Remarks

This will return a list of IGorgonPhysicalFileInfo objects under the virtual file system. Each file system file is mapped from its physicalLocation on the physical file system to a mountPoint on the virtual file system. For example, if the mount point is set to /MyMount/, and the physical location of a file is c:\SourceFileSystem\MyDirectory\MyTextFile.txt, then the returned value should be /MyMount/MyDirectory/MyTextFile.txt.

Implementors of a GorgonFileSystemProvider plug in can override this method to read the list of files from another type of file system, like a Zip file.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalLocation, or the mountPoint parameters are null.
ArgumentEmptyException	Thrown when the physicalLocation parameter is empty.

MapToPhysicalPath(string, GorgonFileSystemMountPoint)

Function to return the physical file system path from a virtual file system path.

Declaration

public string MapToPhysicalPath(string virtualPath, GorgonFileSystemMountPoint mountPoint)

Parameters

Type	Name	Description
string	virtualPath	Virtual path to the file/folder.
GorgonFileSystemMountPoint	mountPoint	The mount point used to map the physical path.

Returns

Type	Description
string	The physical file system path.

MapToVirtualPath(string, GorgonFileSystemMountPoint)

Function to return the virtual file system path from a physical file system path.

Declaration

public string MapToVirtualPath(string physicalPath, GorgonFileSystemMountPoint mountPoint)

Parameters

Type	Name	Description
string	physicalPath	Physical path to the file/folder.
GorgonFileSystemMountPoint	mountPoint	The mount point used to map the physical path.

Returns

Type	Description
string	The virtual file system path.

OnCanReadFile(string)

Function to determine if a physical file system can be read by this provider.

Declaration

protected abstract bool OnCanReadFile(string physicalPath)

Parameters

Type	Name	Description
string	physicalPath	Path to the packed file containing the file system.

Returns

Type	Description
bool	true if the provider can read the packed file, false if not.

Remarks

This will test a physical file system (e.g. a Zip file) to see if the provider can open it or not. If used with a directory on an operating system file system, this method should always return false.

Implementors of a GorgonFileSystemProvider should override this method to determine if a packed file can be read by reading the header of the file specified in physicalPath.

Exceptions

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

OnEnumerate(string, IGorgonVirtualDirectory)

Function to enumerate the files and directories from a physical location and map it to a virtual location.

Declaration

protected abstract GorgonPhysicalFileSystemData OnEnumerate(string physicalLocation, IGorgonVirtualDirectory mountPoint)

Parameters

Type	Name	Description
string	physicalLocation	The physical location containing files and directories to enumerate.
IGorgonVirtualDirectory	mountPoint	A IGorgonVirtualDirectory that the directories and files from the physical file system will be mounted into.

Returns

Type	Description
GorgonPhysicalFileSystemData	A GorgonPhysicalFileSystemData object containing information about the directories and files contained within the physical file system.

Remarks

This will return a GorgonPhysicalFileSystemData representing the paths to directories and IGorgonPhysicalFileInfo objects under the virtual file system. Each file system file and directory is mapped from its physicalLocation on the physical file system to a mountPoint on the virtual file system. For example, if the mount point is set to /MyMount/, and the physical location of a file is c:\SourceFileSystem\MyDirectory\MyTextFile.txt, then the returned value should be /MyMount/MyDirectory/MyTextFile.txt.

Implementors of a GorgonFileSystemProvider plug in can override this method to read the list of files from another type of file system, like a Zip file.

Implementors of a GorgonFileSystemProvider should override this method to read the list of directories and files from another type of file system, like a Zip file. The default functionality will only enumerate directories and files from the operating system file system.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the physicalLocation, or the mountPoint parameters are null.
ArgumentEmptyException	Thrown when the physicalLocation parameter is empty.

OnEnumerateFiles(string, IGorgonVirtualDirectory)

Function to enumerate the files for a given directory.

Declaration

protected abstract IReadOnlyDictionary<string, IGorgonPhysicalFileInfo> OnEnumerateFiles(string physicalLocation, IGorgonVirtualDirectory mountPoint)

Parameters

Type	Name	Description
string	physicalLocation	The physical location containing files to enumerate.
IGorgonVirtualDirectory	mountPoint	A IGorgonVirtualDirectory that the files from the physical file system will be mounted into.

Returns

Type	Description
IReadOnlyDictionary<string, IGorgonPhysicalFileInfo>	A list of files contained within the physical file system.

Remarks

This will return a list of IGorgonPhysicalFileInfo objects under the virtual file system. Each file system file is mapped from its physicalLocation on the physical file system to a mountPoint on the virtual file system. For example, if the mount point is set to /MyMount/, and the physical location of a file is c:\SourceFileSystem\MyDirectory\MyTextFile.txt, then the returned value should be /MyMount/MyDirectory/MyTextFile.txt.

Implementors of a GorgonFileSystemProvider plug in can override this method to read the list of files from another type of file system, like a Zip file.

OnGetPhysicalPath(string, GorgonFileSystemMountPoint)

Function to return the physical file system path from a virtual file system path.

Declaration

protected abstract string OnGetPhysicalPath(string virtualPath, GorgonFileSystemMountPoint mountPoint)

Parameters

Type	Name	Description
string	virtualPath	Virtual path to the file/folder.
GorgonFileSystemMountPoint	mountPoint	The mount point used to map the physical path.

Returns

Type	Description
string	The physical file system path.

OnOpenFileStream(IGorgonVirtualFile)

Function to open a stream to a file on the physical file system from the IGorgonVirtualFile passed in.

Declaration

protected abstract GorgonFileSystemStream OnOpenFileStream(IGorgonVirtualFile file)

Parameters

Type	Name	Description
IGorgonVirtualFile	file	The IGorgonVirtualFile that will be used to locate the file that will be opened on the physical file system.

Returns

Type	Description
GorgonFileSystemStream	A Stream to the file, or null if the file does not exist.

Remarks

This will take the IGorgonVirtualFile and open its corresponding physical file location as a stream for reading. The stream that is returned will be opened, and as such, it is the responsibility of the user to close the stream when finished.

If the file does not exist in the physical file system, this method should return null.

Implementors of a GorgonFileSystemProvider plug in can overload this method to return a stream into a file within their specific native provider (e.g. a Zip file provider will return a stream into the zip file positioned at the location of the compressed file within the zip file).

Exceptions

Type	Condition
ArgumentNullException	Thrown when the file parameter is null.

OpenFileStream(IGorgonVirtualFile)

Function to open a stream to a file on the physical file system from the IGorgonVirtualFile passed in.

Declaration

public Stream OpenFileStream(IGorgonVirtualFile file)

Parameters

Type	Name	Description
IGorgonVirtualFile	file	The IGorgonVirtualFile that will be used to locate the file that will be opened on the physical file system.

Returns

Type	Description
Stream	A Stream to the file, or null if the file does not exist.

Remarks

This will take the IGorgonVirtualFile and open its corresponding physical file location as a stream for reading. The stream that is returned will be opened, and as such, it is the responsibility of the user to close the stream when finished.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the file parameter is null.

Implements

IGorgonFileSystemProvider

IGorgonNamedObject

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)