An abstract interface for filesystem access. More...

Inheritance diagram for SDL::StorageBase:

[legend]

Public Member Functions
	StorageBase (StringParam override, PropertiesBase &props)
	Opens up a read-only container for the application's filesystem.

	StorageBase (StringParam org, StringParam app, PropertiesBase &props)
	Opens up a container for a user's unique read/write filesystem.

	StorageBase (StringParam path)
	Opens up a container for local filesystem storage.

	StorageBase (const StorageInterface &iface, void *userdata)
	Opens up a container using a client-provided storage interface.

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 the underlying resource.

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

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

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

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

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

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

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

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

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 SDL_Storage *	release (SDL_Storage * newResource={})
	Return contained resource and empties or replace value.

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

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

Detailed Description

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

Since: This struct is available since SDL 3.2.0.

Category:: Resource

See also: Storage; StorageRef

Constructor & Destructor Documentation

◆ StorageBase() [1/4]

SDL::StorageBase::StorageBase	(	StringParam	override,
		PropertiesBase &	props
	)

inline

Parameters

override	a path to override the backend's default title root.
props	a property list that may contain backend-specific information.

Postcondition: a title storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageRef.Close; StorageBase.GetFileSize; StorageBase.StorageBase; StorageBase.ReadFile

◆ StorageBase() [2/4]

SDL::StorageBase::StorageBase	(	StringParam	org,
		StringParam	app,
		PropertiesBase &	props
	)

inline

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.

Parameters

org	the name of your organization.
app	the name of your application.
props	a property list that may contain backend-specific information.

Postcondition: a user storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageBase.GetFileSize; StorageBase.GetSpaceRemaining; StorageBase.StorageBase; StorageBase.ReadFile; StorageBase.Ready; StorageBase.WriteFile

◆ StorageBase() [3/4]

SDL::StorageBase::StorageBase ( StringParam path )

inline

This is provided for development and tools. Portable applications should use StorageBase.StorageBase() for access to game data and StorageBase.StorageBase() for access to user data.

Parameters

path	the base path prepended to all storage paths, or nullptr for no base path.

Postcondition: a filesystem storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageBase.GetFileSize; StorageBase.GetSpaceRemaining; StorageBase.StorageBase; StorageBase.StorageBase; StorageBase.ReadFile; StorageBase.WriteFile

◆ StorageBase() [4/4]

SDL::StorageBase::StorageBase	(	const StorageInterface &	iface,
		void *	userdata
	)

inline

Applications do not need to use this function unless they are providing their own StorageBase implementation. If you just need an StorageBase, you should use the built-in implementations in SDL, like StorageBase.StorageBase() or StorageBase.StorageBase().

This function makes a copy of iface and the caller does not need to keep it around after this call.

Parameters

iface	the interface that implements this storage, initialized using SDL_INIT_INTERFACE().
userdata	the pointer that will be passed to the interface functions.

Postcondition: a storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageBase.GetFileSize; StorageBase.GetSpaceRemaining; SDL_INIT_INTERFACE; StorageBase.ReadFile; StorageBase.Ready; StorageBase.WriteFile

Member Function Documentation

◆ CopyFile()

void SDL::StorageBase::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: StorageBase.Ready

◆ CreateDirectory()

void SDL::StorageBase::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: StorageBase.Ready

◆ EnumerateDirectory() [1/3]

std::vector< Path > SDL::StorageBase::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::StorageBase::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: StorageBase.Ready

◆ EnumerateDirectory() [3/3]

void SDL::StorageBase::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: StorageBase.Ready

◆ GetFileSize()

std::optional< Uint64 > SDL::StorageBase::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: StorageBase.ReadFile; StorageBase.Ready

◆ GetPathInfo()

PathInfo SDL::StorageBase::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: StorageBase.Ready

◆ GetSpaceRemaining()

Uint64 SDL::StorageBase::GetSpaceRemaining ( ) const

inline

Returns: the amount of remaining space, in bytes.

Since: This function is available since SDL 3.2.0.

See also: StorageBase.Ready; StorageBase.WriteFile

◆ GlobDirectory()

OwnArray< char * > SDL::StorageBase::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::StorageBase::ReadFile ( StringParam path ) const

inline

The value of length must match the length of the file exactly; call StorageBase.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: StorageBase.GetFileSize; StorageBase.Ready; StorageBase.WriteFile

◆ ReadFile() [2/2]

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

inline

The value of length must match the length of the file exactly; call StorageBase.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: StorageBase.GetFileSize; StorageBase.Ready; StorageBase.WriteFile

◆ ReadFileAs()

template<class T >

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

inline

The value of length must match the length of the file exactly; call StorageBase.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: StorageBase.GetFileSize; StorageBase.Ready; StorageBase.WriteFile

◆ Ready()

bool SDL::StorageBase::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::StorageBase::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: StorageBase.Ready

◆ RenamePath()

void SDL::StorageBase::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: StorageBase.Ready

◆ WriteFile()

void SDL::StorageBase::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: StorageBase.GetSpaceRemaining; StorageBase.ReadFile; StorageBase.Ready

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

SDL3pp/SDL3pp_storage.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StorageBase() [1/4]

◆ StorageBase() [2/4]

◆ StorageBase() [3/4]

◆ StorageBase() [4/4]

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()

◆ WriteFile()