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 * # CategoryStorage
24 *
25 * SDL storage container management.
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
45/**
46 * Function interface for SDL_Storage.
47 *
48 * Apps that want to supply a custom implementation of SDL_Storage will fill
49 * in all the functions in this struct, and then pass it to SDL_OpenStorage to
50 * create a custom SDL_Storage object.
51 *
52 * It is not usually necessary to do this; SDL provides standard
53 * implementations for many things you might expect to do with an SDL_Storage.
54 *
55 * This structure should be initialized using SDL_INIT_INTERFACE()
56 *
57 * \since This struct is available since SDL 3.1.3.
58 *
59 * \sa SDL_INIT_INTERFACE
60 */
62{
63 /* The version of this interface */
65
66 /* Called when the storage is closed */
67 bool (SDLCALL *close)(void *userdata);
68
69 /* Optional, returns whether the storage is currently ready for access */
70 bool (SDLCALL *ready)(void *userdata);
71
72 /* Enumerate a directory, optional for write-only storage */
73 bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata);
74
75 /* Get path information, optional for write-only storage */
76 bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info);
77
78 /* Read a file from storage, optional for write-only storage */
79 bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length);
80
81 /* Write a file to storage, optional for read-only storage */
82 bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length);
83
84 /* Create a directory, optional for read-only storage */
85 bool (SDLCALL *mkdir)(void *userdata, const char *path);
86
87 /* Remove a file or empty directory, optional for read-only storage */
88 bool (SDLCALL *remove)(void *userdata, const char *path);
89
90 /* Rename a path, optional for read-only storage */
91 bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath);
92
93 /* Copy a file, optional for read-only storage */
94 bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath);
95
96 /* Get the space remaining, optional for read-only storage */
97 Uint64 (SDLCALL *space_remaining)(void *userdata);
99
100/* Check the size of SDL_StorageInterface
101 *
102 * If this assert fails, either the compiler is padding to an unexpected size,
103 * or the interface has been updated and this should be updated to match and
104 * the code using this interface should be updated to handle the old version.
105 */
106SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE,
107 (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) ||
108 (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96));
109
110/**
111 * An abstract interface for filesystem access.
112 *
113 * This is an opaque datatype. One can create this object using standard SDL
114 * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create
115 * an object with a custom implementation using SDL_OpenStorage.
116 *
117 * \since This struct is available since SDL 3.1.3.
118 */
120
121/**
122 * Opens up a read-only container for the application's filesystem.
123 *
124 * \param override a path to override the backend's default title root.
125 * \param props a property list that may contain backend-specific information.
126 * \returns a title storage container on success or NULL on failure; call
127 * SDL_GetError() for more information.
128 *
129 * \since This function is available since SDL 3.1.3.
130 *
131 * \sa SDL_CloseStorage
132 * \sa SDL_GetStorageFileSize
133 * \sa SDL_OpenUserStorage
134 * \sa SDL_ReadStorageFile
135 */
136extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props);
137
138/**
139 * Opens up a container for a user's unique read/write filesystem.
140 *
141 * While title storage can generally be kept open throughout runtime, user
142 * storage should only be opened when the client is ready to read/write files.
143 * This allows the backend to properly batch file operations and flush them
144 * when the container has been closed; ensuring safe and optimal save I/O.
145 *
146 * \param org the name of your organization.
147 * \param app the name of your application.
148 * \param props a property list that may contain backend-specific information.
149 * \returns a user storage container on success or NULL on failure; call
150 * SDL_GetError() for more information.
151 *
152 * \since This function is available since SDL 3.1.3.
153 *
154 * \sa SDL_CloseStorage
155 * \sa SDL_GetStorageFileSize
156 * \sa SDL_GetStorageSpaceRemaining
157 * \sa SDL_OpenTitleStorage
158 * \sa SDL_ReadStorageFile
159 * \sa SDL_StorageReady
160 * \sa SDL_WriteStorageFile
161 */
162extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props);
163
164/**
165 * Opens up a container for local filesystem storage.
166 *
167 * This is provided for development and tools. Portable applications should
168 * use SDL_OpenTitleStorage() for access to game data and
169 * SDL_OpenUserStorage() for access to user data.
170 *
171 * \param path the base path prepended to all storage paths, or NULL for no
172 * base path.
173 * \returns a filesystem storage container on success or NULL on failure; call
174 * SDL_GetError() for more information.
175 *
176 * \since This function is available since SDL 3.1.3.
177 *
178 * \sa SDL_CloseStorage
179 * \sa SDL_GetStorageFileSize
180 * \sa SDL_GetStorageSpaceRemaining
181 * \sa SDL_OpenTitleStorage
182 * \sa SDL_OpenUserStorage
183 * \sa SDL_ReadStorageFile
184 * \sa SDL_WriteStorageFile
185 */
186extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path);
187
188/**
189 * Opens up a container using a client-provided storage interface.
190 *
191 * Applications do not need to use this function unless they are providing
192 * their own SDL_Storage implementation. If you just need an SDL_Storage, you
193 * should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
194 * or SDL_OpenUserStorage().
195 *
196 * This function makes a copy of `iface` and the caller does not need to keep
197 * it around after this call.
198 *
199 * \param iface the interface that implements this storage, initialized using
200 * SDL_INIT_INTERFACE().
201 * \param userdata the pointer that will be passed to the interface functions.
202 * \returns a storage container on success or NULL on failure; call
203 * SDL_GetError() for more information.
204 *
205 * \since This function is available since SDL 3.1.3.
206 *
207 * \sa SDL_CloseStorage
208 * \sa SDL_GetStorageFileSize
209 * \sa SDL_GetStorageSpaceRemaining
210 * \sa SDL_INIT_INTERFACE
211 * \sa SDL_ReadStorageFile
212 * \sa SDL_StorageReady
213 * \sa SDL_WriteStorageFile
214 */
215extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata);
216
217/**
218 * Closes and frees a storage container.
219 *
220 * \param storage a storage container to close.
221 * \returns true if the container was freed with no errors, false otherwise;
222 * call SDL_GetError() for more information. Even if the function
223 * returns an error, the container data will be freed; the error is
224 * only for informational purposes.
225 *
226 * \since This function is available since SDL 3.1.3.
227 *
228 * \sa SDL_OpenFileStorage
229 * \sa SDL_OpenStorage
230 * \sa SDL_OpenTitleStorage
231 * \sa SDL_OpenUserStorage
232 */
233extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage);
234
235/**
236 * Checks if the storage container is ready to use.
237 *
238 * This function should be called in regular intervals until it returns true -
239 * however, it is not recommended to spinwait on this call, as the backend may
240 * depend on a synchronous message loop.
241 *
242 * \param storage a storage container to query.
243 * \returns true if the container is ready, false otherwise.
244 *
245 * \since This function is available since SDL 3.1.3.
246 */
247extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
248
249/**
250 * Query the size of a file within a storage container.
251 *
252 * \param storage a storage container to query.
253 * \param path the relative path of the file to query.
254 * \param length a pointer to be filled with the file's length.
255 * \returns true if the file could be queried or false on failure; call
256 * SDL_GetError() for more information.
257 *
258 * \since This function is available since SDL 3.1.3.
259 *
260 * \sa SDL_ReadStorageFile
261 * \sa SDL_StorageReady
262 */
263extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length);
264
265/**
266 * Synchronously read a file from a storage container into a client-provided
267 * buffer.
268 *
269 * \param storage a storage container to read from.
270 * \param path the relative path of the file to read.
271 * \param destination a client-provided buffer to read the file into.
272 * \param length the length of the destination buffer.
273 * \returns true if the file was read or false on failure; call SDL_GetError()
274 * for more information.
275 *
276 * \since This function is available since SDL 3.1.3.
277 *
278 * \sa SDL_GetStorageFileSize
279 * \sa SDL_StorageReady
280 * \sa SDL_WriteStorageFile
281 */
282extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length);
283
284/**
285 * Synchronously write a file from client memory into a storage container.
286 *
287 * \param storage a storage container to write to.
288 * \param path the relative path of the file to write.
289 * \param source a client-provided buffer to write from.
290 * \param length the length of the source buffer.
291 * \returns true if the file was written or false on failure; call
292 * SDL_GetError() for more information.
293 *
294 * \since This function is available since SDL 3.1.3.
295 *
296 * \sa SDL_GetStorageSpaceRemaining
297 * \sa SDL_ReadStorageFile
298 * \sa SDL_StorageReady
299 */
300extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length);
301
302/**
303 * Create a directory in a writable storage container.
304 *
305 * \param storage a storage container.
306 * \param path the path of the directory to create.
307 * \returns true on success or false on failure; call SDL_GetError() for more
308 * information.
309 *
310 * \since This function is available since SDL 3.1.3.
311 *
312 * \sa SDL_StorageReady
313 */
314extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path);
315
316/**
317 * Enumerate a directory in a storage container through a callback function.
318 *
319 * This function provides every directory entry through an app-provided
320 * callback, called once for each directory entry, until all results have been
321 * provided or the callback returns either SDL_ENUM_SUCCESS or
322 * SDL_ENUM_FAILURE.
323 *
324 * This will return false if there was a system problem in general, or if a
325 * callback returns SDL_ENUM_FAILURE. A successful return means a callback
326 * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries
327 * were enumerated.
328 *
329 * \param storage a storage container.
330 * \param path the path of the directory to enumerate.
331 * \param callback a function that is called for each entry in the directory.
332 * \param userdata a pointer that is passed to `callback`.
333 * \returns true on success or false on failure; call SDL_GetError() for more
334 * information.
335 *
336 * \since This function is available since SDL 3.1.3.
337 *
338 * \sa SDL_StorageReady
339 */
340extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata);
341
342/**
343 * Remove a file or an empty directory in a writable storage container.
344 *
345 * \param storage a storage container.
346 * \param path the path of the directory to enumerate.
347 * \returns true on success or false on failure; call SDL_GetError() for more
348 * information.
349 *
350 * \since This function is available since SDL 3.1.3.
351 *
352 * \sa SDL_StorageReady
353 */
354extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path);
355
356/**
357 * Rename a file or directory in a writable storage container.
358 *
359 * \param storage a storage container.
360 * \param oldpath the old path.
361 * \param newpath the new path.
362 * \returns true on success or false on failure; call SDL_GetError() for more
363 * information.
364 *
365 * \since This function is available since SDL 3.1.3.
366 *
367 * \sa SDL_StorageReady
368 */
369extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath);
370
371/**
372 * Copy a file in a writable storage container.
373 *
374 * \param storage a storage container.
375 * \param oldpath the old path.
376 * \param newpath the new path.
377 * \returns true on success or false on failure; call SDL_GetError() for more
378 * information.
379 *
380 * \since This function is available since SDL 3.1.3.
381 *
382 * \sa SDL_StorageReady
383 */
384extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath);
385
386/**
387 * Get information about a filesystem path in a storage container.
388 *
389 * \param storage a storage container.
390 * \param path the path to query.
391 * \param info a pointer filled in with information about the path, or NULL to
392 * check for the existence of a file.
393 * \returns true on success or false if the file doesn't exist, or another
394 * failure; call SDL_GetError() for more information.
395 *
396 * \since This function is available since SDL 3.1.3.
397 *
398 * \sa SDL_StorageReady
399 */
400extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info);
401
402/**
403 * Queries the remaining space in a storage container.
404 *
405 * \param storage a storage container to query.
406 * \returns the amount of remaining space, in bytes.
407 *
408 * \since This function is available since SDL 3.1.3.
409 *
410 * \sa SDL_StorageReady
411 * \sa SDL_WriteStorageFile
412 */
413extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *storage);
414
415/**
416 * Enumerate a directory tree, filtered by pattern, and return a list.
417 *
418 * Files are filtered out if they don't match the string in `pattern`, which
419 * may contain wildcard characters '*' (match everything) and '?' (match one
420 * character). If pattern is NULL, no filtering is done and all results are
421 * returned. Subdirectories are permitted, and are specified with a path
422 * separator of '/'. Wildcard characters '*' and '?' never match a path
423 * separator.
424 *
425 * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching
426 * case-insensitive.
427 *
428 * The returned array is always NULL-terminated, for your iterating
429 * convenience, but if `count` is non-NULL, on return it will contain the
430 * number of items in the array, not counting the NULL terminator.
431 *
432 * \param storage a storage container.
433 * \param path the path of the directory to enumerate.
434 * \param pattern the pattern that files in the directory must match. Can be
435 * NULL.
436 * \param flags `SDL_GLOB_*` bitflags that affect this search.
437 * \param count on return, will be set to the number of items in the returned
438 * array. Can be NULL.
439 * \returns an array of strings on success or NULL on failure; call
440 * SDL_GetError() for more information. The caller should pass the
441 * returned pointer to SDL_free when done with it. This is a single
442 * allocation that should be freed with SDL_free() when it is no
443 * longer needed.
444 *
445 * \threadsafety It is safe to call this function from any thread, assuming
446 * the `storage` object is thread-safe.
447 *
448 * \since This function is available since SDL 3.1.3.
449 */
450extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
451
452/* Ends C function definitions when using C++ */
453#ifdef __cplusplus
454}
455#endif
456#include <SDL3/SDL_close_code.h>
457
458#endif /* SDL_storage_h_ */
Uint32 SDL_GlobFlags
SDL_EnumerationResult(* SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname)
Uint32 SDL_PropertiesID
#define SDL_COMPILE_TIME_ASSERT(name, x)
Definition SDL_stdinc.h:112
#define bool
Definition SDL_stdinc.h:53
uint64_t Uint64
Definition SDL_stdinc.h:392
uint32_t Uint32
Definition SDL_stdinc.h:370
SDL_Storage * SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props)
char ** SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count)
bool SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length)
bool SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath)
bool SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length)
SDL_Storage * SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props)
struct SDL_Storage SDL_Storage
bool SDL_CloseStorage(SDL_Storage *storage)
SDL_Storage * SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata)
bool SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path)
Uint64 SDL_GetStorageSpaceRemaining(SDL_Storage *storage)
bool SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length)
SDL_Storage * SDL_OpenFileStorage(const char *path)
bool SDL_StorageReady(SDL_Storage *storage)
bool SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info)
bool SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath)
bool SDL_RemoveStoragePath(SDL_Storage *storage, const char *path)
bool SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata)
bool(* read_file)(void *userdata, const char *path, void *destination, Uint64 length)
Definition SDL_storage.h:79
bool(* ready)(void *userdata)
Definition SDL_storage.h:70
bool(* rename)(void *userdata, const char *oldpath, const char *newpath)
Definition SDL_storage.h:91
bool(* mkdir)(void *userdata, const char *path)
Definition SDL_storage.h:85
bool(* enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata)
Definition SDL_storage.h:73
bool(* write_file)(void *userdata, const char *path, const void *source, Uint64 length)
Definition SDL_storage.h:82
bool(* info)(void *userdata, const char *path, SDL_PathInfo *info)
Definition SDL_storage.h:76
Uint64(* space_remaining)(void *userdata)
Definition SDL_storage.h:97
bool(* close)(void *userdata)
Definition SDL_storage.h:67
bool(* copy)(void *userdata, const char *oldpath, const char *newpath)
Definition SDL_storage.h:94
bool(* remove)(void *userdata, const char *path)
Definition SDL_storage.h:88