An abstract interface for filesystem access. More...

Inheritance diagram for SDL::StorageRef:

Public Member Functions
bool	Ready () const
	Checks if the storage container is ready to use.

std::optional< Uint64 >	GetFileSize (StringParam path) const
	Query the size of a file within a storage container.

std::string	ReadFile (StringParam path) const
	Synchronously read a file from a storage container into a client-provided buffer.

bool	ReadFile (StringParam path, TargetBytes destination) const
	Synchronously read a file from a storage container into a client-provided buffer.

template<class T >
std::vector< T >	ReadFileAs (StringParam path) const
	Synchronously read a file from a storage container into a client-provided buffer.

void	WriteFile (StringParam path, SourceBytes source)
	Synchronously write a file from client memory into a storage container.

void	CreateDirectory (StringParam path)
	Create a directory in a writable storage container.

std::vector< Path >	EnumerateDirectory (StringParam path)
	Enumerate a directory.

void	EnumerateDirectory (StringParam path, EnumerateDirectoryCB callback)
	Enumerate a directory in a storage container through a callback function.

void	EnumerateDirectory (StringParam path, EnumerateDirectoryCallback callback, void *userdata)
	Enumerate a directory in a storage container through a callback function.

void	RemovePath (StringParam path)
	Remove a file or an empty directory in a writable storage container.

void	RenamePath (StringParam oldpath, StringParam newpath)
	Rename a file or directory in a writable storage container.

void	CopyFile (StringParam oldpath, StringParam newpath)
	Copy a file in a writable storage container.

PathInfo	GetPathInfo (StringParam path) const
	Get information about a filesystem path in a storage container.

Uint64	GetSpaceRemaining () const
	Queries the remaining space in a storage container.

OwnArray< char * >	GlobDirectory (StringParam path, StringParam pattern, GlobFlags flags)
	Enumerate a directory tree, filtered by pattern, and return a list.

constexpr	Resource (T resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

Public Member Functions inherited from SDL::Resource< SDL_Storage * >
constexpr	Resource (SDL_Storage * resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< SDL_Storage * > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

constexpr	operator bool () const
	True if contains a valid resource.

constexpr	operator value_type () const
	Converts back to underlying type.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_Storage *	get () const
	Return contained resource;.

constexpr const SDL_Storage *	operator-> () const
	Access to fields.

constexpr SDL_Storage *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_Storage *resource)
	Closes and frees a storage container.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Storage * >
using	value_type = SDL_Storage *
	The raw resource type.

Detailed Description

This is an opaque datatype. One can create this object using standard SDL functions like Storage.OpenTitle or Storage.OpenUser, etc, or create an object with a custom implementation using Storage.Open.

Since: This struct is available since SDL 3.2.0.

Category:: Resource

See also: Storage

Member Function Documentation

◆ CopyFile()

void SDL::StorageRef::CopyFile	(	StringParam	oldpath,
		StringParam	newpath
	)

inline

Parameters

oldpath	the old path.
newpath	the new path.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ CreateDirectory()

void SDL::StorageRef::CreateDirectory ( StringParam path )

inline

Parameters

path	the path of the directory to create.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ EnumerateDirectory() [1/3]

std::vector< Path > SDL::StorageRef::EnumerateDirectory ( StringParam path )

inline

Parameters

path	the path of the directory to enumerate.

Returns: all the directory contents.

Since: This function is available since SDL 3.2.0.

◆ EnumerateDirectory() [2/3]

void SDL::StorageRef::EnumerateDirectory	(	StringParam	path,
		EnumerateDirectoryCallback	callback,
		void *	userdata
	)

inline

This function provides every directory entry through an app-provided callback, called once for each directory entry, until all results have been provided or the callback returns either ENUM_SUCCESS or ENUM_FAILURE.

This will return false if there was a system problem in general, or if a callback returns ENUM_FAILURE. A successful return means a callback returned ENUM_SUCCESS to halt enumeration, or all directory entries were enumerated.

If path is nullptr, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this.

Parameters

path	the path of the directory to enumerate, or nullptr for the root.
callback	a function that is called for each entry in the directory.
userdata	a pointer that is passed to `callback`.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ EnumerateDirectory() [3/3]

void SDL::StorageRef::EnumerateDirectory	(	StringParam	path,
		EnumerateDirectoryCB	callback
	)

inline

This function provides every directory entry through an app-provided callback, called once for each directory entry, until all results have been provided or the callback returns either ENUM_SUCCESS or ENUM_FAILURE.

This will return false if there was a system problem in general, or if a callback returns ENUM_FAILURE. A successful return means a callback returned ENUM_SUCCESS to halt enumeration, or all directory entries were enumerated.

If path is nullptr, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this.

Parameters

path	the path of the directory to enumerate, or nullptr for the root.
callback	a function that is called for each entry in the directory.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ GetFileSize()

std::optional< Uint64 > SDL::StorageRef::GetFileSize ( StringParam path ) const

inline

Parameters

path	the relative path of the file to query.

Returns: the file's length on success or 0 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.ReadFile; StorageRef.Ready

◆ GetPathInfo()

PathInfo SDL::StorageRef::GetPathInfo ( StringParam path ) const

inline

Parameters

path	the path to query.

Returns: the info on success or false if the file doesn't exist, or another failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ GetSpaceRemaining()

Uint64 SDL::StorageRef::GetSpaceRemaining ( ) const

inline

Returns: the amount of remaining space, in bytes.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready; StorageRef.WriteFile

◆ GlobDirectory()

OwnArray< char * > SDL::StorageRef::GlobDirectory	(	StringParam	path,
		StringParam	pattern,
		GlobFlags	flags
	)

inline

Files are filtered out if they don't match the string in pattern, which may contain wildcard characters * (match everything) and ? (match one character). If pattern is nullptr, 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 GLOB_CASEINSENSITIVE to make the pattern matching case-insensitive.

The returned array is always nullptr-terminated, for your iterating convenience, but if count is non-nullptr, on return it will contain the number of items in the array, not counting the nullptr terminator.

If path is nullptr, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this.

Parameters

path	the path of the directory to enumerate, or nullptr for the root.
pattern	the pattern that files in the directory must match. Can be nullptr.
flags	`SDL_GLOB_*` bitflags that affect this search.

Returns: an array of strings on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, assuming the storage object is thread-safe.

Since: This function is available since SDL 3.2.0.

◆ ReadFile() [1/2]

std::string SDL::StorageRef::ReadFile ( StringParam path ) const

inline

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

Parameters

path	the relative path of the file to read.

Returns: the content if the file was read or empty string on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.GetFileSize; StorageRef.Ready; StorageRef.WriteFile

◆ ReadFile() [2/2]

bool SDL::StorageRef::ReadFile	(	StringParam	path,
		TargetBytes	destination
	)		const

inline

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

Parameters

path	the relative path of the file to read.
destination	a client-provided buffer to read the file into.

Returns: true if the file was read or false on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.GetFileSize; StorageRef.Ready; StorageRef.WriteFile

◆ ReadFileAs()

template<class T >

std::vector< T > SDL::StorageRef::ReadFileAs ( StringParam path ) const

inline

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

Parameters

path	the relative path of the file to read.

Returns: the content if the file was read or empty string on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.GetFileSize; StorageRef.Ready; StorageRef.WriteFile

◆ Ready()

bool SDL::StorageRef::Ready ( ) const

inline

This function should be called in 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.

Returns: true if the container is ready, false otherwise.

Since: This function is available since SDL 3.2.0.

◆ RemovePath()

void SDL::StorageRef::RemovePath ( StringParam path )

inline

Parameters

path	the path of the directory to enumerate.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ RenamePath()

void SDL::StorageRef::RenamePath	(	StringParam	oldpath,
		StringParam	newpath
	)

inline

Parameters

oldpath	the old path.
newpath	the new path.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Ready

◆ reset()

static void SDL::StorageRef::reset ( SDL_Storage * resource )

inlinestatic

Parameters

resource a storage container to close.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: Storage.OpenFile; Storage.Open; Storage.OpenTitle; Storage.OpenUser

◆ WriteFile()

void SDL::StorageRef::WriteFile	(	StringParam	path,
		SourceBytes	source
	)

inline

Parameters

path	the relative path of the file to write.
source	a client-provided buffer to write from.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.GetSpaceRemaining; StorageRef.ReadFile; StorageRef.Ready

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_storage.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ CopyFile()

◆ CreateDirectory()

◆ EnumerateDirectory() [1/3]

◆ EnumerateDirectory() [2/3]

◆ EnumerateDirectory() [3/3]

◆ GetFileSize()

◆ GetPathInfo()

◆ GetSpaceRemaining()

◆ GlobDirectory()

◆ ReadFile() [1/2]

◆ ReadFile() [2/2]

◆ ReadFileAs()

◆ Ready()

◆ RemovePath()

◆ RenamePath()

◆ reset()

◆ WriteFile()