The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level (in SDL's case, this sits on top of the [Filesystem](CategoryFilesystem) and [IOStream](CategoryIOStream) subsystems). More...

Classes
struct	SDL::StorageBase
	Base class to Storage. More...
struct	SDL::Storage
	An abstract interface for filesystem access. More...

Typedefs
using	SDL::StorageRaw = SDL_Storage*
	Alias to raw representation for Storage.
using	SDL::StorageRef = ResourceRefT<StorageBase>
	Reference for Storage.
using	SDL::StorageInterface = SDL_StorageInterface
	Function interface for Storage.

Functions
Storage	SDL::OpenTitleStorage (StringParam override, PropertiesRef props)
	Opens up a read-only container for the application's filesystem.
Storage	SDL::OpenUserStorage (StringParam org, StringParam app, PropertiesRef props)
	Opens up a container for a user's unique read/write filesystem.
Storage	SDL::OpenFileStorage (StringParam path)
	Opens up a container for local filesystem storage.
Storage	SDL::OpenStorage (const StorageInterface &iface, void *userdata)
	Opens up a container using a client-provided storage interface.
bool	SDL::CloseStorage (StorageRaw storage)
	Closes and frees a storage container.
bool	SDL::StorageReady (StorageRef storage)
	Checks if the storage container is ready to use.
std::optional< Uint64 >	SDL::GetStorageFileSize (StorageRef storage, StringParam path)
	Query the size of a file within a storage container.
bool	SDL::ReadStorageFile (StorageRef storage, StringParam path, TargetBytes destination)
	Synchronously read a file from a storage container into a client-provided buffer.
std::string	SDL::ReadStorageFile (StorageRef storage, StringParam path)
	Synchronously read a file from a storage container into a client-provided buffer.
template<class T>
std::vector< T >	SDL::ReadStorageFileAs (StorageRef storage, StringParam path)
	Synchronously read a file from a storage container into a client-provided buffer.
void	SDL::WriteStorageFile (StorageRef storage, StringParam path, SourceBytes source)
	Synchronously write a file from client memory into a storage container.
void	SDL::CreateStorageDirectory (StorageRef storage, StringParam path)
	Create a directory in a writable storage container.
void	SDL::EnumerateStorageDirectory (StorageRef storage, StringParam path, EnumerateDirectoryCallback callback, void *userdata)
	Enumerate a directory in a storage container through a callback function.
void	SDL::EnumerateStorageDirectory (StorageRef storage, StringParam path, EnumerateDirectoryCB callback)
	Enumerate a directory in a storage container through a callback function.
std::vector< Path >	SDL::EnumerateStorageDirectory (StorageRef storage, StringParam path)
	Enumerate a directory in a storage container through a callback function.
void	SDL::RemoveStoragePath (StorageRef storage, StringParam path)
	Remove a file or an empty directory in a writable storage container.
void	SDL::RenameStoragePath (StorageRef storage, StringParam oldpath, StringParam newpath)
	Rename a file or directory in a writable storage container.
void	SDL::CopyStorageFile (StorageRef storage, StringParam oldpath, StringParam newpath)
	Copy a file in a writable storage container.
PathInfo	SDL::GetStoragePathInfo (StorageRef storage, StringParam path)
	Get information about a filesystem path in a storage container.
Uint64	SDL::GetStorageSpaceRemaining (StorageRef storage)
	Queries the remaining space in a storage container.
OwnArray< char * >	SDL::GlobStorageDirectory (StorageRef storage, StringParam path, StringParam pattern, GlobFlags flags)
	Enumerate a directory tree, filtered by pattern, and return a list.
	SDL::Storage::Storage (StringParam override, PropertiesRef props)
	Opens up a read-only container for the application's filesystem.
	SDL::Storage::Storage (StringParam org, StringParam app, PropertiesRef props)
	Opens up a container for a user's unique read/write filesystem.
	SDL::Storage::Storage (StringParam path)
	Opens up a container for local filesystem storage.
	SDL::Storage::Storage (const StorageInterface &iface, void *userdata)
	Opens up a container using a client-provided storage interface.
bool	SDL::StorageBase::Close ()
	Closes and frees a storage container.
bool	SDL::StorageBase::Ready ()
	Checks if the storage container is ready to use.
std::optional< Uint64 >	SDL::StorageBase::GetFileSize (StringParam path)
	Query the size of a file within a storage container.
bool	SDL::StorageBase::ReadFile (StringParam path, TargetBytes destination)
	Synchronously read a file from a storage container into a client-provided buffer.
std::string	SDL::StorageBase::ReadFile (StringParam path)
	Synchronously read a file from a storage container into a client-provided buffer.
template<class T>
std::vector< T >	SDL::StorageBase::ReadFileAs (StringParam path)
	Synchronously read a file from a storage container into a client-provided buffer.
void	SDL::StorageBase::WriteFile (StringParam path, SourceBytes source)
	Synchronously write a file from client memory into a storage container.
void	SDL::StorageBase::CreateDirectory (StringParam path)
	Create a directory in a writable storage container.
void	SDL::StorageBase::EnumerateDirectory (StringParam path, EnumerateDirectoryCallback callback, void *userdata)
	Enumerate a directory in a storage container through a callback function.
std::vector< Path >	SDL::StorageBase::EnumerateDirectory (StringParam path)
	Enumerate a directory in a storage container through a callback function.
void	SDL::StorageBase::EnumerateDirectory (StringParam path, EnumerateDirectoryCB callback)
	Enumerate a directory in a storage container through a callback function.
void	SDL::StorageBase::RemovePath (StringParam path)
	Remove a file or an empty directory in a writable storage container.
void	SDL::StorageBase::RenamePath (StringParam oldpath, StringParam newpath)
	Rename a file or directory in a writable storage container.
void	SDL::StorageBase::CopyFile (StringParam oldpath, StringParam newpath)
	Copy a file in a writable storage container.
PathInfo	SDL::StorageBase::GetPathInfo (StringParam path)
	Get information about a filesystem path in a storage container.
Uint64	SDL::StorageBase::GetSpaceRemaining ()
	Queries the remaining space in a storage container.
OwnArray< char * >	SDL::StorageBase::GlobDirectory (StringParam path, StringParam pattern, GlobFlags flags)
	Enumerate a directory tree, filtered by pattern, and return a list.

Detailed Description

The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level (in SDL's case, this sits on top of the [Filesystem](CategoryFilesystem) and [IOStream](CategoryIOStream) subsystems).

It is significantly more restrictive than a typical filesystem API, for a number of reasons:

What to Access: A common pitfall with existing filesystem APIs is the assumption that all storage is monolithic. However, many other platforms (game consoles in particular) are more strict about what type of filesystem is being accessed; for example, game content and user data are usually two separate storage devices with entirely different characteristics (and possibly different low-level APIs altogether!).
How to Access: Another common mistake is applications assuming that all storage is universally writeable - again, many platforms treat game content and user data as two separate storage devices, and only user data is writeable while game content is read-only.
When to Access: The most common portability issue with filesystem access is timing - you cannot always assume that the storage device is always accessible all of the time, nor can you assume that there are no limits to how long you have access to a particular device.

Consider the following example:

void ReadGameData(void)
{
    extern char** fileNames;
    extern size_t numFiles;
    for (size_t i = 0; i < numFiles; i += 1) {
        FILE *data = fopen(fileNames[i], "rwb");
        if (data == nullptr) {
            // Something bad happened!
        } else {
            // A bunch of stuff happens here
            fclose(data);
        }
    }
}
 
void ReadSave(void)
{
    FILE *save = fopen("saves/save0.sav", "rb");
    if (save == nullptr) {
        // Something bad happened!
    } else {
        // A bunch of stuff happens here
        fclose(save);
    }
}
 
void WriteSave(void)
{
    FILE *save = fopen("saves/save0.sav", "wb");
    if (save == nullptr) {
        // Something bad happened!
    } else {
        // A bunch of stuff happens here
        fclose(save);
    }
}

Going over the bullet points again:

What to Access: This code accesses a global filesystem; game data and saves are all presumed to be in the current working directory (which may or may not be the game's installation folder!).
How to Access: This code assumes that content paths are writeable, and that save data is also writeable despite being in the same location as the game data.
When to Access: This code assumes that they can be called at any time, since the filesystem is always accessible and has no limits on how long the filesystem is being accessed.

Due to these assumptions, the filesystem code is not portable and will fail under these common scenarios:

The game is installed on a device that is read-only, both content loading and game saves will fail or crash outright
Game/User storage is not implicitly mounted, so no files will be found for either scenario when a platform requires explicitly mounting filesystems
Save data may not be safe since the I/O is not being flushed or validated, so an error occurring elsewhere in the program may result in missing/corrupted save data

When using Storage, these types of problems are virtually impossible to trip over:

void ReadGameData(void)
{
    extern char** fileNames;
    extern size_t numFiles;
 
    Storage title = OpenTitleStorage(nullptr, 0);
    if (title == nullptr) {
        // Something bad happened!
    }
    while (!title.Ready()) {
        Delay(1);
    }
 
    for (size_t i = 0; i < numFiles; i += 1) {
        void* dst;
        Uint64 dstLen = title.GetSize(fileNames[i]);
 
        if (dstLen > 0) {
          dst = malloc(dstLen);
          if (title.ReadFile(fileNames[i], dst, dstLen)) {
                // A bunch of stuff happens here
            } else {
                // Something bad happened!
            }
            free(dst);
        } else {
            // Something bad happened!
        }
    }
}
 
void ReadSave(void)
{
    Storage user = OpenUserStorage("libsdl", "Storage Example", 0);
    if (user == nullptr) {
        // Something bad happened!
    }
    while (!user.Ready()) {
        Delay(1);
    }
 
    Uint64 saveLen = user.GetFileSize();
    if (saveLen > 0) {
        void* dst = malloc(saveLen);
        if (user.ReadFile("save0.sav", dst, saveLen)) {
            // A bunch of stuff happens here
        } else {
            // Something bad happened!
        }
        free(dst);
    } else {
        // Something bad happened!
    }
}
 
void WriteSave(void)
{
    Storage user = OpenUserStorage("libsdl", "Storage Example", 0);
    if (user == nullptr) {
        // Something bad happened!
    }
    while (!user.Ready()) {
        Delay(1);
    }
 
    extern void *saveData; // A bunch of stuff happened here...
    extern Uint64 saveLen;
    if (!user.WriteFile("save0.sav", saveData, saveLen)) {
        // Something bad happened!
    }
}

Note the improvements that Storage makes:

What to Access: This code explicitly reads from a title or user storage device based on the context of the function.
How to Access: This code explicitly uses either a read or write function based on the context of the function.
When to Access: This code explicitly opens the device when it needs to, and closes it when it is finished working with the filesystem.

The result is an application that is significantly more robust against the increasing demands of platforms and their filesystems!

A publicly available example of an Storage backend is the Steam Cloud backend - you can initialize Steamworks when starting the program, and then SDL will recognize that Steamworks is initialized and automatically use ISteamRemoteStorage when the application opens user storage. More importantly, when you open storage it knows to begin a "batch" of filesystem operations, and when you close storage it knows to end and flush the batch. This is used by Steam to support Dynamic Cloud Sync ; users can save data on one PC, put the device to sleep, and then continue playing on another PC (and vice versa) with the save data fully synchronized across all devices, allowing for a seamless experience without having to do full restarts of the program.

Notes on valid paths

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 UTF-8 strings (discounting the nullptr terminator character and the '/' path separator) are usable for filenames, however, an underlying Storage implementation may not support particularly strange sequences and refuse to create files with those names, etc.

Typedef Documentation

◆ StorageInterface

using SDL::StorageInterface = SDL_StorageInterface

Function interface for Storage.

Apps that want to supply a custom implementation of Storage will fill in all the functions in this struct, and then pass it to OpenStorage to create a custom Storage object.

It is not usually necessary to do this; SDL provides standard implementations for many things you might expect to do with an Storage.

This structure should be initialized using InitInterface()

Since: This struct is available since SDL 3.2.0.

See also: InitInterface

◆ StorageRef

using SDL::StorageRef = ResourceRefT<StorageBase>

Reference for Storage.

This does not take ownership!

Function Documentation

◆ Close()

bool SDL::StorageBase::Close ( )

inline

Closes and frees a storage container.

Returns: true if the container was freed with no errors, false otherwise; call GetError() for more information. Even if the function returns an error, the container data will be freed; the error is only for informational purposes.

Since: This function is available since SDL 3.2.0.

See also: OpenFileStorage; OpenStorage; OpenTitleStorage; OpenUserStorage

◆ CloseStorage()

bool SDL::CloseStorage ( StorageRaw storage )

inline

Closes and frees a storage container.

Parameters

storage a storage container to close.

Returns: true if the container was freed with no errors, false otherwise; call GetError() for more information. Even if the function returns an error, the container data will be freed; the error is only for informational purposes.

Since: This function is available since SDL 3.2.0.

See also: OpenFileStorage; OpenStorage; OpenTitleStorage; OpenUserStorage

◆ CopyFile()

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

inline

Copy a file in a writable storage container.

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: StorageReady

◆ CopyStorageFile()

void SDL::CopyStorageFile	(	StorageRef	storage,
		StringParam	oldpath,
		StringParam	newpath )

inline

Copy a file in a writable storage container.

Parameters

storage	a storage container.
oldpath	the old path.
newpath	the new path.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ CreateDirectory()

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

inline

Create a directory in a writable storage container.

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: StorageReady

◆ CreateStorageDirectory()

void SDL::CreateStorageDirectory	(	StorageRef	storage,
		StringParam	path )

inline

Create a directory in a writable storage container.

Parameters

storage	a storage container.
path	the path of the directory to create.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ EnumerateDirectory() [1/3]

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

inline

Enumerate a directory in a storage container through a callback function.

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.

Returns: all the directory contents.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ EnumerateDirectory() [2/3]

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

inline

Enumerate a directory in a storage container through a callback function.

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: StorageReady

◆ EnumerateDirectory() [3/3]

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

inline

Enumerate a directory in a storage container through a callback function.

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: StorageReady

◆ EnumerateStorageDirectory() [1/3]

std::vector< Path > SDL::EnumerateStorageDirectory	(	StorageRef	storage,
		StringParam	path )

inline

Enumerate a directory in a storage container through a callback function.

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

storage	a storage container.
path	the path of the directory to enumerate, or nullptr for the root.

Returns: all the directory contents.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ EnumerateStorageDirectory() [2/3]

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

inline

Enumerate a directory in a storage container through a callback function.

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

storage	a storage container.
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: StorageReady

◆ EnumerateStorageDirectory() [3/3]

void SDL::EnumerateStorageDirectory	(	StorageRef	storage,
		StringParam	path,
		EnumerateDirectoryCB	callback )

inline

Enumerate a directory in a storage container through a callback function.

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

storage	a storage container.
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: StorageReady

◆ GetFileSize()

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

inline

Query the size of a file within a storage container.

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: ReadStorageFile; StorageReady

◆ GetPathInfo()

PathInfo SDL::StorageBase::GetPathInfo ( StringParam path )

inline

Get information about a filesystem path in a storage container.

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: StorageReady

◆ GetSpaceRemaining()

Uint64 SDL::StorageBase::GetSpaceRemaining ( )

inline

Queries the remaining space in a storage container.

Returns: the amount of remaining space, in bytes.

Since: This function is available since SDL 3.2.0.

See also: StorageReady; WriteStorageFile

◆ GetStorageFileSize()

std::optional< Uint64 > SDL::GetStorageFileSize	(	StorageRef	storage,
		StringParam	path )

inline

Query the size of a file within a storage container.

Parameters

storage	a storage container to query.
path	the relative path of the file to query.

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

Since: This function is available since SDL 3.2.0.

See also: ReadStorageFile; StorageReady

◆ GetStoragePathInfo()

PathInfo SDL::GetStoragePathInfo	(	StorageRef	storage,
		StringParam	path )

inline

Get information about a filesystem path in a storage container.

Parameters

storage	a storage container.
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: StorageReady

◆ GetStorageSpaceRemaining()

Uint64 SDL::GetStorageSpaceRemaining ( StorageRef storage )

inline

Queries the remaining space in a storage container.

Parameters

storage a storage container to query.

Returns: the amount of remaining space, in bytes.

Since: This function is available since SDL 3.2.0.

See also: StorageReady; WriteStorageFile

◆ GlobDirectory()

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

inline

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

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.

◆ GlobStorageDirectory()

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

inline

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

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

storage	a storage container.
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.

◆ OpenFileStorage()

Storage SDL::OpenFileStorage ( StringParam path )

inline

Opens up a container for local filesystem storage.

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

Parameters

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

Returns: a filesystem storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; OpenTitleStorage; OpenUserStorage; ReadStorageFile; WriteStorageFile

◆ OpenStorage()

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

inline

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

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

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 InitInterface().
userdata	the pointer that will be passed to the interface functions.

Returns: a storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; InitInterface; ReadStorageFile; StorageReady; WriteStorageFile

◆ OpenTitleStorage()

Storage SDL::OpenTitleStorage	(	StringParam	override,
		PropertiesRef	props )

inline

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

By default, OpenTitleStorage uses the generic storage implementation. When the path override is not provided, the generic implementation will use the output of GetBasePath as the base path.

Parameters

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

Returns: a title storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: CloseStorage; GetStorageFileSize; OpenUserStorage; ReadStorageFile

◆ OpenUserStorage()

Storage SDL::OpenUserStorage	(	StringParam	org,
		StringParam	app,
		PropertiesRef	props )

inline

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.

Parameters

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

Returns: a user storage container on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; OpenTitleStorage; ReadStorageFile; StorageReady; WriteStorageFile

◆ ReadFile() [1/2]

std::string SDL::StorageBase::ReadFile ( StringParam path )

inline

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

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

Parameters

path	the relative path of the file to read.

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: GetStorageFileSize; StorageReady; WriteStorageFile

◆ ReadFile() [2/2]

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

inline

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

The value of length must match the length of the file exactly; call GetStorageFileSize() 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: GetStorageFileSize; StorageReady; WriteStorageFile

◆ ReadFileAs()

template<class T>

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

inline

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

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

◆ ReadStorageFile() [1/2]

std::string SDL::ReadStorageFile	(	StorageRef	storage,
		StringParam	path )

inline

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

Parameters

storage	a storage container to read from.
path	the relative path of the file to read.

Returns: the content if the file was read.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: GetStorageFileSize; StorageReady; WriteStorageFile

◆ ReadStorageFile() [2/2]

bool SDL::ReadStorageFile	(	StorageRef	storage,
		StringParam	path,
		TargetBytes	destination )

inline

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

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

Parameters

storage	a storage container to read from.
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: GetStorageFileSize; StorageReady; WriteStorageFile

◆ ReadStorageFileAs()

template<class T>

std::vector< T > SDL::ReadStorageFileAs	(	StorageRef	storage,
		StringParam	path )

inline

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

Parameters

storage	a storage container to read from.
path	the relative path of the file to read.

Returns: the content if the file was read.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

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

◆ Ready()

bool SDL::StorageBase::Ready ( )

inline

Checks if the storage container is ready to use.

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

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

Parameters

path	the path to remove from the filesystem.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ RemoveStoragePath()

void SDL::RemoveStoragePath	(	StorageRef	storage,
		StringParam	path )

inline

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

Parameters

storage	a storage container.
path	the path to remove from the filesystem.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ RenamePath()

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

inline

Rename a file or directory in a writable storage container.

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: StorageReady

◆ RenameStoragePath()

void SDL::RenameStoragePath	(	StorageRef	storage,
		StringParam	oldpath,
		StringParam	newpath )

inline

Rename a file or directory in a writable storage container.

Parameters

storage	a storage container.
oldpath	the old path.
newpath	the new path.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: StorageReady

◆ Storage() [1/4]

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

inline

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

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

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 InitInterface().
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: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; InitInterface; ReadStorageFile; StorageReady; WriteStorageFile

◆ Storage() [2/4]

SDL::Storage::Storage	(	StringParam	org,
		StringParam	app,
		PropertiesRef	props )

inline

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.

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: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; OpenTitleStorage; ReadStorageFile; StorageReady; WriteStorageFile

◆ Storage() [3/4]

SDL::Storage::Storage	(	StringParam	override,
		PropertiesRef	props )

inline

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

By default, OpenTitleStorage uses the generic storage implementation. When the path override is not provided, the generic implementation will use the output of GetBasePath as the base path.

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: CloseStorage; GetStorageFileSize; OpenUserStorage; ReadStorageFile

◆ Storage() [4/4]

SDL::Storage::Storage ( StringParam path )

inline

Opens up a container for local filesystem storage.

This is provided for development and tools. Portable applications should use OpenTitleStorage() for access to game data and OpenUserStorage() 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: CloseStorage; GetStorageFileSize; GetStorageSpaceRemaining; OpenTitleStorage; OpenUserStorage; ReadStorageFile; WriteStorageFile

◆ StorageReady()

bool SDL::StorageReady ( StorageRef storage )

inline

Checks if the storage container is ready to use.

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.

Parameters

storage a storage container to query.

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

Since: This function is available since SDL 3.2.0.

◆ WriteFile()

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

inline

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

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: GetStorageSpaceRemaining; ReadStorageFile; StorageReady

◆ WriteStorageFile()

void SDL::WriteStorageFile	(	StorageRef	storage,
		StringParam	path,
		SourceBytes	source )

inline

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

Parameters

storage	a storage container to write to.
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: GetStorageSpaceRemaining; ReadStorageFile; StorageReady

Classes

Typedefs

Functions

Detailed Description

Notes on valid paths

Typedef Documentation

◆ StorageInterface

◆ StorageRef

Function Documentation

◆ Close()

◆ CloseStorage()

◆ CopyFile()

◆ CopyStorageFile()

◆ CreateDirectory()

◆ CreateStorageDirectory()

◆ EnumerateDirectory() [1/3]

◆ EnumerateDirectory() [2/3]

◆ EnumerateDirectory() [3/3]

◆ EnumerateStorageDirectory() [1/3]

◆ EnumerateStorageDirectory() [2/3]

◆ EnumerateStorageDirectory() [3/3]

◆ GetFileSize()

◆ GetPathInfo()

◆ GetSpaceRemaining()

◆ GetStorageFileSize()

◆ GetStoragePathInfo()

◆ GetStorageSpaceRemaining()

◆ GlobDirectory()

◆ GlobStorageDirectory()

◆ OpenFileStorage()

◆ OpenStorage()

◆ OpenTitleStorage()

◆ OpenUserStorage()

◆ ReadFile() [1/2]

◆ ReadFile() [2/2]

◆ ReadFileAs()

◆ ReadStorageFile() [1/2]

◆ ReadStorageFile() [2/2]

◆ ReadStorageFileAs()

◆ Ready()

◆ RemovePath()

◆ RemoveStoragePath()

◆ RenamePath()

◆ RenameStoragePath()

◆ Storage() [1/4]

◆ Storage() [2/4]

◆ Storage() [3/4]

◆ Storage() [4/4]

◆ StorageReady()

◆ WriteFile()

◆ WriteStorageFile()