TSdlStorage

An abstract interface for filesystem access.

Definition

Unit: Neslib.Sdl3.IO

type TSdlStorage = record ... end;

Properties

Name	Description
IsReady	Whether the storage container is ready to use.
SpaceRemaining	The remaining space in a storage container.

Operators

Name	Description
Equal(TSdlStorage, TSdlStorage)	Used to compare against another TSdlStorage.
Equal(TSdlStorage, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlStorage, TSdlStorage)	Used to compare against another TSdlStorage.
NotEqual(TSdlStorage, Pointer)	Used to compare against nil.

Methods

Name	Description
Close	Alternative to Free.
CopyFile	Copy a file in a writable storage container.
CreateDirectory	Create a directory in a writable storage container.
EnumerateDirectory	Enumerate a directory in the storage container.
Free	Closes and frees the storage container.
GetFileSize	Query the size of a file within a storage container.
GetPathInfo	Get information about a filesystem path in the storage container.
GlobDirectory	Enumerate a directory tree, filtered by pattern, and return a list.
OpenCustom	Opens up a container using a client-provided storage interface.
OpenFile	Opens up a container for local filesystem storage.
OpenTitle(String, TSdlProperties)	Opens up a read-only container for the application's filesystem.
OpenTitle(String)	Opens up a read-only container for the application's filesystem.
OpenUser(String, String, TSdlProperties)	Opens up a container for a user's unique read/write filesystem.
OpenUser(String, String)	Opens up a container for a user's unique read/write filesystem.
PathExists	Checks whether a path in the storage container exists.
ReadFile(String, , Int64)	Synchronously read a file from a storage container into a client-provided buffer.
ReadFile(String)	Synchronously read a file from a storage container.
RemovePath	Remove a file or an empty directory in a writable storage container.
RenamePath	Rename a file or directory in a writable storage container.
WriteFile(String, TBytes)	Synchronously write a file.
WriteFile(String, , Int64)	Synchronously write a file from client memory into a storage container.

Property Descriptions

IsReady

Whether the storage container is ready to use.

This property should be checked at regular intervals until it returns True - however, it is not recommended to spinwait on this call, as the backend may depend on a synchronous message loop. You might instead poll this in your game's main loop while processing events and drawing a loading screen.

property IsReady: Boolean read GetIsReady

Type: Boolean

---

SpaceRemaining

The remaining space in a storage container.

property SpaceRemaining: Int64 read GetSpaceRemaining

Type: Int64

See Also

• IsReady
• WriteFile

---

Operator Descriptions

Equal(TSdlStorage, TSdlStorage)

Used to compare against another TSdlStorage.

class operator Equal(const ALeft, ARight: TSdlStorage): Boolean; inline; static

Parameters

ALeft: TSdlStorage

ARight: TSdlStorage

Returns

Boolean

---

Equal(TSdlStorage, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlStorage; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlStorage

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlStorage; inline; static

Parameters

AValue: Pointer

Returns

TSdlStorage

---

NotEqual(TSdlStorage, TSdlStorage)

Used to compare against another TSdlStorage.

class operator NotEqual(const ALeft, ARight: TSdlStorage): Boolean; inline; static

Parameters

ALeft: TSdlStorage

ARight: TSdlStorage

Returns

Boolean

---

NotEqual(TSdlStorage, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlStorage; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlStorage

ARight: Pointer

Returns

Boolean

---

Method Descriptions

Close

Alternative to Free.

procedure Close; inline

---

CopyFile(String, String)

Copy a file in a writable storage container.

procedure CopyFile(const AOldPath, ANewPath: String); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AOldPath: String : The old path.

ANewPath: String : The new path.

See Also

• IsReady

---

CreateDirectory(String)

Create a directory in a writable storage container.

procedure CreateDirectory(const APath: String); inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The path of the directory to create.

See Also

• IsReady

---

EnumerateDirectory(String)

Enumerate a directory in the storage container.

If APath is empty, this is treated as a request to enumerate the root of the storage container's tree.

function EnumerateDirectory(const APath: String = ''): TArray<TSdlDirectoryEntry>

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String = '' : (Optional) path of the directory to enumerate, or empty (default) for the root.

Returns

TArray<TSdlDirectoryEntry>: An array of all entries in this directory.

See Also

• IsReady

---

Free

Closes and frees the storage container.

procedure Free; inline

Exceptions

ESdlError: Raised on failure.

See Also

• OpenFile
• OpenCustom
• OpenTitle
• OpenUser

---

GetFileSize(String)

Query the size of a file within a storage container.

function GetFileSize(const APath: String): Int64; inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The relative path of the file to query.

Returns

Int64: The file's length.

See Also

• ReadFile
• IsReady

---

GetPathInfo(String)

Get information about a filesystem path in the storage container.

function GetPathInfo(const APath: String): TSdlPathInfo; inline

Exceptions

ESdlError: Raised on failure (e.g. when the file does not exist).

Parameters

APath: String : The path to query.

Returns

TSdlPathInfo: Information about the path.

See Also

• IsReady

---

GlobDirectory(String, String, Boolean)

Enumerate a directory tree, filtered by pattern, and return a list.

Files are filtered out if they don't match the string in APattern, which may contain wildcard characters * (match everything) and ? (match one character). If APattern is empty, 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.

If APath is empty, this is treated as a request to enumerate the root of the storage container's tree.

function GlobDirectory(const APath: String = ''; const APattern: String = ''; const ACaseInsensitive: Boolean = False): TArray<String>

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String = '' : (Optional) path of the directory to enumerate, or empty (default) for the root.

APattern: String = '' : (Optional) pattern that files in the directory must match, or empty to include all results.

ACaseInsensitive: Boolean = False : (Optional) flag whether pattern matching is case-insensitive (default False, meaning case-sensitive).

Returns

TArray<String>: An array of strings.

Remarks

It is safe to call this method from any thread, assuming the storage object is thread-safe.

---

OpenCustom(TSdlStorageInterface, Pointer)

Opens up a container using a client-provided storage interface.

Applications do not need to use this function unless they are providing their own TSdlStorage implementation. If you just need a TSdlStorage, you should use the built-in implementations in SDL, like OpenTitle or OpenUser.

class function OpenCustom(const AInterface: TSdlStorageInterface; const AUserData: Pointer): TSdlStorage; static

Exceptions

ESdlError: Raised on failure.

Parameters

AInterface: TSdlStorageInterface : The interface that implements this storage, initialized using Init.

AUserData: Pointer : The pointer that will be passed to the interface functions.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• SpaceRemaining
• OpenTitle
• OpenUser
• ReadFile
• WriteFile
• IsReady
• TSdlStorageInterface.Init

---

OpenFile(String)

Opens up a container for local filesystem storage.

This is provided for development and tools. Portable applications should use OpenTitle for access to game data and OpenUser for access to user data.

class function OpenFile(const APath: String = ''): TSdlStorage; static

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String = '' : (Optional) base path prepended to all storage paths.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• SpaceRemaining
• OpenTitle
• OpenUser
• ReadFile
• WriteFile

---

OpenTitle(String, TSdlProperties)

Opens up a read-only container for the application's filesystem.

class function OpenTitle(const AOverride: String; const AProps: TSdlProperties): TSdlStorage; overload; static

Exceptions

ESdlError: Raised on failure.

Parameters

AOverride: String : A path to override the backend's default title root.

AProps: TSdlProperties : A property list that may contain backend-specific information.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• OpenUser
• ReadFile

---

OpenTitle(String)

Opens up a read-only container for the application's filesystem.

class function OpenTitle(const AOverride: String = ''): TSdlStorage; overload; static

Exceptions

ESdlError: Raised on failure.

Parameters

AOverride: String = '' : (Optional) path to override the backend's default title root.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• OpenUser
• ReadFile

---

OpenUser(String, String, TSdlProperties)

Opens up a container for a user's unique read/write filesystem.

While title storage can generally be kept open throughout runtime, user storage should only be opened when the client is ready to read/write files. This allows the backend to properly batch file operations and flush them when the container has been closed; ensuring safe and optimal save I/O.

class function OpenUser(const AOrg, AApp: String; const AProps: TSdlProperties): TSdlStorage; overload; static

Exceptions

ESdlError: Raised on failure.

Parameters

AOrg: String : The name of your organization.

AApp: String : The name of your application.

AProps: TSdlProperties : A property list that may contain backend-specific information.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• OpenTitle
• ReadFile
• SpaceRemaining
• IsReady
• WriteFile

---

OpenUser(String, String)

Opens up a container for a user's unique read/write filesystem.

While title storage can generally be kept open throughout runtime, user storage should only be opened when the client is ready to read/write files. This allows the backend to properly batch file operations and flush them when the container has been closed; ensuring safe and optimal save I/O.

class function OpenUser(const AOrg, AApp: String): TSdlStorage; overload; static

Exceptions

ESdlError: Raised on failure.

Parameters

AOrg: String : The name of your organization.

AApp: String : The name of your application.

Returns

TSdlStorage

See Also

• Free
• GetFileSize
• OpenTitle
• ReadFile
• SpaceRemaining
• IsReady
• WriteFile

---

PathExists(String)

Checks whether a path in the storage container exists.

function PathExists(const APath: String): Boolean; inline

Parameters

APath: String : The path to query.

Returns

Boolean: True if the path exists, False otherwise.

See Also

• IsReady

---

ReadFile(String, [untyped], Int64)

Synchronously read a file from a storage container into a client-provided buffer.

The value of ALength must match the length of the file exactly; call GetFileSize to get this value. This behavior may be relaxed in a future release.

procedure ReadFile(const APath: String; var ADestination; const ALength: Int64); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The relative path of the file to read.

ADestination: : A client-provided buffer to read the file into.

ALength: Int64 : The length of the destination buffer.

See Also

• GetFileSize
• IsReady
• WriteFile

---

ReadFile(String)

Synchronously read a file from a storage container.

function ReadFile(const APath: String): TBytes; overload

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The relative path of the file to read.

Returns

TBytes: The file's content.

See Also

• GetFileSize
• IsReady
• WriteFile

---

RemovePath(String)

Remove a file or an empty directory in a writable storage container.

procedure RemovePath(const APath: String); inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The path of the file or directory to remove.

See Also

• IsReady

---

RenamePath(String, String)

Rename a file or directory in a writable storage container.

procedure RenamePath(const AOldPath, ANewPath: String); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AOldPath: String : The old path.

ANewPath: String : The new path.

See Also

• IsReady

---

WriteFile(String, TBytes)

Synchronously write a file.

procedure WriteFile(const APath: String; const ASource: TBytes); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The relative path of the file to write.

ASource: TBytes : The buffer to write from.

See Also

• SpaceRemaining
• ReadFile
• IsReady

---

WriteFile(String, [untyped], Int64)

Synchronously write a file from client memory into a storage container.

procedure WriteFile(const APath: String; const ASource; const ALength: Int64); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

APath: String : The relative path of the file to write.

ASource: : A client-provided buffer to write from.

ALength: Int64 : The length of the source buffer.

See Also

• SpaceRemaining
• ReadFile
• IsReady

---