mirror of https://github.com/libsdl-org/SDL
277 lines
9.0 KiB
C
277 lines
9.0 KiB
C
|
/*
|
||
|
|
Simple DirectMedia Layer
|
||
|
|
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
|
||
|
|
|
||
|
|
This software is provided 'as-is', without any express or implied
|
||
|
|
warranty. In no event will the authors be held liable for any damages
|
||
|
|
arising from the use of this software.
|
||
|
|
|
||
|
|
Permission is granted to anyone to use this software for any purpose,
|
||
|
|
including commercial applications, and to alter it and redistribute it
|
||
|
|
freely, subject to the following restrictions:
|
||
|
|
|
||
|
|
1. The origin of this software must not be misrepresented; you must not
|
||
|
|
claim that you wrote the original software. If you use this software
|
||
|
|
in a product, an acknowledgment in the product documentation would be
|
||
|
|
appreciated but is not required.
|
||
|
|
2. Altered source versions must be plainly marked as such, and must not be
|
||
|
|
misrepresented as being the original software.
|
||
|
|
3. This notice may not be removed or altered from any source distribution.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \file SDL_storage.h
|
||
|
|
*
|
||
|
|
* Include file for storage container SDL API functions
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef SDL_storage_h_
|
||
|
|
#define SDL_storage_h_
|
||
|
|
|
||
|
|
#include <SDL3/SDL_stdinc.h>
|
||
|
|
#include <SDL3/SDL_mutex.h>
|
||
|
|
#include <SDL3/SDL_properties.h>
|
||
|
|
|
||
|
|
#include <SDL3/SDL_begin_code.h>
|
||
|
|
|
||
|
|
/* Set up for C function definitions, even when using C++ */
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/* !!! FIXME: Don't let this ship without async R/W support!!! */
|
||
|
|
|
||
|
|
typedef struct SDL_StorageInterface
|
||
|
|
{
|
||
|
|
int (SDLCALL *close)(void *userdata);
|
||
|
|
|
||
|
|
SDL_bool (SDLCALL *ready)(void *userdata);
|
||
|
|
|
||
|
|
int (SDLCALL *fileSize)(void *userdata, const char *path, Uint64 *length);
|
||
|
|
|
||
|
|
int (SDLCALL *readFile)(void *userdata, const char *path, void *destination, Uint64 length);
|
||
|
|
|
||
|
|
int (SDLCALL *writeFile)(void *userdata, const char *path, const void *source, Uint64 length);
|
||
|
|
|
||
|
|
Uint64 (SDLCALL *spaceRemaining)(void *userdata);
|
||
|
|
} SDL_StorageInterface;
|
||
|
|
|
||
|
|
typedef struct SDL_Storage SDL_Storage;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Opens up a read-only container for the application's filesystem.
|
||
|
|
*
|
||
|
|
* \param override a path to override the backend's default title root
|
||
|
|
* \param props a 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.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_TitleStorageReady
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 R/W operations and flush them when
|
||
|
|
* the container has been closed; ensuring safe and optimal save I/O.
|
||
|
|
*
|
||
|
|
* \param org the name of your organization
|
||
|
|
* \param app the name of your application
|
||
|
|
* \param props a 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.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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().
|
||
|
|
*
|
||
|
|
* \param iface the function table to be used by this container
|
||
|
|
* \param userdata the 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.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Closes and frees a storage container.
|
||
|
|
*
|
||
|
|
* \param storage a 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.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*
|
||
|
|
* \param storage a 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.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Query the size of a file within a storage container.
|
||
|
|
*
|
||
|
|
* \param storage a storage container to query
|
||
|
|
* \param path the relative path of the file to query
|
||
|
|
* \param length a pointer to be filled with the file's length
|
||
|
|
* \returns 0 if the file could be queried, a negative value otherwise; call
|
||
|
|
* SDL_GetError() for more information.
|
||
|
|
*
|
||
|
|
* \since This function is available since SDL 3.0.0.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC int SDLCALL SDL_StorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Synchronously read a file from a storage container into a client-provided buffer.
|
||
|
|
*
|
||
|
|
* \param storage a storage container to read from
|
||
|
|
* \param path the relative path of the file to read
|
||
|
|
* \param destination a client-provided buffer to read the file into
|
||
|
|
* \param length the length of the destination buffer
|
||
|
|
* \returns 0 if the file was read, a negative value otherwise; call
|
||
|
|
* SDL_GetError() for more information.
|
||
|
|
*
|
||
|
|
* \since This function is available since SDL 3.0.0.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC int SDLCALL SDL_StorageReadFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Synchronously write a file from client memory into a storage container.
|
||
|
|
*
|
||
|
|
* \param storage a storage container to write to
|
||
|
|
* \param path the relative path of the file to write
|
||
|
|
* \param source a client-provided buffer to write from
|
||
|
|
* \param length the length of the source buffer
|
||
|
|
* \returns 0 if the file was written, a negative value otherwise; call
|
||
|
|
* SDL_GetError() for more information.
|
||
|
|
*
|
||
|
|
* \since This function is available since SDL 3.0.0.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageSpaceRemaining
|
||
|
|
*/
|
||
|
|
extern DECLSPEC int SDL_StorageWriteFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Queries the remaining space in a storage container.
|
||
|
|
*
|
||
|
|
* \param storage a storage container to query
|
||
|
|
* \returns the amount of remaining space, in bytes
|
||
|
|
*
|
||
|
|
* \since This function is available since SDL 3.0.0.
|
||
|
|
*
|
||
|
|
* \sa SDL_OpenTitleStorage
|
||
|
|
* \sa SDL_OpenUserStorage
|
||
|
|
* \sa SDL_OpenStorage
|
||
|
|
* \sa SDL_CloseStorage
|
||
|
|
* \sa SDL_StorageReady
|
||
|
|
* \sa SDL_StorageFileSize
|
||
|
|
* \sa SDL_StorageReadFile
|
||
|
|
* \sa SDL_StorageReadFileAsync
|
||
|
|
* \sa SDL_StorageWriteFile
|
||
|
|
* \sa SDL_StorageWriteFileAsync
|
||
|
|
*/
|
||
|
|
extern DECLSPEC Uint64 SDLCALL SDL_StorageSpaceRemaining(SDL_Storage *storage);
|
||
|
|
|
||
|
|
/* Ends C function definitions when using C++ */
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
#include <SDL3/SDL_close_code.h>
|
||
|
|
|
||
|
|
#endif /* SDL_storage_h_ */
|