Interface IIndelibleDirectory

Represents the root of a Directory that can not be deleted, where each file that is access through a directory is associated with a GUID in the directory's manifest.

When files are moved between IDirectories, the files GUID is preserved. Thus, metadata can be preserved throughout.

Namespace: Snowflake.Filesystem

Assembly: Snowflake.Framework.Primitives.dll

Syntax

public interface IIndelibleDirectory

Properties

Name

Gets the name of the directory

Declaration

string Name { get; }

Property Value

Type	Description
System.String

Methods

AsReadOnly()

Returns a read only view over this directory.

Declaration

IReadOnlyDirectory AsReadOnly()

Returns

Type	Description
IReadOnlyDirectory	A read only view over this directory.

ContainsDirectory(String)

Whether or not this directory contains directory as a direct child. full path, this will truncate the path using System.IO.Path.GetDirectoryName(System.String)

Declaration

bool ContainsDirectory(string directory)

Parameters

Type	Name	Description
System.String	directory	The name of the directory to check.

Returns

Type	Description
System.Boolean	Whether or not this directory contains the given directory.

ContainsFile(String)

Whether or not this directory contains a file in its manifest. If provided a full path, this will truncate the path using System.IO.Path.GetFileName(System.String)

Declaration

bool ContainsFile(string file)

Parameters

Type	Name	Description
System.String	file	The name of the file to check.

Returns

Type	Description
System.Boolean	Whether or not this directory contains the given file.

CopyFrom(IReadOnlyFile)

Copies a file from a IFile from another IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

Declaration

IFile CopyFrom(IReadOnlyFile source)

Parameters

Type	Name	Description
IReadOnlyFile	source	The System.IO.FileInfo

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFrom(IReadOnlyFile, Boolean)

Copies a file from a IFile from another IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

Declaration

IFile CopyFrom(IReadOnlyFile source, bool overwrite)

Parameters

Type	Name	Description
IReadOnlyFile	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFrom(FileInfo)

Copies a file from an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Do not use this method to copy from a managed IDirectory. Instead, use CopyFrom(IReadOnlyFile).

Declaration

IFile CopyFrom(FileInfo source)

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFrom(FileInfo, Boolean)

Copies a file from an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Do not use this method to copy from a managed IDirectory. Instead, use CopyFrom(IReadOnlyFile).

Declaration

IFile CopyFrom(FileInfo source, bool overwrite)

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFromAsync(IReadOnlyFile, Boolean, CancellationToken)

Copies a file asynchronously from a IFile from another IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

Declaration

Task<IFile> CopyFromAsync(IReadOnlyFile source, bool overwrite, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
IReadOnlyFile	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory
System.Threading.CancellationToken	cancellation	Cancellation token for the asynchronous task.

Returns

Type	Description
System.Threading.Tasks.Task<IFile>	The IReadOnlyFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFromAsync(IReadOnlyFile, CancellationToken)

Copies a file asynchronously from a IFile from another IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

Declaration

Task<IFile> CopyFromAsync(IReadOnlyFile source, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
IReadOnlyFile	source	The System.IO.FileInfo
System.Threading.CancellationToken	cancellation	Cancellation token for the asynchronous task.

Returns

Type	Description
System.Threading.Tasks.Task<IFile>	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFromAsync(FileInfo, Boolean, CancellationToken)

Copies a file asynchronously from an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Do not use this method to copy from a managed IDirectory. Instead, use CopyFrom(IReadOnlyFile).

Declaration

Task<IFile> CopyFromAsync(FileInfo source, bool overwrite, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory
System.Threading.CancellationToken	cancellation	A cancellation token that is forwarded to the underlying System.Threading.Tasks.Task<TResult>.

Returns

Type	Description
System.Threading.Tasks.Task<IFile>	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

CopyFromAsync(FileInfo, CancellationToken)

Copies a file asynchronously from an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Do not use this method to copy from a managed IDirectory. Instead, use .

Declaration

Task<IFile> CopyFromAsync(FileInfo source, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo
System.Threading.CancellationToken	cancellation	A cancellation token that is forwarded to the underlying System.Threading.Tasks.Task<TResult>.

Returns

Type	Description
System.Threading.Tasks.Task<IFile>	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

EnumerateDirectories()

Enumerates all direct child directories of this IDirectory.

Declaration

IEnumerable<IDirectory> EnumerateDirectories()

Returns

Type	Description
System.Collections.Generic.IEnumerable<IDirectory>	All direct children directories.

EnumerateFiles()

Enumerates all files in this directory,

Declaration

IEnumerable<IFile> EnumerateFiles()

Returns

Type	Description
System.Collections.Generic.IEnumerable<IFile>	All direct children files.

EnumerateFilesRecursive()

Recursively enumerates all files that are contained in this directory.

This method is usually implemented as a Breadth-first search, but no order is guaranteed.

Declaration

IEnumerable<IFile> EnumerateFilesRecursive()

Returns

Type	Description
System.Collections.Generic.IEnumerable<IFile>	All files contained within this directory, including descendant subfolders.

LinkFrom(FileInfo)

Creates a link to an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Links are akin to shortcuts more than symbolic links, being represented as a text file with a real file path to another file on the file system. Do not ever link to another IFile. Instead, use CopyFrom(IReadOnlyFile).

Links are transparent, i.e. OpenStream() will open a stream to the linked file, and UnsafeGetFilePath() will return the path of the linked file. The path of the shortcut remains inaccessible except for the internal method Snowflake.Filesystem.IReadOnlyFile.UnsafeGetFilePointerPath. IDirectory methods like CopyFrom(IReadOnlyFile) and MoveFrom(IFile) work as expected.

Links differ semantically from Files in two ways: IsLink is always true for links, and always false for Files, and OpenStream() on a non existing file throws System.IO.FileNotFoundException instead of creating a new file. The reasoning behind throwing an exception is that links should always point to a real file on the filesystem, and not be used as a method to escape the directory jail (although OpenStream(FileMode, FileAccess, FileShare) will work as expected. The intended action when encountering a broken link is not to create a new file, but instead to repair the link by recreating it with LinkFrom(FileInfo).

The underlying file that a link points to can only be modified through the stream. Calling Delete() or Rename(String) will only rename or delete the link. If the file the link points to does not exist, calling OpenStream() will throw System.IO.FileNotFoundException.

Links are very powerful and allow a way for plugins to escape the filesystem jail that an IDirectory creates. Because they present the potential to modify files outside of the allocated directory, be very careful when using them. Prefer read-only access by using AsReadOnly() whenever possible.

Declaration

IFile LinkFrom(FileInfo source)

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

LinkFrom(FileInfo, Boolean)

Creates a link to an unmanaged System.IO.FileInfo that exists outside of a IDirectory. Links are akin to shortcuts more than symbolic links, being represented as a text file with a real file path to another file on the file system. Do not ever link to another IFile. Instead, use CopyFrom(IReadOnlyFile).

Links are transparent, i.e. OpenStream() will open a stream to the linked file, and UnsafeGetFilePath() will return the path of the linked file. The path of the shortcut remains inaccessible except for the internal method Snowflake.Filesystem.IReadOnlyFile.UnsafeGetFilePointerPath. IDirectory methods like CopyFrom(IReadOnlyFile) and MoveFrom(IFile) work as expected.

Links differ semantically from Files in two ways: IsLink is always true for links, and always false for Files, and OpenStream() on a non existing file throws System.IO.FileNotFoundException instead of creating a new file. The reasoning behind throwing an exception is that links should always point to a real file on the filesystem, and not be used as a method to escape the directory jail (although OpenStream(FileMode, FileAccess, FileShare) will work as expected. The intended action when encountering a broken link is not to create a new file, but instead to repair the link by recreating it with LinkFrom(FileInfo, Boolean)

The underlying file that a link points to can only be modified through the stream. Calling Delete() or Rename(String) will only rename or delete the link. If the file the link points to does not exist, calling OpenStream() will throw System.IO.FileNotFoundException.

Links are very powerful and allow a way for plugins to escape the filesystem jail that an IDirectory creates. Because they present the potential to modify files outside of the allocated directory, be very careful when using them. Prefer read-only access by using AsReadOnly() whenever possible.

Declaration

IFile LinkFrom(FileInfo source, bool overwrite)

Parameters

Type	Name	Description
System.IO.FileInfo	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory. The new link will inherit the GUID of the previously existing file.

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

MoveFrom(IFile)

Moves a file between IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

The source file will cease to exist in its original IDirectory.

There is no asychronous equivalent by design, since MoveFrom(IFile, Boolean) is intended to be faster than CopyFromAsync(IReadOnlyFile, CancellationToken) if the IDirectory instances are on the same file system. Otherwise, you should use CopyFromAsync(IReadOnlyFile, CancellationToken), then Delete() the old file.

Declaration

IFile MoveFrom(IFile source)

Parameters

Type	Name	Description
IFile	source	The System.IO.FileInfo

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination.
System.IO.FileNotFoundException	If the source file can not be found.

MoveFrom(IFile, Boolean)

Moves a file between IDirectory, updating the manifests such that the resulting file has the same FileGuid as the source file.

The source file will cease to exist in its original IDirectory.

There is no asychronous equivalent by design, since MoveFrom(IFile, Boolean) is intended to be faster than CopyFromAsync(IReadOnlyFile, Boolean, CancellationToken) if the IDirectory instances are on the same file system. Otherwise, you should use CopyFromAsync(IReadOnlyFile, Boolean, CancellationToken), then Delete() the old file.

Declaration

IFile MoveFrom(IFile source, bool overwrite)

Parameters

Type	Name	Description
IFile	source	The System.IO.FileInfo
System.Boolean	overwrite	Overwrite the file if it already exists in this IDirectory

Returns

Type	Description
IFile	The IFile that describes the file in the current IDirectory.

Exceptions

Type	Condition
System.IO.IOException	If a file with the same name exists in the target destination and overwrite is false.
System.IO.FileNotFoundException	If the source file can not be found.

OpenDirectory(String)

Opens an existing descendant directory with the given name. If the directory does not exist, creates the directory. You can open a nested directory using '/' as the path separator, and it will be created relative to this current directory.

Declaration

IDirectory OpenDirectory(string name)

Parameters

Type	Name	Description
System.String	name	The name of the existing directory

Returns

Type	Description
IDirectory	The directory if it exists, or null if it does not.

OpenFile(String)

Opens or creates a file, adding it to the manifest and assigning it a unique System.Guid.

Unlike OpenDirectory(String), you can not use the path separator to open a nested file. Paths will be truncated with System.IO.Path.GetFileName(System.String).

Instead, use OpenDirectory(String) to open the directory of the desired file, then call OpenFile(String) on the returned instance.

Keep in mind this does not actually create a file on the underlying file system. However, you can use OpenStream() and friends to create the file if it does not yet exist.

Declaration

IFile OpenFile(string file)

Parameters

Type	Name	Description
System.String	file	The name of the file. If this is a path, will be truncated with System.IO.Path.GetFileName(System.String)

Returns

Type	Description
IFile	An object that associates a given file with a with a unique System.Guid

UnsafeGetPath()

Gets the underlying System.IO.DirectoryInfo where files are contained.

This is very rarely necessary, and most IO tasks can be done efficiently and safely using the provided API. Manipulating the underlying file system will potentially desync the manifest, and cause loss of associated metadata.

Declaration

[Obsolete("Avoid accessing the underlying file path, and use the object methods instead.")]
DirectoryInfo UnsafeGetPath()

Returns

Type	Description
System.IO.DirectoryInfo	The underlying System.IO.DirectoryInfo where files are contained.

Extension Methods

DirectoryExtensions.CopyFromDirectory(IIndelibleDirectory, IIndelibleDirectory)

DirectoryExtensions.CopyFromDirectory(IIndelibleDirectory, IIndelibleDirectory, Boolean)