SDL 3.0
SDL_storage.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * \file SDL_storage.h
24 *
25 * Include file for storage container SDL API functions
26 */
27
28#ifndef SDL_storage_h_
29#define SDL_storage_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_filesystem.h>
34#include <SDL3/SDL_properties.h>
35
36#include <SDL3/SDL_begin_code.h>
37
38/* Set up for C function definitions, even when using C++ */
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/* !!! FIXME: Don't let this ship without async R/W support!!! */
44
46{
47 /* Called when the storage is closed */
48 int (SDLCALL *close)(void *userdata);
49
50 /* Optional, returns whether the storage is currently ready for access */
51 SDL_bool (SDLCALL *ready)(void *userdata);
52
53 /* Enumerate a directory, optional for write-only storage */
54 int (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata);
55
56 /* Get path information, optional for write-only storage */
57 int (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info);
58
59 /* Read a file from storage, optional for write-only storage */
60 int (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length);
61
62 /* Write a file to storage, optional for read-only storage */
63 int (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length);
64
65 /* Create a directory, optional for read-only storage */
66 int (SDLCALL *mkdir)(void *userdata, const char *path);
67
68 /* Remove a file or empty directory, optional for read-only storage */
69 int (SDLCALL *remove)(void *userdata, const char *path);
70
71 /* Rename a path, optional for read-only storage */
72 int (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath);
73
74 /* Get the space remaining, optional for read-only storage */
75 Uint64 (SDLCALL *space_remaining)(void *userdata);
76
78
79typedef struct SDL_Storage SDL_Storage;
80
81/**
82 * Opens up a read-only container for the application's filesystem.
83 *
84 * \param override a path to override the backend's default title root
85 * \param props a property list that may contain backend-specific information
86 * \returns a title storage container on success or NULL on failure; call
87 * SDL_GetError() for more information.
88 *
89 * \since This function is available since SDL 3.0.0.
90 *
91 * \sa SDL_CloseStorage
92 * \sa SDL_GetStorageFileSize
93 * \sa SDL_OpenUserStorage
94 * \sa SDL_ReadStorageFile
95 */
96extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props);
97
98/**
99 * Opens up a container for a user's unique read/write filesystem.
100 *
101 * While title storage can generally be kept open throughout runtime, user
102 * storage should only be opened when the client is ready to read/write files.
103 * This allows the backend to properly batch file operations and flush them
104 * when the container has been closed; ensuring safe and optimal save I/O.
105 *
106 * \param org the name of your organization
107 * \param app the name of your application
108 * \param props a property list that may contain backend-specific information
109 * \returns a user storage container on success or NULL on failure; call
110 * SDL_GetError() for more information.
111 *
112 * \since This function is available since SDL 3.0.0.
113 *
114 * \sa SDL_CloseStorage
115 * \sa SDL_GetStorageFileSize
116 * \sa SDL_GetStorageSpaceRemaining
117 * \sa SDL_OpenTitleStorage
118 * \sa SDL_ReadStorageFile
119 * \sa SDL_StorageReady
120 * \sa SDL_WriteStorageFile
121 */
122extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props);
123
124/**
125 * Opens up a container for local filesystem storage.
126 *
127 * This is provided for development and tools. Portable applications should
128 * use SDL_OpenTitleStorage() for access to game data and
129 * SDL_OpenUserStorage() for access to user data.
130 *
131 * \param path the base path prepended to all storage paths, or NULL for no
132 * base path
133 * \returns a filesystem storage container on success or NULL on failure; call
134 * SDL_GetError() for more information.
135 *
136 * \since This function is available since SDL 3.0.0.
137 *
138 * \sa SDL_CloseStorage
139 * \sa SDL_GetStorageFileSize
140 * \sa SDL_GetStorageSpaceRemaining
141 * \sa SDL_OpenTitleStorage
142 * \sa SDL_OpenUserStorage
143 * \sa SDL_ReadStorageFile
144 * \sa SDL_WriteStorageFile
145 */
146extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenFileStorage(const char *path);
147
148/**
149 * Opens up a container using a client-provided storage interface.
150 *
151 * Applications do not need to use this function unless they are providing
152 * their own SDL_Storage implementation. If you just need an SDL_Storage, you
153 * should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
154 * or SDL_OpenUserStorage().
155 *
156 * \param iface the function table to be used by this container
157 * \param userdata the pointer that will be passed to the store interface
158 * \returns a storage container on success or NULL on failure; call
159 * SDL_GetError() for more information.
160 *
161 * \since This function is available since SDL 3.0.0.
162 *
163 * \sa SDL_CloseStorage
164 * \sa SDL_GetStorageFileSize
165 * \sa SDL_GetStorageSpaceRemaining
166 * \sa SDL_ReadStorageFile
167 * \sa SDL_StorageReady
168 * \sa SDL_WriteStorageFile
169 */
170extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata);
171
172/**
173 * Closes and frees a storage container.
174 *
175 * \param storage a storage container to close
176 * \returns 0 if the container was freed with no errors, a negative value
177 * otherwise; call SDL_GetError() for more information. Even if the
178 * function returns an error, the container data will be freed; the
179 * error is only for informational purposes.
180 *
181 * \since This function is available since SDL 3.0.0.
182 *
183 * \sa SDL_OpenFileStorage
184 * \sa SDL_OpenStorage
185 * \sa SDL_OpenTitleStorage
186 * \sa SDL_OpenUserStorage
187 */
188extern DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage);
189
190/**
191 * Checks if the storage container is ready to use.
192 *
193 * This function should be called in regular intervals until it returns
194 * SDL_TRUE - however, it is not recommended to spinwait on this call, as the
195 * backend may depend on a synchronous message loop.
196 *
197 * \param storage a storage container to query
198 * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise
199 *
200 * \since This function is available since SDL 3.0.0.
201 */
202extern DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
203
204/**
205 * Query the size of a file within a storage container.
206 *
207 * \param storage a storage container to query
208 * \param path the relative path of the file to query
209 * \param length a pointer to be filled with the file's length
210 * \returns 0 if the file could be queried, a negative value otherwise; call
211 * SDL_GetError() for more information.
212 *
213 * \since This function is available since SDL 3.0.0.
214 *
215 * \sa SDL_ReadStorageFile
216 * \sa SDL_StorageReady
217 */
218extern DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length);
219
220/**
221 * Synchronously read a file from a storage container into a client-provided
222 * buffer.
223 *
224 * \param storage a storage container to read from
225 * \param path the relative path of the file to read
226 * \param destination a client-provided buffer to read the file into
227 * \param length the length of the destination buffer
228 * \returns 0 if the file was read, a negative value otherwise; call
229 * SDL_GetError() for more information.
230 *
231 * \since This function is available since SDL 3.0.0.
232 *
233 * \sa SDL_GetStorageFileSize
234 * \sa SDL_StorageReady
235 * \sa SDL_WriteStorageFile
236 */
237extern DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length);
238
239/**
240 * Synchronously write a file from client memory into a storage container.
241 *
242 * \param storage a storage container to write to
243 * \param path the relative path of the file to write
244 * \param source a client-provided buffer to write from
245 * \param length the length of the source buffer
246 * \returns 0 if the file was written, a negative value otherwise; call
247 * SDL_GetError() for more information.
248 *
249 * \since This function is available since SDL 3.0.0.
250 *
251 * \sa SDL_GetStorageSpaceRemaining
252 * \sa SDL_ReadStorageFile
253 * \sa SDL_StorageReady
254 */
255extern DECLSPEC int SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length);
256
257/**
258 * Create a directory in a writable storage container.
259 *
260 * \param storage a storage container
261 * \param path the path of the directory to create
262 * \returns 0 on success or a negative error code on failure; call
263 * SDL_GetError() for more information.
264 *
265 * \since This function is available since SDL 3.0.0.
266 *
267 * \sa SDL_StorageReady
268 */
269extern DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path);
270
271/**
272 * Enumerate a directory in a storage container through a callback function.
273 *
274 * This function provides every directory entry through an app-provided
275 * callback, called once for each directory entry, until all results have been
276 * provided or the callback returns <= 0.
277 *
278 * \param storage a storage container
279 * \param path the path of the directory to enumerate
280 * \param callback a function that is called for each entry in the directory
281 * \param userdata a pointer that is passed to `callback`
282 * \returns 0 on success or a negative error code on failure; call
283 * SDL_GetError() for more information.
284 *
285 * \since This function is available since SDL 3.0.0.
286 *
287 * \sa SDL_StorageReady
288 */
289extern DECLSPEC int SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata);
290
291/**
292 * Remove a file or an empty directory in a writable storage container.
293 *
294 * \param storage a storage container
295 * \param path the path of the directory to enumerate
296 * \returns 0 on success or a negative error code on failure; call
297 * SDL_GetError() for more information.
298 *
299 * \since This function is available since SDL 3.0.0.
300 *
301 * \sa SDL_StorageReady
302 */
303extern DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path);
304
305/**
306 * Rename a file or directory in a writable storage container.
307 *
308 * \param storage a storage container
309 * \param oldpath the old path
310 * \param newpath the new path
311 * \returns 0 on success or a negative error code on failure; call
312 * SDL_GetError() for more information.
313 *
314 * \since This function is available since SDL 3.0.0.
315 *
316 * \sa SDL_StorageReady
317 */
318extern DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath);
319
320/**
321 * Get information about a filesystem path in a storage container.
322 *
323 * \param storage a storage container
324 * \param path the path to query
325 * \param info a pointer filled in with information about the path, or NULL to
326 * check for the existence of a file
327 * \returns 0 on success or a negative error code if the file doesn't exist,
328 * or another failure; call SDL_GetError() for more information.
329 *
330 * \since This function is available since SDL 3.0.0.
331 *
332 * \sa SDL_StorageReady
333 */
334extern DECLSPEC int SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info);
335
336/**
337 * Queries the remaining space in a storage container.
338 *
339 * \param storage a storage container to query
340 * \returns the amount of remaining space, in bytes
341 *
342 * \since This function is available since SDL 3.0.0.
343 *
344 * \sa SDL_StorageReady
345 * \sa SDL_WriteStorageFile
346 */
347extern DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *storage);
348
349/**
350 * Enumerate a directory tree, filtered by pattern, and return a list.
351 *
352 * Files are filtered out if they don't match the string in `pattern`, which
353 * may contain wildcard characters '*' (match everything) and '?' (match one
354 * character). If pattern is NULL, no filtering is done and all results are
355 * returned. Subdirectories are permitted, and are specified with a path
356 * separator of '/'. Wildcard characters '*' and '?' never match a path
357 * separator.
358 *
359 * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching
360 * case-insensitive.
361 *
362 * The returned array is always NULL-terminated, for your iterating
363 * convenience, but if `count` is non-NULL, on return it will contain the
364 * number of items in the array, not counting the NULL terminator.
365 *
366 * You must free the returned pointer with SDL_free() when done with it.
367 *
368 * \param storage a storage container
369 * \param path the path of the directory to enumerate
370 * \param pattern the pattern that files in the directory must match. Can be
371 * NULL.
372 * \param flags `SDL_GLOB_*` bitflags that affect this search.
373 * \param count on return, will be set to the number of items in the returned
374 * array. Can be NULL.
375 * \returns an array of strings on success or NULL on failure; call
376 * SDL_GetError() for more information. The caller should pass the
377 * returned pointer to SDL_free when done with it.
378 *
379 * \threadsafety It is safe to call this function from any thread, assuming
380 * the `storage` object is thread-safe.
381 *
382 * \since This function is available since SDL 3.0.0.
383 */
384extern DECLSPEC char **SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, Uint32 flags, int *count);
385
386/* Ends C function definitions when using C++ */
387#ifdef __cplusplus
388}
389#endif
390#include <SDL3/SDL_close_code.h>
391
392#endif /* SDL_storage_h_ */
int(* SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname)
Uint32 SDL_PropertiesID
int SDL_bool
Definition SDL_stdinc.h:170
uint64_t Uint64
Definition SDL_stdinc.h:242
uint32_t Uint32
Definition SDL_stdinc.h:224
SDL_Storage * SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props)
SDL_Storage * SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props)
int SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path)
struct SDL_Storage SDL_Storage
Definition SDL_storage.h:79
SDL_Storage * SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata)
char ** SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, Uint32 flags, int *count)
int SDL_CloseStorage(SDL_Storage *storage)
int SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info)
Uint64 SDL_GetStorageSpaceRemaining(SDL_Storage *storage)
int SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length)
SDL_Storage * SDL_OpenFileStorage(const char *path)
int SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath)
int SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata)
int SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length)
SDL_bool SDL_StorageReady(SDL_Storage *storage)
int SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length)
int SDL_RemoveStoragePath(SDL_Storage *storage, const char *path)
int(* remove)(void *userdata, const char *path)
Definition SDL_storage.h:69
int(* mkdir)(void *userdata, const char *path)
Definition SDL_storage.h:66
int(* enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata)
Definition SDL_storage.h:54
int(* rename)(void *userdata, const char *oldpath, const char *newpath)
Definition SDL_storage.h:72
SDL_bool(* ready)(void *userdata)
Definition SDL_storage.h:51
int(* read_file)(void *userdata, const char *path, void *destination, Uint64 length)
Definition SDL_storage.h:60
int(* write_file)(void *userdata, const char *path, const void *source, Uint64 length)
Definition SDL_storage.h:63
int(* info)(void *userdata, const char *path, SDL_PathInfo *info)
Definition SDL_storage.h:57
Uint64(* space_remaining)(void *userdata)
Definition SDL_storage.h:75
int(* close)(void *userdata)
Definition SDL_storage.h:48