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