Safe Haskell	None
Language	GHC2021

SDL3.Sys.Bindgen.Storage.Safe

Synopsis

sDL_OpenTitleStorage :: PtrConst CChar -> SDL_PropertiesID -> IO (Ptr SDL_Storage)
sDL_OpenUserStorage :: PtrConst CChar -> PtrConst CChar -> SDL_PropertiesID -> IO (Ptr SDL_Storage)
sDL_OpenFileStorage :: PtrConst CChar -> IO (Ptr SDL_Storage)
sDL_OpenStorage :: PtrConst SDL_StorageInterface -> Ptr Void -> IO (Ptr SDL_Storage)
sDL_CloseStorage :: Ptr SDL_Storage -> IO CBool
sDL_StorageReady :: Ptr SDL_Storage -> IO CBool
sDL_GetStorageFileSize :: Ptr SDL_Storage -> PtrConst CChar -> Ptr Uint64 -> IO CBool
sDL_ReadStorageFile :: Ptr SDL_Storage -> PtrConst CChar -> Ptr Void -> Uint64 -> IO CBool
sDL_WriteStorageFile :: Ptr SDL_Storage -> PtrConst CChar -> PtrConst Void -> Uint64 -> IO CBool
sDL_CreateStorageDirectory :: Ptr SDL_Storage -> PtrConst CChar -> IO CBool
sDL_EnumerateStorageDirectory :: Ptr SDL_Storage -> PtrConst CChar -> SDL_EnumerateDirectoryCallback -> Ptr Void -> IO CBool
sDL_RemoveStoragePath :: Ptr SDL_Storage -> PtrConst CChar -> IO CBool
sDL_RenameStoragePath :: Ptr SDL_Storage -> PtrConst CChar -> PtrConst CChar -> IO CBool
sDL_CopyStorageFile :: Ptr SDL_Storage -> PtrConst CChar -> PtrConst CChar -> IO CBool
sDL_GetStoragePathInfo :: Ptr SDL_Storage -> PtrConst CChar -> Ptr SDL_PathInfo -> IO CBool
sDL_GetStorageSpaceRemaining :: Ptr SDL_Storage -> IO Uint64
sDL_GlobStorageDirectory :: Ptr SDL_Storage -> PtrConst CChar -> PtrConst CChar -> SDL_GlobFlags -> Ptr CInt -> IO (Ptr (Ptr CChar))

Documentation

sDL_OpenTitleStorage Source #

Arguments

:: PtrConst CChar	`override` a path to override the backend's default title root.
-> SDL_PropertiesID	`props` a property list that may contain backend-specific information.
-> IO (Ptr SDL_Storage)

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

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

Returns: a title storage container on success or NULL on failure; call SDL_GetError() for more information.
See also: sDL_CloseStorage, sDL_GetStorageFileSize, sDL_OpenUserStorage, sDL_ReadStorageFile
C declaration: SDL_OpenTitleStorage, defined at SDL3/SDL_storage.h 353:43

Since: 3.2.0

sDL_OpenUserStorage Source #

Arguments

:: PtrConst CChar	`org` the name of your organization.
-> PtrConst CChar	`app` the name of your application.
-> SDL_PropertiesID	`props` a property list that may contain backend-specific information.
-> IO (Ptr SDL_Storage)

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.

Returns: a user storage container on success or NULL on failure; call SDL_GetError() for more information.
See also: sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, sDL_OpenTitleStorage, sDL_ReadStorageFile, sDL_StorageReady, sDL_WriteStorageFile
C declaration: SDL_OpenUserStorage, defined at SDL3/SDL_storage.h 379:43

Since: 3.2.0

sDL_OpenFileStorage Source #

Arguments

:: PtrConst CChar	`path` the base path prepended to all storage paths, or NULL for no base path.
-> IO (Ptr SDL_Storage)

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.

Returns: a filesystem storage container on success or NULL on failure; call SDL_GetError() for more information.
See also: sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, sDL_OpenTitleStorage, sDL_OpenUserStorage, sDL_ReadStorageFile, sDL_WriteStorageFile
C declaration: SDL_OpenFileStorage, defined at SDL3/SDL_storage.h 403:43

Since: 3.2.0

sDL_OpenStorage Source #

Arguments

:: PtrConst SDL_StorageInterface	`iface` the interface that implements this storage, initialized using SDL_INIT_INTERFACE().
-> Ptr Void	`userdata` the pointer that will be passed to the interface functions.
-> IO (Ptr SDL_Storage)

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

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

Returns: a storage container on success or NULL on failure; call SDL_GetError() for more information.
See also: sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, SDL_INIT_INTERFACE, sDL_ReadStorageFile, sDL_StorageReady, sDL_WriteStorageFile
C declaration: SDL_OpenStorage, defined at SDL3/SDL_storage.h 432:43

Since: 3.2.0

sDL_CloseStorage Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to close.
-> IO CBool

Closes and frees a storage container.

Returns: true if the container was freed with no errors, false 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.
See also: sDL_OpenFileStorage, sDL_OpenStorage, sDL_OpenTitleStorage, sDL_OpenUserStorage
C declaration: SDL_CloseStorage, defined at SDL3/SDL_storage.h 450:34

Since: 3.2.0

sDL_StorageReady Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to query.
-> IO CBool

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.
C declaration: SDL_StorageReady, defined at SDL3/SDL_storage.h 465:34

Since: 3.2.0

sDL_GetStorageFileSize Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to query.
-> PtrConst CChar	`path` the relative path of the file to query.
-> Ptr Uint64	`length` a pointer to be filled with the file's length.
-> IO CBool

Query the size of a file within a storage container.

Returns: true if the file could be queried or false on failure; call SDL_GetError() for more information.
See also: sDL_ReadStorageFile, sDL_StorageReady
C declaration: SDL_GetStorageFileSize, defined at SDL3/SDL_storage.h 481:34

Since: 3.2.0

sDL_ReadStorageFile Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to read from.
-> PtrConst CChar	`path` the relative path of the file to read.
-> Ptr Void	`destination` a client-provided buffer to read the file into.
-> Uint64	`length` the length of the destination buffer.
-> IO CBool

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 SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in a future release.

Returns: true if the file was read or false on failure; call SDL_GetError() for more information.
See also: sDL_GetStorageFileSize, sDL_StorageReady, sDL_WriteStorageFile
C declaration: SDL_ReadStorageFile, defined at SDL3/SDL_storage.h 504:34

Since: 3.2.0

sDL_WriteStorageFile Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to write to.
-> PtrConst CChar	`path` the relative path of the file to write.
-> PtrConst Void	`source` a client-provided buffer to write from.
-> Uint64	`length` the length of the source buffer.
-> IO CBool

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

Returns: true if the file was written or false on failure; call SDL_GetError() for more information.
See also: sDL_GetStorageSpaceRemaining, sDL_ReadStorageFile, sDL_StorageReady
C declaration: SDL_WriteStorageFile, defined at SDL3/SDL_storage.h 522:34

Since: 3.2.0

sDL_CreateStorageDirectory Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`path` the path of the directory to create.
-> IO CBool

Create a directory in a writable storage container.

Returns: true on success or false on failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_CreateStorageDirectory, defined at SDL3/SDL_storage.h 536:34

Since: 3.2.0

sDL_EnumerateStorageDirectory Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`path` the path of the directory to enumerate, or NULL for the root.
-> SDL_EnumerateDirectoryCallback	`callback` a function that is called for each entry in the directory.
-> Ptr Void	`userdata` a pointer that is passed to `callback`.
-> IO CBool

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 SDL_ENUM_SUCCESS or SDL_ENUM_FAILURE.

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

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

Returns: true on success or false on failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_EnumerateStorageDirectory, defined at SDL3/SDL_storage.h 565:34

Since: 3.2.0

sDL_RemoveStoragePath Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`path` the path to remove from the filesystem.
-> IO CBool

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

Returns: true on success or false on failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_RemoveStoragePath, defined at SDL3/SDL_storage.h 579:34

Since: 3.2.0

sDL_RenameStoragePath Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`oldpath` the old path.
-> PtrConst CChar	`newpath` the new path.
-> IO CBool

Rename a file or directory in a writable storage container.

Returns: true on success or false on failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_RenameStoragePath, defined at SDL3/SDL_storage.h 594:34

Since: 3.2.0

sDL_CopyStorageFile Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`oldpath` the old path.
-> PtrConst CChar	`newpath` the new path.
-> IO CBool

Copy a file in a writable storage container.

Returns: true on success or false on failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_CopyStorageFile, defined at SDL3/SDL_storage.h 609:34

Since: 3.2.0

sDL_GetStoragePathInfo Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`path` the path to query.
-> Ptr SDL_PathInfo	`info` a pointer filled in with information about the path, or NULL to check for the existence of a file.
-> IO CBool

Get information about a filesystem path in a storage container.

Returns: true on success or false if the file doesn't exist, or another failure; call SDL_GetError() for more information.
See also: sDL_StorageReady
C declaration: SDL_GetStoragePathInfo, defined at SDL3/SDL_storage.h 625:34

Since: 3.2.0

sDL_GetStorageSpaceRemaining Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container to query.
-> IO Uint64

Queries the remaining space in a storage container.

Returns: the amount of remaining space, in bytes.
See also: sDL_StorageReady, sDL_WriteStorageFile
C declaration: SDL_GetStorageSpaceRemaining, defined at SDL3/SDL_storage.h 638:36

Since: 3.2.0

sDL_GlobStorageDirectory Source #

Arguments

:: Ptr SDL_Storage	`storage` a storage container.
-> PtrConst CChar	`path` the path of the directory to enumerate, or NULL for the root.
-> PtrConst CChar	`pattern` the pattern that files in the directory must match. Can be NULL.
-> SDL_GlobFlags	`flags` `SDL_GLOB_*` bitflags that affect this search.
-> Ptr CInt	`count` on return, will be set to the number of items in the returned array. Can be NULL.
-> IO (Ptr (Ptr CChar))

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.

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

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.
Thread safety: It is safe to call this function from any thread, assuming the storage object is thread-safe.
C declaration: SDL_GlobStorageDirectory, defined at SDL3/SDL_storage.h 678:37

Since: 3.2.0