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_filesystem.h>
33#include <SDL3/SDL_properties.h>
34
35#include <SDL3/SDL_begin_code.h>
36
37/* Set up for C function definitions, even when using C++ */
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/* !!! FIXME: Don't let this ship without async R/W support!!! */
43
45{
46 /* Called when the storage is closed */
47 int (SDLCALL *close)(void *userdata);
48
49 /* Optional, returns whether the storage is currently ready for access */
50 SDL_bool (SDLCALL *ready)(void *userdata);
51
52 /* Enumerate a directory, optional for write-only storage */
53 int (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata);
54
55 /* Get path information, optional for write-only storage */
56 int (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info);
57
58 /* Read a file from storage, optional for write-only storage */
59 int (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length);
60
61 /* Write a file to storage, optional for read-only storage */
62 int (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length);
63
64 /* Create a directory, optional for read-only storage */
65 int (SDLCALL *mkdir)(void *userdata, const char *path);
66
67 /* Remove a file or empty directory, optional for read-only storage */
68 int (SDLCALL *remove)(void *userdata, const char *path);
69
70 /* Rename a path, optional for read-only storage */
71 int (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath);
72
73 /* Get the space remaining, optional for read-only storage */
74 Uint64 (SDLCALL *space_remaining)(void *userdata);
75
77
78typedef struct SDL_Storage SDL_Storage;
79
80/**
81 * Opens up a read-only container for the application's filesystem.
82 *
83 * \param override a path to override the backend's default title root
84 * \param props a property list that may contain backend-specific information
85 * \returns a title storage container on success or NULL on failure; call
86 * SDL_GetError() for more information.
87 *
88 * \since This function is available since SDL 3.0.0.
89 *
90 * \sa SDL_CloseStorage
91 * \sa SDL_GetStorageFileSize
92 * \sa SDL_OpenUserStorage
93 * \sa SDL_ReadStorageFile
94 */
95extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props);
96
97/**
98 * Opens up a container for a user's unique read/write filesystem.
99 *
100 * While title storage can generally be kept open throughout runtime, user
101 * storage should only be opened when the client is ready to read/write files.
102 * This allows the backend to properly batch file operations and flush them
103 * when the container has been closed; ensuring safe and optimal save I/O.
104 *
105 * \param org the name of your organization
106 * \param app the name of your application
107 * \param props a property list that may contain backend-specific information
108 * \returns a user storage container on success or NULL on failure; call
109 * SDL_GetError() for more information.
110 *
111 * \since This function is available since SDL 3.0.0.
112 *
113 * \sa SDL_CloseStorage
114 * \sa SDL_GetStorageFileSize
115 * \sa SDL_GetStorageSpaceRemaining
116 * \sa SDL_OpenTitleStorage
117 * \sa SDL_ReadStorageFile
118 * \sa SDL_StorageReady
119 * \sa SDL_WriteStorageFile
120 */
121extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props);
122
123/**
124 * Opens up a container for local filesystem storage.
125 *
126 * This is provided for development and tools. Portable applications should
127 * use SDL_OpenTitleStorage() for access to game data and
128 * SDL_OpenUserStorage() for access to user data.
129 *
130 * \param path the base path prepended to all storage paths, or NULL for no
131 * base path
132 * \returns a filesystem 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_OpenUserStorage
142 * \sa SDL_ReadStorageFile
143 * \sa SDL_WriteStorageFile
144 */
145extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenFileStorage(const char *path);
146
147/**
148 * Opens up a container using a client-provided storage interface.
149 *
150 * Applications do not need to use this function unless they are providing
151 * their own SDL_Storage implementation. If you just need an SDL_Storage, you
152 * should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
153 * or SDL_OpenUserStorage().
154 *
155 * \param iface the function table to be used by this container
156 * \param userdata the pointer that will be passed to the store interface
157 * \returns a storage container on success or NULL on failure; call
158 * SDL_GetError() for more information.
159 *
160 * \since This function is available since SDL 3.0.0.
161 *
162 * \sa SDL_CloseStorage
163 * \sa SDL_GetStorageFileSize
164 * \sa SDL_GetStorageSpaceRemaining
165 * \sa SDL_ReadStorageFile
166 * \sa SDL_StorageReady
167 * \sa SDL_WriteStorageFile
168 */
169extern DECLSPEC SDL_Storage *SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata);
170
171/**
172 * Closes and frees a storage container.
173 *
174 * \param storage a storage container to close
175 * \returns 0 if the container was freed with no errors, a negative value
176 * otherwise; call SDL_GetError() for more information. Even if the
177 * function returns an error, the container data will be freed; the
178 * error is only for informational purposes.
179 *
180 * \since This function is available since SDL 3.0.0.
181 *
182 * \sa SDL_OpenFileStorage
183 * \sa SDL_OpenStorage
184 * \sa SDL_OpenTitleStorage
185 * \sa SDL_OpenUserStorage
186 */
187extern DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage);
188
189/**
190 * Checks if the storage container is ready to use.
191 *
192 * This function should be called in regular intervals until it returns
193 * SDL_TRUE - however, it is not recommended to spinwait on this call, as the
194 * backend may depend on a synchronous message loop.
195 *
196 * \param storage a storage container to query
197 * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise
198 *
199 * \since This function is available since SDL 3.0.0.
200 */
201extern DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
202
203/**
204 * Query the size of a file within a storage container.
205 *
206 * \param storage a storage container to query
207 * \param path the relative path of the file to query
208 * \param length a pointer to be filled with the file's length
209 * \returns 0 if the file could be queried, a negative value otherwise; call
210 * SDL_GetError() for more information.
211 *
212 * \since This function is available since SDL 3.0.0.
213 *
214 * \sa SDL_ReadStorageFile
215 * \sa SDL_StorageReady
216 */
217extern DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length);
218
219/**
220 * Synchronously read a file from a storage container into a client-provided
221 * buffer.
222 *
223 * \param storage a storage container to read from
224 * \param path the relative path of the file to read
225 * \param destination a client-provided buffer to read the file into
226 * \param length the length of the destination buffer
227 * \returns 0 if the file was read, a negative value otherwise; call
228 * SDL_GetError() for more information.
229 *
230 * \since This function is available since SDL 3.0.0.
231 *
232 * \sa SDL_GetStorageFileSize
233 * \sa SDL_StorageReady
234 * \sa SDL_WriteStorageFile
235 */
236extern DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length);
237
238/**
239 * Synchronously write a file from client memory into a storage container.
240 *
241 * \param storage a storage container to write to
242 * \param path the relative path of the file to write
243 * \param source a client-provided buffer to write from
244 * \param length the length of the source buffer
245 * \returns 0 if the file was written, a negative value otherwise; call
246 * SDL_GetError() for more information.
247 *
248 * \since This function is available since SDL 3.0.0.
249 *
250 * \sa SDL_GetStorageSpaceRemaining
251 * \sa SDL_ReadStorageFile
252 * \sa SDL_StorageReady
253 */
254extern DECLSPEC int SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length);
255
256/**
257 * Create a directory in a writable storage container.
258 *
259 * \param storage a storage container
260 * \param path the path of the directory to create
261 * \returns 0 on success or a negative error code on failure; call
262 * SDL_GetError() for more information.
263 *
264 * \since This function is available since SDL 3.0.0.
265 *
266 * \sa SDL_StorageReady
267 */
268extern DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path);
269
270/**
271 * Enumerate a directory in a storage container.
272 *
273 * \param storage a storage container
274 * \param path the path of the directory to enumerate
275 * \param callback a function that is called for each entry in the directory
276 * \param userdata a pointer that is passed to `callback`
277 * \returns 0 on success or a negative error code on failure; call
278 * SDL_GetError() for more information.
279 *
280 * \since This function is available since SDL 3.0.0.
281 *
282 * \sa SDL_StorageReady
283 */
284extern DECLSPEC int SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata);
285
286/**
287 * Remove a file or an empty directory in a writable storage container.
288 *
289 * \param storage a storage container
290 * \param path the path of the directory to enumerate
291 * \returns 0 on success or a negative error code on failure; call
292 * SDL_GetError() for more information.
293 *
294 * \since This function is available since SDL 3.0.0.
295 *
296 * \sa SDL_StorageReady
297 */
298extern DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path);
299
300/**
301 * Rename a file or directory in a writable storage container.
302 *
303 * \param storage a storage container
304 * \param oldpath the old path
305 * \param newpath the new path
306 * \returns 0 on success or a negative error code on failure; call
307 * SDL_GetError() for more information.
308 *
309 * \since This function is available since SDL 3.0.0.
310 *
311 * \sa SDL_StorageReady
312 */
313extern DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath);
314
315/**
316 * Get information about a filesystem path in a storage container.
317 *
318 * \param storage a storage container
319 * \param path the path to query
320 * \param info a pointer filled in with information about the path, or NULL to
321 * check for the existence of a file
322 * \returns 0 on success or a negative error code if the file doesn't exist,
323 * or another failure; call SDL_GetError() for more information.
324 *
325 * \since This function is available since SDL 3.0.0.
326 *
327 * \sa SDL_StorageReady
328 */
329extern DECLSPEC int SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info);
330
331/**
332 * Queries the remaining space in a storage container.
333 *
334 * \param storage a storage container to query
335 * \returns the amount of remaining space, in bytes
336 *
337 * \since This function is available since SDL 3.0.0.
338 *
339 * \sa SDL_StorageReady
340 * \sa SDL_WriteStorageFile
341 */
342extern DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *storage);
343
344/* Ends C function definitions when using C++ */
345#ifdef __cplusplus
346}
347#endif
348#include <SDL3/SDL_close_code.h>
349
350#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:137
uint64_t Uint64
Definition SDL_stdinc.h:187
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:78
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:68
int(* mkdir)(void *userdata, const char *path)
Definition SDL_storage.h:65
int(* enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata)
Definition SDL_storage.h:53
int(* rename)(void *userdata, const char *oldpath, const char *newpath)
Definition SDL_storage.h:71
SDL_bool(* ready)(void *userdata)
Definition SDL_storage.h:50
int(* read_file)(void *userdata, const char *path, void *destination, Uint64 length)
Definition SDL_storage.h:59
int(* write_file)(void *userdata, const char *path, const void *source, Uint64 length)
Definition SDL_storage.h:62
int(* info)(void *userdata, const char *path, SDL_PathInfo *info)
Definition SDL_storage.h:56
Uint64(* space_remaining)(void *userdata)
Definition SDL_storage.h:74
int(* close)(void *userdata)
Definition SDL_storage.h:47