Table of Contents

Class Storage

Namespace
Sdl3Sharp.IO
Assembly
Sdl3Sharp.dll

A base storage container for abstracting file storage operations

public abstract class Storage : IDisposable
Inheritance
Storage
Implements
Derived
Inherited Members

Remarks

All paths in the Storage API use Unix-style path separators ('/'). Using a different path separator will not work, even if the underlying platform would otherwise accept it. This is to keep code using the Storage API portable between platforms and Storage implementations and simplify app code.

Paths with relative directories ("." and "..") are forbidden by the Storage API.

All valid Unicode strings (discounting the '\0' character and the '/' path separator character) are usable for filenames, however, an underlying Storage implementation may not support particularly strange sequences and refuse to create files with those names.

Constructors

Storage()

Creates a new Storage instance that uses a custom storage implementation provided by the derived class

protected Storage()

Exceptions

SdlException

The custom storage container instance could not be opened (check TryGet(out string?) for more information)

Properties

IsReady

Gets a value indicating whether the storage container is ready to use

public bool IsReady { get; }

Property Value

bool

A value indicating whether the storage container is ready to use

Remarks

The value of this property should be examined in regular intervals until it becomes true. However, it is not recommended to spin-wait on examining this property, as the backend may depend on a synchronous message loop. You might instead poll the value of this property in your app's main loop while processing events and drawing some kind of loading indicator.

IsReadyCore

Gets a value indicating whether the storage container is ready to use

protected abstract bool IsReadyCore { get; }

Property Value

bool

A value indicating whether the storage container is ready to use

Remarks

Supporting this property is optional (just always have to value of this property be true).

See Also

IsValid

Gets a value indicating whether the storage container is valid

public bool IsValid { get; }

Property Value

bool

A value indicating whether the storage container is valid

Remarks

A storage container becomes invalid after it has been closed or disposed.

RemainingSpace

Gets the remaining space, in bytes, in the storage container

public ulong RemainingSpace { get; }

Property Value

ulong

The remaining space, in bytes, in the storage container

RemainingSpaceCore

Gets the remaining space, in bytes, in the storage container

protected abstract ulong RemainingSpaceCore { get; }

Property Value

ulong

The remaining space, in bytes, in the storage container

Remarks

Supporting this property is optional for read-only storage containers (just always have to value of this property be 0).

SdlStorage

Gets a pointer to the underlying SDL SDL_Storage that the Storage represents

public nint SdlStorage { get; }

Property Value

nint

A pointer to the underlying SDL SDL_Storage that the Storage represents. This can be cast to a SDL SDL_Storage*.

Methods

CloseCore()

Closes the storage container and release associated resources

protected abstract bool CloseCore()

Returns

bool

true if the storage container was closed successfully; otherwise, false

See Also

CopyFileCore(string, string)

Copies a file from one path to another within a writable storage container

protected abstract bool CopyFileCore(string oldPath, string newPath)

Parameters

oldPath string

The original file path

newPath string

The new file path

Returns

bool

true, if the file was copied successfully; otherwise, false

Remarks

Supporting this method is optional for read-only storage containers (just always return false).

See Also

CreateDirectoryCore(string)

Creates a directory at the specified path within a writable storage container

protected abstract bool CreateDirectoryCore(string path)

Parameters

path string

The path to the directory to create

Returns

bool

true, if the directory was created successfully; otherwise, false

Remarks

Supporting this method is optional for read-only storage containers (just always return false).

See Also

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool, bool)

Disposes the storage container

protected virtual void Dispose(bool disposing, bool close)

Parameters

disposing bool

A value indicating whether the call came from a call to Dispose() or from the finalizer

close bool

A value indicating whether the storage container should be closed

See Also

EnumerateDirectory(string?)

Enumerates entries for a specified directory path within the storage container

public Storage.DirectoryEnumerable EnumerateDirectory(string? path)

Parameters

path string

The path to the directory to enumerate, or null or the empty string ("") to request the root of the storage container

Returns

Storage.DirectoryEnumerable

A Storage.DirectoryEnumerable that can be used to enumerate the entries for the specified directory path

Remarks

If path is null or the empty string (""), this is treated as a request to enumerate the root of the storage container.

Exceptions

ArgumentNullException

storage is null

EnumerateDirectoryCore(string, EnumerateDirectoryCallback)

Enumerate entries in a directory within the storage container

protected abstract bool EnumerateDirectoryCore(string path, EnumerateDirectoryCallback callback)

Parameters

path string

The path to the directory to enumerate, or the empty string ("") to request the root of the storage container

callback EnumerateDirectoryCallback

The callback to invoke for each entry

Returns

bool

true, if the enumeration was successful; otherwise, false

Remarks

If path is the empty string (""), this should be treated as a request to enumerate the root of the storage container.

Supporting this method is optional for write-only storage containers (just always return false).

See Also

~Storage() 

protected ~Storage()

GetPathInfoCore(string, out PathInfo)

Gets information about a path within the storage container

protected abstract bool GetPathInfoCore(string path, out PathInfo info)

Parameters

path string

The path to get information about

info PathInfo

The information about path

Returns

bool

true, if the information about the path was retrieved successfully; otherwise, false

Remarks

Supporting this method is optional for write-only storage containers (just always return false).

See Also

PathExists(string)

Determines whether a entry exists at a specified path within the storage container

public bool PathExists(string path)

Parameters

path string

The path to the entry

Returns

bool

true, if the entry at path exists; otherwise, false

ReadFileCore(string, NativeMemory)

Reads all the data from a specified file within the storage container

protected abstract bool ReadFileCore(string path, NativeMemory destination)

Parameters

path string

The path to the file, where to read all available data from

destination NativeMemory

The memory buffer to read data into

Returns

bool

true if the data was successfully read into the specified memory buffer; otherwise, false

Remarks

Supporting this method is optional for write-only storage containers (just always return false).

See Also

RemovePathCore(string)

Removes a file or an empty directory at the specified path within a writable storage container

protected abstract bool RemovePathCore(string path)

Parameters

path string

The path to the file or directory to remove

Returns

bool

true, if the file or directory was removed successfully; otherwise, false

Remarks

Supporting this method is optional for read-only storage containers (just always return false).

See Also

RenamePathCore(string, string)

Renames a file or directory from one path to another within a writable storage container

protected abstract bool RenamePathCore(string oldPath, string newPath)

Parameters

oldPath string

The old path to rename

newPath string

The new path

Returns

bool

true, if the file or directory was renamed successfully; otherwise, false

Remarks

Supporting this method is optional for read-only storage containers (just always return false).

See Also

TryClose()

Tries to close the storage container and releases associated resources

public bool TryClose()

Returns

bool

true if the storage container was closed without failure; otherwise, false (check TryGet(out string?) for more information)

Remarks

Note: Even if this method returns false, the storage container is considered closed, its associated resources are released, and the storage container becomes invalid afterwards. The return value is just for informational purposes and you can check TryGet(out string?) for more information.

TryCopyFile(string, string)

Tries to copy a file from one path to another within a writable storage container

public bool TryCopyFile(string oldPath, string newPath)

Parameters

oldPath string

The original file path

newPath string

The new file path

Returns

bool

true, if the file was copied successfully; otherwise, false (check TryGet(out string?) for more information)

See Also

TryCreateDirectory(string)

Tries to create a directory at the specified path within a writable storage container

public bool TryCreateDirectory(string path)

Parameters

path string

The path to the directory to create

Returns

bool

true, if the directory was created successfully; otherwise, false (check TryGet(out string?) for more information)

See Also

TryEnumerateDirectory(string?, EnumerateDirectoryCallback)

Tries to enumerate entries in a directory within the storage container

public bool TryEnumerateDirectory(string? path, EnumerateDirectoryCallback callback)

Parameters

path string

The path to the directory to enumerate, or null or the empty string ("") to request the root of the storage container

callback EnumerateDirectoryCallback

The callback to invoke for each entry

Returns

bool

true, if the enumeration was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method will continue enumerating entries until all entries have been enumerated, or until the provided callback returns either Success or Failure.

This method will return false, if there was an error in general, or if the provided callback returned Failure. A return value of true indicates that all entries were enumerated successfully, or that the provided callback returned Success.

If path is null or the empty string (""), this is treated as a request to enumerate the root of the storage container.

Exceptions

ArgumentNullException

callback is null

See Also

TryGetFileLength(string, out ulong)

Tries to get the size, in bytes, of a file within the storage container

public bool TryGetFileLength(string path, out ulong length)

Parameters

path string

The path to the file to get the size of

length ulong

The size of the file, in bytes

Returns

bool

true, if the size was retrieved successfully; otherwise, false (check TryGet(out string?) for more information)

TryGetPathInfo(string, out PathInfo)

Tries to get information about a path within the storage container

public bool TryGetPathInfo(string path, out PathInfo info)

Parameters

path string

The path to get information about

info PathInfo

The information about path

Returns

bool

true, if the information about the path was retrieved successfully; otherwise, false (check TryGet(out string?) for more information)

See Also

TryGlobDirectory(string?, string?, GlobFlags, out string[]?)

Tries to enumerate entries in a directory within the storage container, filtered by a pattern

public bool TryGlobDirectory(string? path, string? pattern, GlobFlags flags, out string[]? matches)

Parameters

path string

The path to the directory to enumerate, or null or the empty string ("") to request the root of the storage container

pattern string

The pattern that entries must match. Can be null to not filter at all.

flags GlobFlags

Flags to modify the pattern matching behavior

matches string[]

The matching entries, when this method returns true; otherwise, null

Returns

bool

true, if the directory was successfully enumerated and entries were filtered; otherwise, false (check TryGet(out string?) for more information)

Remarks

Entries are filtered out if they don't match the pattern, which may contain wildcard characters '*' (match everything) and '?' (match one character). If pattern is null, no filtering is done and all results are returned. Subdirectories are permitted, and are specified with a path separator of '/'. Wildcard characters '*' and '?' never match a path separator.

flags may be set to CaseInsensitive to make the pattern matching case-insensitive.

If path is null or the empty string (""), this is treated as a request to enumerate the root of the storage container.

See Also

TryReadFile(string, NativeMemory)

Tries to synchronously read all the data from a specified file within the storage container

public bool TryReadFile(string path, NativeMemory destination)

Parameters

path string

The path to the file, where to read all available data from

destination NativeMemory

The memory buffer to read data into

Returns

bool

true if the data was successfully read into the specified memory buffer; otherwise, false (check TryGet(out string?) for more information)

Remarks

The value of the destination's Length property must match the length of the file exactly. You can use TryGetFileLength(string, out ulong) to get the length of the file. This behavior may be relaxed in a future release.

TryReadFile(string, Span<byte>)

Tries to read all the data from a specified file within the storage container

public bool TryReadFile(string path, Span<byte> destination)

Parameters

path string

The path to the file, where to read all available data from

destination Span<byte>

The Span<T> to read data into

Returns

bool

true if the data was successfully read into the specified Span<T>; otherwise, false (check TryGet(out string?) for more information)

Remarks

The value of the destination's Length property must match the length of the file exactly. You can use TryGetFileLength(string, out ulong) to get the length of the file. This behavior may be relaxed in a future release.

TryReadFile(string, void*, ulong)

Tries to read all the data from a specified file within the storage container

public bool TryReadFile(string path, void* destination, ulong length)

Parameters

path string

The path to the file, where to read all available data from

destination void*

A pointer to the unmananged memory to read data into

length ulong

The length of the destination buffer

Returns

bool

true if the data was successfully read into the specified unmanaged memory; otherwise, false (check TryGet(out string?) for more information)

Remarks

The length of the destination buffer must match the length of the file exactly. You can use TryGetFileLength(string, out ulong) to get the length of the file. This behavior may be relaxed in a future release.

TryRemovePath(string)

Tries to remove a file or an empty directory at the specified path within a writable storage container

public bool TryRemovePath(string path)

Parameters

path string

The path to the file or directory to remove

Returns

bool

true, if the file or directory was removed successfully; otherwise, false (check TryGet(out string?) for more information)

See Also

TryRenamePath(string, string)

Tries to rename a file or directory from one path to another within a writable storage container

public bool TryRenamePath(string oldPath, string newPath)

Parameters

oldPath string

The old path to rename

newPath string

The new path

Returns

bool

true, if the file or directory was renamed successfully; otherwise, false (check TryGet(out string?) for more information)

See Also

TryWriteFile(string, ReadOnlyNativeMemory)

Tries to synchronously write all specified data into a specified file within a writable storage container

public bool TryWriteFile(string path, ReadOnlyNativeMemory source)

Parameters

path string

The path to the file, where to write all available data into

source ReadOnlyNativeMemory

The memory buffer containing all the data to be written into the file

Returns

bool

true if the data from the specified memory buffer was successfully written into the file; otherwise, false (check TryGet(out string?) for more information)

TryWriteFile(string, ReadOnlySpan<byte>)

Tries to synchronously write all specified data into a specified file within a writable storage container

public bool TryWriteFile(string path, ReadOnlySpan<byte> source)

Parameters

path string

The path to the file, where to write all available data into

source ReadOnlySpan<byte>

The Span<T> containing all the data to be written into the file

Returns

bool

true if the data from the specified Span<T> was successfully written into the file; otherwise, false (check TryGet(out string?) for more information)

TryWriteFile(string, void*, ulong)

Tries to synchronously write all specified data into a specified file within a writable storage container

public bool TryWriteFile(string path, void* source, ulong length)

Parameters

path string

The path to the file, where to write all available data into

source void*

A pointer to the unmanaged memory containing all the data to be written into the file

length ulong

The length of the source buffer

Returns

bool

true if the data from the specified unmanaged memory was successfully written into the file; otherwise, false (check TryGet(out string?) for more information)

Remarks

The unmanaged memory pointed to by source must be safely dereferencable for at least length bytes.

WriteFileCore(string, ReadOnlyNativeMemory)

Writes all specified data into a specified file within a writable storage container

protected abstract bool WriteFileCore(string path, ReadOnlyNativeMemory source)

Parameters

path string

The path to the file, where to write all available data into

source ReadOnlyNativeMemory

The memory buffer containing all the data to be written into the file

Returns

bool

true if the data from the specified memory buffer was successfully written into the file; otherwise, false

Remarks

Supporting this method is optional for read-only storage containers (just always return false).

See Also