Interface IGorgonFileSystemWriter<T>

Specifies a writable area on the physical file system for a virtual file system.

Namespace: Gorgon.IO
Assembly: Gorgon.FileSystem.dll
Syntax
public interface IGorgonFileSystemWriter<out T> where T : Stream
Type Parameters
Name Description
T

The type of stream returned from OpenStream(string, FileMode).
Remarks

The IGorgonFileSystem is a read only object that is only capable of returning existing files and directories from a physical file system. This is by design in order to keep the integrity and security of the original file system intact. However, in some cases, the need to write data is required by the application, and that data should be reflected in the current file system. Thus, we have the IGorgonFileSystemWriter<T> interface.

This object will allow applications to define an area on a physical file system that can be written to by the application. This provides isolation from the main file system and gives a degree of security when persisting data to an application. For example, if you have a zip file mounted in / and you want to write some data in a new directory, then you could create this object and provide a path to the writable area: c:\users\username\AppData\YourApplication\CustomData\. When creating, or deleting a directory or file, all data will be shunted to that physical location. For example, creating a directory named CustomDirectory would actually put the directory under c:\users\AppData\YourApplication\CustomData\CustomDirectory. Likewise, a file named SomeFile.txt would be put under >c:\users\username\AppData\YourApplication\CustomData\SomeFile.txt.

If the IGorgonFileSystem already has a file or directory mounted from a physical file system, then files from the write area will override those files, providing the most up to date copy of the data in the physical file systems. There is no actual change to the original files and they will remain in their original location, untouched. Only the files in the directory designated to be the writable area for a file system will be used for write operations.

Because the type parameter T is based on Stream, we can use this interface to build an object that can write into anything that supports a stream, including memory.

tip

When attaching a IGorgonFileSystemWriter<T> to a IGorgonFileSystem, the write area location is always mounted to the root of the virtual file system.

warning

Because the Mount(string, string) method always overrides existing files and directories (with the same path) with files and directories from the last loaded physical file system, the write area may have its files overridden if Mount(string, string) is called after linking the write area with a IGorgonFileSystem.

Examples

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

IGorgonFileSystem fileSystem = new GorgonFileSystem();
IGorgonFileSystemWriter writeArea = new GorgonFileSystemWriter(fileSystem, @"C:\MyWritingSpot\");

// Mount a directory for this file system.
fileSystem.Mount(@"C:\MyDirectory\", "/"); 

// Ensure that we mount the write area to ensure that the files in the write directory 
// are available.
writeArea.Mount();

// Create a text file.
using (Stream stream = writeArea.OpenStream("/AFile.txt", FileMode.Create))
{
	using (StreamWriter writer = new StreamWriter(stream, Encoding.UTF8))
	{
		writer.WriteLine("This is a line of text.");
	}
}

// This should retrieve the updated file.
IGorgonVirtualFile file = fileSystem.GetFile("/AFile.txt");

Properties

| Edit this page View Source

FileSystem

Property to return the file system linked to this writable area.

Declaration
IGorgonFileSystem FileSystem { get; }
Property Value
Type Description
IGorgonFileSystem
| Edit this page View Source

WriteLocation

Property to return the location on the physical file system to use as the writable area for a IGorgonFileSystem.

Declaration
string WriteLocation { get; }
Property Value
Type Description
string
Remarks

This value may return null or an empty string if there's no actual location on a physical file system (e.g. the file system is located in memory).

Methods

| Edit this page View Source

CopyDirectory(string, string, GorgonCopyCallbackOptions)

Function to copy a directory to another directory.

Declaration
void CopyDirectory(string directoryPath, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
string directoryPath

The path to the directory to copy.
string destDirectoryPath

The destination directory path that will receive the copied data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method copies a directory, its sub directories and all files under those directories to a new directory path.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

Calling this method will trigger the VirtualDirectoryCopied event.

See Also
| Edit this page View Source

CopyFiles(IEnumerable<string>, string, GorgonCopyCallbackOptions)

Function to copy files to another directory.

Declaration
void CopyFiles(IEnumerable<string> filePaths, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
IEnumerable<string> filePaths

The path to the files to copy.
string destDirectoryPath

The destination directory path that will receive the copied data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method copies a file, or files, to a new directory path.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

Calling this method will trigger the VirtualFileCopied event.

See Also
| Edit this page View Source

CreateDirectory(string)

Function to create a new directory in the writable area on the physical file system.

Declaration
IGorgonVirtualDirectory CreateDirectory(string path)
Parameters
Type Name Description
string path

Path to the directory (or directories) to create.
Returns
Type Description
IGorgonVirtualDirectory

A IGorgonVirtualDirectory representing the final directory in the path.
Remarks

This will create a new directory within the physical file system directory specified by the WriteLocation. If the path contains multiple directories that don't exist (e.g. /Exists/AlsoExists/DoesNotExist/DoesNotExistEither/), then those directories will be created until the path is completely parsed. The file system will be updated to ensure that those directories will exist and can be referenced.

If the directory path contains a name that is the same as a file name within a directory (e.g. /MyDirectory/SomeFile.txt/AnotherDirectory, where SomeFile.txt already exists as a file under MyDirectory), then an exception will be thrown.

If the directory already exists (either in the IGorgonFileSystem or on the physical file system), then nothing will be done and the existing directory will be returned from the method.

Calling this method will trigger the VirtualDirectoryAdded event.

| Edit this page View Source

DeleteDirectory(string, Action<string>, CancellationToken?)

Function to delete a directory from the writeable area with progress functionality.

Declaration
void DeleteDirectory(string path, Action<string> onDelete = null, CancellationToken? cancelToken = null)
Parameters
Type Name Description
string path

The path of the directory to delete.
Action<string> onDelete

[Optional] The callback method to execute when a directory, or file is deleted.
CancellationToken? cancelToken

[Optional] The token used to determine if the operation should be canceled or not.
Remarks

This will delete a directory, its sub directories, and any files under this directory and sub directories. It will remove all references to those files and directories from the FileSystem, and will delete these items from the WriteLocation if they exist in that location.

When a directory is removed from the FileSystem, only the directory in the WriteLocation is physically removed. The items in the other file system mount points will be removed from the mounted directory list(s), but not from the other mount points. That is, anything mounted outside of the write location will be preserved and can be re-added to the directory list(s) by calling Refresh().

This method provides the means to receive feedback during the deletion operation, and a means to cancel the operation. This is useful in cases where a UI is present and a delete operation can take a long time to return to the user. The callback method takes a single string parameter which represents the full path to the directory,subdirectory, or file being deleted.

If the path is set to the root of the file system (/), then the entire file system will be deleted, but the root directory will always remain.

important

When restoring files with Refresh(), only the file system object will be updated. The method will not restore any deleted directories in the WriteLocation.

This method will use the delete callback action passed to the constructor (if supplied) to perform custom deletion of file system items. If no action is provided, then the files and directories deleted by this method are erased and cannot be recovered easily.

Calling this method will trigger the VirtualDirectoryDeleted event.

See Also
| Edit this page View Source

DeleteFile(string)

Function to delete a file from the file system.

Declaration
void DeleteFile(string path)
Parameters
Type Name Description
string path

The path to the file to delete.
Remarks

This will delete a single file from the file system, and physically remove it from the WriteLocation.

When a file is removed from the FileSystem, only the file in the WriteLocation is physically removed. The items in the other file system mount points will be removed from the mounted directory list(s), but not from the other mount point physical locations. That is, anything mounted outside of the write location will be preserved and can be re-added to the directory list(s) by calling Refresh().

important

When restoring files with Refresh(), only the file system object will be updated. The method will not restore any deleted files in the WriteLocation.

This method will use the delete callback action passed to the constructor (if supplied) to perform custom deletion of file system items. If no action is provided, then the files and directories deleted by this method are erased and cannot be recovered easily.

Calling this method will trigger the VirtualFileDeleted event.

| Edit this page View Source

DeleteFiles(IEnumerable<string>, Action<string>, CancellationToken?)

Function to delete multiple files from the file system.

Declaration
void DeleteFiles(IEnumerable<string> paths, Action<string> onDelete = null, CancellationToken? cancelToken = null)
Parameters
Type Name Description
IEnumerable<string> paths

The path to the files to delete.
Action<string> onDelete

[Optional] The callback method to execute when a directory, or file is deleted.
CancellationToken? cancelToken

[Optional] The token used to determine if the operation should be canceled or not.
Remarks

This will delete multiple files from the file system, and physically remove them from the WriteLocation.

This method provides the means to receive feedback during the deletion operation, and a means to cancel the operation. This is useful in cases where a UI is present and a delete operation can take a long time to return to the user. The callback method takes a single string parameter which represents the full path to the file being deleted.

When a file is removed from the FileSystem, only the file in the WriteLocation is physically removed. The items in the other file system mount points will be removed from the mounted directory list(s), but not from the other mount point physical locations. That is, anything mounted outside of the write location will be preserved and can be re-added to the directory list(s) by calling Refresh().

important

When restoring files with Refresh(), only the file system object will be updated. The method will not restore any deleted files in the WriteLocation.

This method will use the delete callback action passed to the constructor (if supplied) to perform custom deletion of file system items. If no action is provided, then the files and directories deleted by this method are erased and cannot be recovered easily.

Calling this method will trigger the VirtualFileDeleted event.

| Edit this page View Source

ExportDirectory(string, string, GorgonCopyCallbackOptions)

Function to export a directory from the virtual file system to a directory on the physical file system.

Declaration
void ExportDirectory(string directoryPath, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
string directoryPath

The path to the directory to export.
string destDirectoryPath

The destination directory path on the physical file system that will receive the exported data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method exports the virtual directory, its sub directories and all files under those directories to a directory on the physical file system.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

See Also
| Edit this page View Source

ExportFiles(IEnumerable<string>, string, GorgonCopyCallbackOptions)

Function to export files from the virtual file system to a directory on the physical file system.

Declaration
void ExportFiles(IEnumerable<string> filePaths, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
IEnumerable<string> filePaths

The path to the files to export.
string destDirectoryPath

The destination directory path on the physical file system that will receive the exported data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method exports the specified files to a directory on the physical file system.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

See Also
| Edit this page View Source

Import(IReadOnlyList<string>, string, GorgonCopyCallbackOptions)

Function to import files/directories from the physical file system to a directory on the virtual file system.

Declaration
void Import(IReadOnlyList<string> paths, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
IReadOnlyList<string> paths

The paths to the files/directories on the physical file system to import.
string destDirectoryPath

The destination directory path in the virtual file system that will receive the imported data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method imports files, and directories from the physical file system into a directory on the virtual file system.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

See Also
| Edit this page View Source

Mount()

Function to mount the directory specified by WriteLocation into the file system.

Declaration
void Mount()
Remarks

This will refresh the FileSystem with the most up to date contents of the WriteLocation by mounting the WriteLocation into the current FileSystem.

important

Users should call this method immediately after creating the object in order to get the contents of the write area into the file system. If this is not called, the file system will not know what files or directories are available in the WriteLocation.

| Edit this page View Source

MoveDirectory(string, string, GorgonCopyCallbackOptions)

Function to move a directory to another directory.

Declaration
void MoveDirectory(string directoryPath, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
string directoryPath

The path to the directory to move.
string destDirectoryPath

The destination directory path that will receive the moved data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method moves a directory, its sub directories and all files under those directories to a new directory path.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

If the directoryPath, and the destDirectoryPath point to the same location, then this method will return immediately without doing anything.

When moving a directory the directoryPath must not be an ancestor of the destDirectoryPath, and the directoryPath must not be the root (/) directory. An exception will be thrown if either condition is true.

Calling this method will trigger the VirtualDirectoryMoved event.

See Also
| Edit this page View Source

MoveFiles(IEnumerable<string>, string, GorgonCopyCallbackOptions)

Function to move files to another directory.

Declaration
void MoveFiles(IEnumerable<string> filePaths, string destDirectoryPath, GorgonCopyCallbackOptions options = null)
Parameters
Type Name Description
IEnumerable<string> filePaths

The path to the files to file.
string destDirectoryPath

The destination directory path that will receive the moved data.
GorgonCopyCallbackOptions options

[Optional] The options used to report progress, support cancelation, etc...
Remarks

This method moves a file, or files, to a new directory path.

When the options parameter is specified, callback methods can be used to show progress of the copy operation, handle file naming conflicts and provide cancellation support. These callbacks are useful in scenarios where a UI component is necessary to show progress, and/or prompts to allow the user to decide on how to handle a file naming conflict when copying files. The cancellation support is useful in an asynchronous scenario where it's desirable to allow the user to cancel the operation, or cancellation is required due to other conditions.

Calling this method will trigger the VirtualFileMoved event.

See Also
| Edit this page View Source

OpenStream(string, FileMode)

Function to open a file for reading or for writing.

Declaration
T OpenStream(string path, FileMode mode)
Parameters
Type Name Description
string path

The path to the file to read/write.
FileMode mode

The mode to determine how to read/write the file.
Returns
Type Description
T

An open FileStream to the file.
Remarks

This will open a file for reading or writing depending on the value passed to the mode parameter. See the FileMode enumeration for more information about how these modes affect the returned Stream.

When the mode parameter is set to Open, or Truncate, and the file does not exist in the FileSystem, then an exception will be thrown.

If the path has a directory, for example /MyDirectory/MyFile.txt, and the directory /MyDirectory does not exist, an exception will be thrown.

Calling this method will trigger the VirtualFileOpened event, and when the file stream is closed the VirtualFileClosed event.

See Also
| Edit this page View Source

RenameDirectory(string, string)

Function to rename a directory.

Declaration
void RenameDirectory(string path, string newName)
Parameters
Type Name Description
string path

The path to the directory to rename.
string newName

The new name of the directory.
Remarks

This will change the name of the specified directory in the path to the name specified by newName. The newName must only contain the name of the directory, and no path information. This newName must also not already exist as a file or directory name in the same path.

Calling this method will trigger the VirtualDirectoryRenamed event.

| Edit this page View Source

RenameFile(string, string)

Function to rename a file.

Declaration
void RenameFile(string path, string newName)
Parameters
Type Name Description
string path

The path to the file to rename.
string newName

The new name of the file.
Remarks

This will change the name of the specified file in the path to the name specified by newName. The newName must only contain the name of the file, and no path information. This newName must also not already exist as a file or directory name in the same path.

Calling this method will trigger the VirtualFileRenamed event.

| Edit this page View Source

Unmount()

Function to unmount the directory specified by WriteLocation from the file system.

Declaration
void Unmount()
Remarks

This will unmount the WriteLocation from the file system. All directories and files for the writable area will be removed from the associated FileSystem.

If another physical file system has files or directories with the same path as one in the write area, then they will be removed from the file system as well since the last mounted file system (including the write area) will override the previous entries. To refresh and retrieve those items from the currently mounted file systems after unmounting the write area, call the Refresh() method.

Events

| Edit this page View Source

FileImported

Event triggered after a physical file is imported into the file system.

Declaration
event EventHandler<FileImportedArgs> FileImported
Event Type
Type Description
EventHandler<FileImportedArgs>
| Edit this page View Source

FileImporting

Event triggered before a phsyical file is imported into the file system.

Declaration
event EventHandler<FileImportingArgs> FileImporting
Event Type
Type Description
EventHandler<FileImportingArgs>
| Edit this page View Source

Imported

Event triggered when directories, and files have been imported.

Declaration
event EventHandler<ImportedEventArgs> Imported
Event Type
Type Description
EventHandler<ImportedEventArgs>
| Edit this page View Source

VirtualDirectoryAdded

Event triggered when a virtual directory has been added to the file system.

Declaration
event EventHandler<VirtualDirectoryAddedEventArgs> VirtualDirectoryAdded
Event Type
Type Description
EventHandler<VirtualDirectoryAddedEventArgs>
| Edit this page View Source

VirtualDirectoryCopied

Event triggered when a virtual directory has been copied.

Declaration
event EventHandler<VirtualDirectoryCopiedMovedEventArgs> VirtualDirectoryCopied
Event Type
Type Description
EventHandler<VirtualDirectoryCopiedMovedEventArgs>
| Edit this page View Source

VirtualDirectoryDeleted

Event triggered when a virtual directory has been deleted from the file system.

Declaration
event EventHandler<VirtualDirectoryDeletedEventArgs> VirtualDirectoryDeleted
Event Type
Type Description
EventHandler<VirtualDirectoryDeletedEventArgs>
| Edit this page View Source

VirtualDirectoryMoved

Event triggered when a virtual directory has been moved.

Declaration
event EventHandler<VirtualDirectoryCopiedMovedEventArgs> VirtualDirectoryMoved
Event Type
Type Description
EventHandler<VirtualDirectoryCopiedMovedEventArgs>
| Edit this page View Source

VirtualDirectoryRenamed

Event triggered when a virtual directory has been renamed.

Declaration
event EventHandler<VirtualDirectoryRenamedEventArgs> VirtualDirectoryRenamed
Event Type
Type Description
EventHandler<VirtualDirectoryRenamedEventArgs>
| Edit this page View Source

VirtualFileClosed

Event triggered when a virtual file has had its write stream closed.

Declaration
event EventHandler<VirtualFileClosedEventArgs> VirtualFileClosed
Event Type
Type Description
EventHandler<VirtualFileClosedEventArgs>
| Edit this page View Source

VirtualFileCopied

Event triggered when virtual files were copied.

Declaration
event EventHandler<VirtualFileCopiedMovedEventArgs> VirtualFileCopied
Event Type
Type Description
EventHandler<VirtualFileCopiedMovedEventArgs>
| Edit this page View Source

VirtualFileDeleted

Event triggered when a virtual file has been deleted from the file system.

Declaration
event EventHandler<VirtualFileDeletedEventArgs> VirtualFileDeleted
Event Type
Type Description
EventHandler<VirtualFileDeletedEventArgs>
| Edit this page View Source

VirtualFileMoved

Event triggered when virtual files were moved.

Declaration
event EventHandler<VirtualFileCopiedMovedEventArgs> VirtualFileMoved
Event Type
Type Description
EventHandler<VirtualFileCopiedMovedEventArgs>
| Edit this page View Source

VirtualFileOpened

Event triggered when a virtual file has been opened for writing on the file system.

Declaration
event EventHandler<VirtualFileOpenedEventArgs> VirtualFileOpened
Event Type
Type Description
EventHandler<VirtualFileOpenedEventArgs>
| Edit this page View Source

VirtualFileRenamed

Event triggered when a virtual file has been renamed.

Declaration
event EventHandler<VirtualFileRenamedEventArgs> VirtualFileRenamed
Event Type
Type Description
EventHandler<VirtualFileRenamedEventArgs>

Extension Methods