SDL 3.0
SDL_storage.h File Reference
+ Include dependency graph for SDL_storage.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_StorageInterface
 

Typedefs

typedef struct SDL_Storage SDL_Storage
 

Functions

SDL_StorageSDL_OpenTitleStorage (const char *override, SDL_PropertiesID props)
 
SDL_StorageSDL_OpenUserStorage (const char *org, const char *app, SDL_PropertiesID props)
 
SDL_StorageSDL_OpenFileStorage (const char *path)
 
SDL_StorageSDL_OpenStorage (const SDL_StorageInterface *iface, void *userdata)
 
int SDL_CloseStorage (SDL_Storage *storage)
 
SDL_bool SDL_StorageReady (SDL_Storage *storage)
 
int SDL_GetStorageFileSize (SDL_Storage *storage, const char *path, Uint64 *length)
 
int SDL_ReadStorageFile (SDL_Storage *storage, const char *path, void *destination, Uint64 length)
 
int SDL_WriteStorageFile (SDL_Storage *storage, const char *path, const void *source, Uint64 length)
 
int SDL_CreateStorageDirectory (SDL_Storage *storage, const char *path)
 
int SDL_EnumerateStorageDirectory (SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata)
 
int SDL_RemoveStoragePath (SDL_Storage *storage, const char *path)
 
int SDL_RenameStoragePath (SDL_Storage *storage, const char *oldpath, const char *newpath)
 
int SDL_CopyStorageFile (SDL_Storage *storage, const char *oldpath, const char *newpath)
 
int SDL_GetStoragePathInfo (SDL_Storage *storage, const char *path, SDL_PathInfo *info)
 
Uint64 SDL_GetStorageSpaceRemaining (SDL_Storage *storage)
 
char ** SDL_GlobStorageDirectory (SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count)
 

Typedef Documentation

◆ SDL_Storage

typedef struct SDL_Storage SDL_Storage

An abstract interface for filesystem access.

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

Since
This struct is available since SDL 3.0.0.

Definition at line 102 of file SDL_storage.h.

Function Documentation

◆ SDL_CloseStorage()

int SDL_CloseStorage ( SDL_Storage storage)
extern

Closes and frees a storage container.

Parameters
storagea storage container to close.
Returns
0 if the container was freed with no errors, a negative value otherwise; call SDL_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.0.0.
See also
SDL_OpenFileStorage
SDL_OpenStorage
SDL_OpenTitleStorage
SDL_OpenUserStorage

◆ SDL_CopyStorageFile()

int SDL_CopyStorageFile ( SDL_Storage storage,
const char *  oldpath,
const char *  newpath 
)
extern

Copy a file in a writable storage container.

Parameters
storagea storage container.
oldpaththe old path.
newpaththe new path.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_CreateStorageDirectory()

int SDL_CreateStorageDirectory ( SDL_Storage storage,
const char *  path 
)
extern

Create a directory in a writable storage container.

Parameters
storagea storage container.
paththe path of the directory to create.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_EnumerateStorageDirectory()

int SDL_EnumerateStorageDirectory ( SDL_Storage storage,
const char *  path,
SDL_EnumerateDirectoryCallback  callback,
void *  userdata 
)
extern

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 <= 0.

Parameters
storagea storage container.
paththe path of the directory to enumerate.
callbacka function that is called for each entry in the directory.
userdataa pointer that is passed to callback.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_GetStorageFileSize()

int SDL_GetStorageFileSize ( SDL_Storage storage,
const char *  path,
Uint64 length 
)
extern

Query the size of a file within a storage container.

Parameters
storagea storage container to query.
paththe relative path of the file to query.
lengtha pointer to be filled with the file's length.
Returns
0 if the file could be queried or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_ReadStorageFile
SDL_StorageReady

◆ SDL_GetStoragePathInfo()

int SDL_GetStoragePathInfo ( SDL_Storage storage,
const char *  path,
SDL_PathInfo info 
)
extern

Get information about a filesystem path in a storage container.

Parameters
storagea storage container.
paththe path to query.
infoa pointer filled in with information about the path, or NULL to check for the existence of a file.
Returns
0 on success or a negative error code if the file doesn't exist, or another failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_GetStorageSpaceRemaining()

Uint64 SDL_GetStorageSpaceRemaining ( SDL_Storage storage)
extern

Queries the remaining space in a storage container.

Parameters
storagea storage container to query.
Returns
the amount of remaining space, in bytes.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady
SDL_WriteStorageFile

◆ SDL_GlobStorageDirectory()

char ** SDL_GlobStorageDirectory ( SDL_Storage storage,
const char *  path,
const char *  pattern,
SDL_GlobFlags  flags,
int *  count 
)
extern

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 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 SDL_GLOB_CASEINSENSITIVE to make the pattern matching case-insensitive.

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

Parameters
storagea storage container.
paththe path of the directory to enumerate.
patternthe pattern that files in the directory must match. Can be NULL.
flagsSDL_GLOB_* bitflags that affect this search.
counton return, will be set to the number of items in the returned array. Can be NULL.
Returns
an array of strings on success or NULL on failure; call SDL_GetError() for more information. The caller should pass the returned pointer to SDL_free when done with it. This is a single allocation that should be freed with SDL_free() when it is no longer needed.

\threadsafety 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.0.0.

◆ SDL_OpenFileStorage()

SDL_Storage * SDL_OpenFileStorage ( const char *  path)
extern

Opens up a container for local filesystem storage.

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

Parameters
paththe base path prepended to all storage paths, or NULL for no base path.
Returns
a filesystem storage container on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseStorage
SDL_GetStorageFileSize
SDL_GetStorageSpaceRemaining
SDL_OpenTitleStorage
SDL_OpenUserStorage
SDL_ReadStorageFile
SDL_WriteStorageFile

◆ SDL_OpenStorage()

SDL_Storage * SDL_OpenStorage ( const SDL_StorageInterface iface,
void *  userdata 
)
extern

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

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

Parameters
ifacethe function table to be used by this container.
userdatathe pointer that will be passed to the store interface.
Returns
a storage container on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseStorage
SDL_GetStorageFileSize
SDL_GetStorageSpaceRemaining
SDL_ReadStorageFile
SDL_StorageReady
SDL_WriteStorageFile

◆ SDL_OpenTitleStorage()

SDL_Storage * SDL_OpenTitleStorage ( const char *  override,
SDL_PropertiesID  props 
)
extern

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

Parameters
overridea path to override the backend's default title root.
propsa property list that may contain backend-specific information.
Returns
a title storage container on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseStorage
SDL_GetStorageFileSize
SDL_OpenUserStorage
SDL_ReadStorageFile

◆ SDL_OpenUserStorage()

SDL_Storage * SDL_OpenUserStorage ( const char *  org,
const char *  app,
SDL_PropertiesID  props 
)
extern

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
orgthe name of your organization.
appthe name of your application.
propsa property list that may contain backend-specific information.
Returns
a user storage container on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseStorage
SDL_GetStorageFileSize
SDL_GetStorageSpaceRemaining
SDL_OpenTitleStorage
SDL_ReadStorageFile
SDL_StorageReady
SDL_WriteStorageFile

◆ SDL_ReadStorageFile()

int SDL_ReadStorageFile ( SDL_Storage storage,
const char *  path,
void *  destination,
Uint64  length 
)
extern

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

Parameters
storagea storage container to read from.
paththe relative path of the file to read.
destinationa client-provided buffer to read the file into.
lengththe length of the destination buffer.
Returns
0 if the file was read or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetStorageFileSize
SDL_StorageReady
SDL_WriteStorageFile

◆ SDL_RemoveStoragePath()

int SDL_RemoveStoragePath ( SDL_Storage storage,
const char *  path 
)
extern

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

Parameters
storagea storage container.
paththe path of the directory to enumerate.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_RenameStoragePath()

int SDL_RenameStoragePath ( SDL_Storage storage,
const char *  oldpath,
const char *  newpath 
)
extern

Rename a file or directory in a writable storage container.

Parameters
storagea storage container.
oldpaththe old path.
newpaththe new path.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StorageReady

◆ SDL_StorageReady()

SDL_bool SDL_StorageReady ( SDL_Storage storage)
extern

Checks if the storage container is ready to use.

This function should be called in regular intervals until it returns SDL_TRUE - however, it is not recommended to spinwait on this call, as the backend may depend on a synchronous message loop.

Parameters
storagea storage container to query.
Returns
SDL_TRUE if the container is ready, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.

◆ SDL_WriteStorageFile()

int SDL_WriteStorageFile ( SDL_Storage storage,
const char *  path,
const void *  source,
Uint64  length 
)
extern

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

Parameters
storagea storage container to write to.
paththe relative path of the file to write.
sourcea client-provided buffer to write from.
lengththe length of the source buffer.
Returns
0 if the file was written or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetStorageSpaceRemaining
SDL_ReadStorageFile
SDL_StorageReady