SDL 3.0
SDL_iostream.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/* WIKI CATEGORY: IOStream */
23
24/**
25 * # CategoryIOStream
26 *
27 * SDL provides an abstract interface for reading and writing data streams. It
28 * offers implementations for files, memory, etc, and the app can provideo
29 * their own implementations, too.
30 *
31 * SDL_IOStream is not related to the standard C++ iostream class, other than
32 * both are abstract interfaces to read/write data.
33 */
34
35#ifndef SDL_iostream_h_
36#define SDL_iostream_h_
37
38#include <SDL3/SDL_stdinc.h>
39#include <SDL3/SDL_error.h>
40#include <SDL3/SDL_properties.h>
41
42#include <SDL3/SDL_begin_code.h>
43/* Set up for C function definitions, even when using C++ */
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * SDL_IOStream status, set by a read or write operation.
50 *
51 * \since This enum is available since SDL 3.0.0.
52 */
53typedef enum SDL_IOStatus
54{
55 SDL_IO_STATUS_READY, /**< Everything is ready (no errors and not EOF). */
56 SDL_IO_STATUS_ERROR, /**< Read or write I/O error */
57 SDL_IO_STATUS_EOF, /**< End of file */
58 SDL_IO_STATUS_NOT_READY, /**< Non blocking I/O, not ready */
59 SDL_IO_STATUS_READONLY, /**< Tried to write a read-only buffer */
60 SDL_IO_STATUS_WRITEONLY /**< Tried to read a write-only buffer */
62
63/**
64 * Possible `whence` values for SDL_IOStream seeking.
65 *
66 * These map to the same "whence" concept that `fseek` or `lseek` use in the
67 * standard C runtime.
68 *
69 * \since This enum is available since SDL 3.0.0.
70 */
71typedef enum SDL_IOWhence
72{
73 SDL_IO_SEEK_SET, /**< Seek from the beginning of data */
74 SDL_IO_SEEK_CUR, /**< Seek relative to current read point */
75 SDL_IO_SEEK_END /**< Seek relative to the end of data */
77
78/**
79 * The function pointers that drive an SDL_IOStream.
80 *
81 * Applications can provide this struct to SDL_OpenIO() to create their own
82 * implementation of SDL_IOStream. This is not necessarily required, as SDL
83 * already offers several common types of I/O streams, via functions like
84 * SDL_IOFromFile() and SDL_IOFromMem().
85 *
86 * \since This struct is available since SDL 3.0.0.
87 */
89{
90 /**
91 * Return the number of bytes in this SDL_IOStream
92 *
93 * \return the total size of the data stream, or -1 on error.
94 */
95 Sint64 (SDLCALL *size)(void *userdata);
96
97 /**
98 * Seek to `offset` relative to `whence`, one of stdio's whence values:
99 * SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END
100 *
101 * \return the final offset in the data stream, or -1 on error.
102 */
103 Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence);
104
105 /**
106 * Read up to `size` bytes from the data stream to the area pointed
107 * at by `ptr`.
108 *
109 * On an incomplete read, you should set `*status` to a value from the
110 * SDL_IOStatus enum. You do not have to explicitly set this on
111 * a complete, successful read.
112 *
113 * \return the number of bytes read
114 */
115 size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status);
116
117 /**
118 * Write exactly `size` bytes from the area pointed at by `ptr`
119 * to data stream.
120 *
121 * On an incomplete write, you should set `*status` to a value from the
122 * SDL_IOStatus enum. You do not have to explicitly set this on
123 * a complete, successful write.
124 *
125 * \return the number of bytes written
126 */
127 size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status);
128
129 /**
130 * Close and free any allocated resources.
131 *
132 * The SDL_IOStream is still destroyed even if this fails, so clean up anything
133 * even if flushing to disk returns an error.
134 *
135 * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data.
136 */
137 SDL_bool (SDLCALL *close)(void *userdata);
138
140
141
142/**
143 * The read/write operation structure.
144 *
145 * This operates as an opaque handle. There are several APIs to create various
146 * types of I/O streams, or an app can supply an SDL_IOStreamInterface to
147 * SDL_OpenIO() to provide their own stream implementation behind this
148 * struct's abstract interface.
149 *
150 * \since This struct is available since SDL 3.0.0.
151 */
153
154
155/**
156 * \name IOFrom functions
157 *
158 * Functions to create SDL_IOStream structures from various data streams.
159 */
160/* @{ */
161
162/**
163 * Use this function to create a new SDL_IOStream structure for reading from
164 * and/or writing to a named file.
165 *
166 * The `mode` string is treated roughly the same as in a call to the C
167 * library's fopen(), even if SDL doesn't happen to use fopen() behind the
168 * scenes.
169 *
170 * Available `mode` strings:
171 *
172 * - "r": Open a file for reading. The file must exist.
173 * - "w": Create an empty file for writing. If a file with the same name
174 * already exists its content is erased and the file is treated as a new
175 * empty file.
176 * - "a": Append to a file. Writing operations append data at the end of the
177 * file. The file is created if it does not exist.
178 * - "r+": Open a file for update both reading and writing. The file must
179 * exist.
180 * - "w+": Create an empty file for both reading and writing. If a file with
181 * the same name already exists its content is erased and the file is
182 * treated as a new empty file.
183 * - "a+": Open a file for reading and appending. All writing operations are
184 * performed at the end of the file, protecting the previous content to be
185 * overwritten. You can reposition (fseek, rewind) the internal pointer to
186 * anywhere in the file for reading, but writing operations will move it
187 * back to the end of file. The file is created if it does not exist.
188 *
189 * **NOTE**: In order to open a file as a binary file, a "b" character has to
190 * be included in the `mode` string. This additional "b" character can either
191 * be appended at the end of the string (thus making the following compound
192 * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the
193 * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+").
194 * Additional characters may follow the sequence, although they should have no
195 * effect. For example, "t" is sometimes appended to make explicit the file is
196 * a text file.
197 *
198 * This function supports Unicode filenames, but they must be encoded in UTF-8
199 * format, regardless of the underlying operating system.
200 *
201 * In Android, SDL_IOFromFile() can be used to open content:// URIs. As a
202 * fallback, SDL_IOFromFile() will transparently open a matching filename in
203 * the app's `assets`.
204 *
205 * Closing the SDL_IOStream will close SDL's internal file handle.
206 *
207 * The following properties may be set at creation time by SDL:
208 *
209 * - `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`: a pointer, that can be cast
210 * to a win32 `HANDLE`, that this SDL_IOStream is using to access the
211 * filesystem. If the program isn't running on Windows, or SDL used some
212 * other method to access the filesystem, this property will not be set.
213 * - `SDL_PROP_IOSTREAM_STDIO_FILE_POINTER`: a pointer, that can be cast to a
214 * stdio `FILE *`, that this SDL_IOStream is using to access the filesystem.
215 * If SDL used some other method to access the filesystem, this property
216 * will not be set. PLEASE NOTE that if SDL is using a different C runtime
217 * than your app, trying to use this pointer will almost certainly result in
218 * a crash! This is mostly a problem on Windows; make sure you build SDL and
219 * your app with the same compiler and settings to avoid it.
220 * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast
221 * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access
222 * the filesystem. If SDL used some other method to access the filesystem,
223 * this property will not be set.
224 *
225 * \param file a UTF-8 string representing the filename to open.
226 * \param mode an ASCII string representing the mode to be used for opening
227 * the file.
228 * \returns a pointer to the SDL_IOStream structure that is created or NULL on
229 * failure; call SDL_GetError() for more information.
230 *
231 * \since This function is available since SDL 3.0.0.
232 *
233 * \sa SDL_CloseIO
234 * \sa SDL_ReadIO
235 * \sa SDL_SeekIO
236 * \sa SDL_TellIO
237 * \sa SDL_WriteIO
238 */
239extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, const char *mode);
240
241#define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle"
242#define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file"
243#define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset"
244
245/**
246 * Use this function to prepare a read-write memory buffer for use with
247 * SDL_IOStream.
248 *
249 * This function sets up an SDL_IOStream struct based on a memory area of a
250 * certain size, for both read and write access.
251 *
252 * This memory buffer is not copied by the SDL_IOStream; the pointer you
253 * provide must remain valid until you close the stream. Closing the stream
254 * will not free the original buffer.
255 *
256 * If you need to make sure the SDL_IOStream never writes to the memory
257 * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of
258 * memory instead.
259 *
260 * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
261 * \param size the buffer size, in bytes.
262 * \returns a pointer to a new SDL_IOStream structure or NULL 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_IOFromConstMem
268 * \sa SDL_CloseIO
269 * \sa SDL_ReadIO
270 * \sa SDL_SeekIO
271 * \sa SDL_TellIO
272 * \sa SDL_WriteIO
273 */
274extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size);
275
276/**
277 * Use this function to prepare a read-only memory buffer for use with
278 * SDL_IOStream.
279 *
280 * This function sets up an SDL_IOStream struct based on a memory area of a
281 * certain size. It assumes the memory area is not writable.
282 *
283 * Attempting to write to this SDL_IOStream stream will report an error
284 * without writing to the memory buffer.
285 *
286 * This memory buffer is not copied by the SDL_IOStream; the pointer you
287 * provide must remain valid until you close the stream. Closing the stream
288 * will not free the original buffer.
289 *
290 * If you need to write to a memory buffer, you should use SDL_IOFromMem()
291 * with a writable buffer of memory instead.
292 *
293 * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
294 * \param size the buffer size, in bytes.
295 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
296 * SDL_GetError() for more information.
297 *
298 * \since This function is available since SDL 3.0.0.
299 *
300 * \sa SDL_IOFromMem
301 * \sa SDL_CloseIO
302 * \sa SDL_ReadIO
303 * \sa SDL_SeekIO
304 * \sa SDL_TellIO
305 */
306extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, size_t size);
307
308/**
309 * Use this function to create an SDL_IOStream that is backed by dynamically
310 * allocated memory.
311 *
312 * This supports the following properties to provide access to the memory and
313 * control over allocations:
314 *
315 * - `SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER`: a pointer to the internal
316 * memory of the stream. This can be set to NULL to transfer ownership of
317 * the memory to the application, which should free the memory with
318 * SDL_free(). If this is done, the next operation on the stream must be
319 * SDL_CloseIO().
320 * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
321 * multiples of this size, defaulting to 1024.
322 *
323 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
324 * SDL_GetError() for more information.
325 *
326 * \since This function is available since SDL 3.0.0.
327 *
328 * \sa SDL_CloseIO
329 * \sa SDL_ReadIO
330 * \sa SDL_SeekIO
331 * \sa SDL_TellIO
332 * \sa SDL_WriteIO
333 */
334extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void);
335
336#define SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER "SDL.iostream.dynamic.memory"
337#define SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER "SDL.iostream.dynamic.chunksize"
338
339/* @} *//* IOFrom functions */
340
341
342/**
343 * Create a custom SDL_IOStream.
344 *
345 * Applications do not need to use this function unless they are providing
346 * their own SDL_IOStream implementation. If you just need an SDL_IOStream to
347 * read/write a common data source, you should use the built-in
348 * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc.
349 *
350 * You must free the returned pointer with SDL_CloseIO().
351 *
352 * This function makes a copy of `iface` and the caller does not need to keep
353 * this data around after this call.
354 *
355 * \param iface the function pointers that implement this SDL_IOStream.
356 * \param userdata the app-controlled pointer that is passed to iface's
357 * functions when called.
358 * \returns a pointer to the allocated memory on success or NULL on failure;
359 * call SDL_GetError() for more information.
360 *
361 * \since This function is available since SDL 3.0.0.
362 *
363 * \sa SDL_CloseIO
364 * \sa SDL_IOFromConstMem
365 * \sa SDL_IOFromFile
366 * \sa SDL_IOFromMem
367 */
368extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata);
369
370/**
371 * Close and free an allocated SDL_IOStream structure.
372 *
373 * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any
374 * resources used by the stream and frees the SDL_IOStream itself. This
375 * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to
376 * its output (e.g. to disk).
377 *
378 * Note that if this fails to flush the stream to disk, this function reports
379 * an error, but the SDL_IOStream is still invalid once this function returns.
380 *
381 * \param context SDL_IOStream structure to close.
382 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
383 * for more information.
384 *
385 * \since This function is available since SDL 3.0.0.
386 *
387 * \sa SDL_OpenIO
388 */
389extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context);
390
391/**
392 * Get the properties associated with an SDL_IOStream.
393 *
394 * \param context a pointer to an SDL_IOStream structure.
395 * \returns a valid property ID on success or 0 on failure; call
396 * SDL_GetError() for more information.
397 *
398 * \since This function is available since SDL 3.0.0.
399 */
400extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context);
401
402/**
403 * Query the stream status of an SDL_IOStream.
404 *
405 * This information can be useful to decide if a short read or write was due
406 * to an error, an EOF, or a non-blocking operation that isn't yet ready to
407 * complete.
408 *
409 * An SDL_IOStream's status is only expected to change after a SDL_ReadIO or
410 * SDL_WriteIO call; don't expect it to change if you just call this query
411 * function in a tight loop.
412 *
413 * \param context the SDL_IOStream to query.
414 * \returns an SDL_IOStatus enum with the current state.
415 *
416 * \threadsafety This function should not be called at the same time that
417 * another thread is operating on the same SDL_IOStream.
418 *
419 * \since This function is available since SDL 3.0.0.
420 */
421extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context);
422
423/**
424 * Use this function to get the size of the data stream in an SDL_IOStream.
425 *
426 * \param context the SDL_IOStream to get the size of the data stream from.
427 * \returns the size of the data stream in the SDL_IOStream on success or a
428 * negative error code on failure; call SDL_GetError() for more
429 * information.
430 *
431 * \since This function is available since SDL 3.0.0.
432 */
433extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context);
434
435/**
436 * Seek within an SDL_IOStream data stream.
437 *
438 * This function seeks to byte `offset`, relative to `whence`.
439 *
440 * `whence` may be any of the following values:
441 *
442 * - `SDL_IO_SEEK_SET`: seek from the beginning of data
443 * - `SDL_IO_SEEK_CUR`: seek relative to current read point
444 * - `SDL_IO_SEEK_END`: seek relative to the end of data
445 *
446 * If this stream can not seek, it will return -1.
447 *
448 * \param context a pointer to an SDL_IOStream structure.
449 * \param offset an offset in bytes, relative to `whence` location; can be
450 * negative.
451 * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`,
452 * `SDL_IO_SEEK_END`.
453 * \returns the final offset in the data stream after the seek or a negative
454 * error code on failure; call SDL_GetError() for more information.
455 *
456 * \since This function is available since SDL 3.0.0.
457 *
458 * \sa SDL_TellIO
459 */
460extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence);
461
462/**
463 * Determine the current read/write offset in an SDL_IOStream data stream.
464 *
465 * SDL_TellIO is actually a wrapper function that calls the SDL_IOStream's
466 * `seek` method, with an offset of 0 bytes from `SDL_IO_SEEK_CUR`, to
467 * simplify application development.
468 *
469 * \param context an SDL_IOStream data stream object from which to get the
470 * current offset.
471 * \returns the current offset in the stream, or -1 if the information can not
472 * be determined.
473 *
474 * \since This function is available since SDL 3.0.0.
475 *
476 * \sa SDL_SeekIO
477 */
478extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
479
480/**
481 * Read from a data source.
482 *
483 * This function reads up `size` bytes from the data source to the area
484 * pointed at by `ptr`. This function may read less bytes than requested. It
485 * will return zero when the data stream is completely read, and
486 * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and
487 * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR.
488 *
489 * \param context a pointer to an SDL_IOStream structure.
490 * \param ptr a pointer to a buffer to read data into.
491 * \param size the number of bytes to read from the data source.
492 * \returns the number of bytes read, or 0 on end of file or other failure;
493 * call SDL_GetError() for more information.
494 *
495 * \since This function is available since SDL 3.0.0.
496 *
497 * \sa SDL_WriteIO
498 * \sa SDL_GetIOStatus
499 */
500extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size);
501
502/**
503 * Write to an SDL_IOStream data stream.
504 *
505 * This function writes exactly `size` bytes from the area pointed at by `ptr`
506 * to the stream. If this fails for any reason, it'll return less than `size`
507 * to demonstrate how far the write progressed. On success, it returns `size`.
508 *
509 * On error, this function still attempts to write as much as possible, so it
510 * might return a positive value less than the requested write size.
511 *
512 * The caller can use SDL_GetIOStatus() to determine if the problem is
513 * recoverable, such as a non-blocking write that can simply be retried later,
514 * or a fatal error.
515 *
516 * \param context a pointer to an SDL_IOStream structure.
517 * \param ptr a pointer to a buffer containing data to write.
518 * \param size the number of bytes to write.
519 * \returns the number of bytes written, which will be less than `size` on
520 * failure; call SDL_GetError() for more information.
521 *
522 * \since This function is available since SDL 3.0.0.
523 *
524 * \sa SDL_IOprintf
525 * \sa SDL_ReadIO
526 * \sa SDL_SeekIO
527 * \sa SDL_GetIOStatus
528 */
529extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size);
530
531/**
532 * Print to an SDL_IOStream data stream.
533 *
534 * This function does formatted printing to the stream.
535 *
536 * \param context a pointer to an SDL_IOStream structure.
537 * \param fmt a printf() style format string.
538 * \param ... additional parameters matching % tokens in the `fmt` string, if
539 * any.
540 * \returns the number of bytes written or 0 on failure; call SDL_GetError()
541 * for more information.
542 *
543 * \since This function is available since SDL 3.0.0.
544 *
545 * \sa SDL_IOvprintf
546 * \sa SDL_WriteIO
547 */
548extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
549
550/**
551 * Print to an SDL_IOStream data stream.
552 *
553 * This function does formatted printing to the stream.
554 *
555 * \param context a pointer to an SDL_IOStream structure.
556 * \param fmt a printf() style format string.
557 * \param ap a variable argument list.
558 * \returns the number of bytes written or 0 on failure; call SDL_GetError()
559 * for more information.
560 *
561 * \since This function is available since SDL 3.0.0.
562 *
563 * \sa SDL_IOprintf
564 * \sa SDL_WriteIO
565 */
566extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
567
568/**
569 * Load all the data from an SDL data stream.
570 *
571 * The data is allocated with a zero byte at the end (null terminated) for
572 * convenience. This extra byte is not included in the value reported via
573 * `datasize`.
574 *
575 * The data should be freed with SDL_free().
576 *
577 * \param src the SDL_IOStream to read all available data from.
578 * \param datasize if not NULL, will store the number of bytes read.
579 * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
580 * even in the case of an error.
581 * \returns the data or NULL on failure; call SDL_GetError() for more
582 * information.
583 *
584 * \since This function is available since SDL 3.0.0.
585 *
586 * \sa SDL_LoadFile
587 */
588extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio);
589
590/**
591 * Load all the data from a file path.
592 *
593 * The data is allocated with a zero byte at the end (null terminated) for
594 * convenience. This extra byte is not included in the value reported via
595 * `datasize`.
596 *
597 * The data should be freed with SDL_free().
598 *
599 * \param file the path to read all available data from.
600 * \param datasize if not NULL, will store the number of bytes read.
601 * \returns the data or NULL on failure; call SDL_GetError() for more
602 * information.
603 *
604 * \since This function is available since SDL 3.0.0.
605 *
606 * \sa SDL_LoadFile_IO
607 */
608extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
609
610/**
611 * \name Read endian functions
612 *
613 * Read an item of the specified endianness and return in native format.
614 */
615/* @{ */
616
617/**
618 * Use this function to read a byte from an SDL_IOStream.
619 *
620 * \param src the SDL_IOStream to read from.
621 * \param value a pointer filled in with the data read.
622 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
623 * for more information.
624 *
625 * \since This function is available since SDL 3.0.0.
626 */
627extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value);
628
629/**
630 * Use this function to read a signed byte from an SDL_IOStream.
631 *
632 * \param src the SDL_IOStream to read from.
633 * \param value a pointer filled in with the data read.
634 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
635 * for more information.
636 *
637 * \since This function is available since SDL 3.0.0.
638 */
639extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value);
640
641/**
642 * Use this function to read 16 bits of little-endian data from an
643 * SDL_IOStream and return in native format.
644 *
645 * SDL byteswaps the data only if necessary, so the data returned will be in
646 * the native byte order.
647 *
648 * \param src the stream from which to read data.
649 * \param value a pointer filled in with the data read.
650 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
651 * SDL_GetError() for more information.
652 *
653 * \since This function is available since SDL 3.0.0.
654 */
655extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value);
656
657/**
658 * Use this function to read 16 bits of little-endian data from an
659 * SDL_IOStream and return in native format.
660 *
661 * SDL byteswaps the data only if necessary, so the data returned will be in
662 * the native byte order.
663 *
664 * \param src the stream from which to read data.
665 * \param value a pointer filled in with the data read.
666 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
667 * SDL_GetError() for more information.
668 *
669 * \since This function is available since SDL 3.0.0.
670 */
671extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value);
672
673/**
674 * Use this function to read 16 bits of big-endian data from an SDL_IOStream
675 * and return in native format.
676 *
677 * SDL byteswaps the data only if necessary, so the data returned will be in
678 * the native byte order.
679 *
680 * \param src the stream from which to read data.
681 * \param value a pointer filled in with the data read.
682 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
683 * SDL_GetError() for more information.
684 *
685 * \since This function is available since SDL 3.0.0.
686 */
687extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value);
688
689/**
690 * Use this function to read 16 bits of big-endian data from an SDL_IOStream
691 * and return in native format.
692 *
693 * SDL byteswaps the data only if necessary, so the data returned will be in
694 * the native byte order.
695 *
696 * \param src the stream from which to read data.
697 * \param value a pointer filled in with the data read.
698 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
699 * SDL_GetError() for more information.
700 *
701 * \since This function is available since SDL 3.0.0.
702 */
703extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value);
704
705/**
706 * Use this function to read 32 bits of little-endian data from an
707 * SDL_IOStream and return in native format.
708 *
709 * SDL byteswaps the data only if necessary, so the data returned will be in
710 * the native byte order.
711 *
712 * \param src the stream from which to read data.
713 * \param value a pointer filled in with the data read.
714 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
715 * SDL_GetError() for more information.
716 *
717 * \since This function is available since SDL 3.0.0.
718 */
719extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value);
720
721/**
722 * Use this function to read 32 bits of little-endian data from an
723 * SDL_IOStream and return in native format.
724 *
725 * SDL byteswaps the data only if necessary, so the data returned will be in
726 * the native byte order.
727 *
728 * \param src the stream from which to read data.
729 * \param value a pointer filled in with the data read.
730 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
731 * SDL_GetError() for more information.
732 *
733 * \since This function is available since SDL 3.0.0.
734 */
735extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value);
736
737/**
738 * Use this function to read 32 bits of big-endian data from an SDL_IOStream
739 * and return in native format.
740 *
741 * SDL byteswaps the data only if necessary, so the data returned will be in
742 * the native byte order.
743 *
744 * \param src the stream from which to read data.
745 * \param value a pointer filled in with the data read.
746 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
747 * SDL_GetError() for more information.
748 *
749 * \since This function is available since SDL 3.0.0.
750 */
751extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value);
752
753/**
754 * Use this function to read 32 bits of big-endian data from an SDL_IOStream
755 * and return in native format.
756 *
757 * SDL byteswaps the data only if necessary, so the data returned will be in
758 * the native byte order.
759 *
760 * \param src the stream from which to read data.
761 * \param value a pointer filled in with the data read.
762 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
763 * SDL_GetError() for more information.
764 *
765 * \since This function is available since SDL 3.0.0.
766 */
767extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value);
768
769/**
770 * Use this function to read 64 bits of little-endian data from an
771 * SDL_IOStream and return in native format.
772 *
773 * SDL byteswaps the data only if necessary, so the data returned will be in
774 * the native byte order.
775 *
776 * \param src the stream from which to read data.
777 * \param value a pointer filled in with the data read.
778 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
779 * SDL_GetError() for more information.
780 *
781 * \since This function is available since SDL 3.0.0.
782 */
783extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value);
784
785/**
786 * Use this function to read 64 bits of little-endian data from an
787 * SDL_IOStream and return in native format.
788 *
789 * SDL byteswaps the data only if necessary, so the data returned will be in
790 * the native byte order.
791 *
792 * \param src the stream from which to read data.
793 * \param value a pointer filled in with the data read.
794 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
795 * SDL_GetError() for more information.
796 *
797 * \since This function is available since SDL 3.0.0.
798 */
799extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value);
800
801/**
802 * Use this function to read 64 bits of big-endian data from an SDL_IOStream
803 * and return in native format.
804 *
805 * SDL byteswaps the data only if necessary, so the data returned will be in
806 * the native byte order.
807 *
808 * \param src the stream from which to read data.
809 * \param value a pointer filled in with the data read.
810 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
811 * SDL_GetError() for more information.
812 *
813 * \since This function is available since SDL 3.0.0.
814 */
815extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value);
816
817/**
818 * Use this function to read 64 bits of big-endian data from an SDL_IOStream
819 * and return in native format.
820 *
821 * SDL byteswaps the data only if necessary, so the data returned will be in
822 * the native byte order.
823 *
824 * \param src the stream from which to read data.
825 * \param value a pointer filled in with the data read.
826 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
827 * SDL_GetError() for more information.
828 *
829 * \since This function is available since SDL 3.0.0.
830 */
831extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value);
832/* @} *//* Read endian functions */
833
834/**
835 * \name Write endian functions
836 *
837 * Write an item of native format to the specified endianness.
838 */
839/* @{ */
840
841/**
842 * Use this function to write a byte to an SDL_IOStream.
843 *
844 * \param dst the SDL_IOStream to write to.
845 * \param value the byte value to write.
846 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
847 * SDL_GetError() for more information.
848 *
849 * \since This function is available since SDL 3.0.0.
850 */
851extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value);
852
853/**
854 * Use this function to write a signed byte to an SDL_IOStream.
855 *
856 * \param dst the SDL_IOStream to write to.
857 * \param value the byte value to write.
858 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
859 * SDL_GetError() for more information.
860 *
861 * \since This function is available since SDL 3.0.0.
862 */
863extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value);
864
865/**
866 * Use this function to write 16 bits in native format to an SDL_IOStream as
867 * little-endian data.
868 *
869 * SDL byteswaps the data only if necessary, so the application always
870 * specifies native format, and the data written will be in little-endian
871 * format.
872 *
873 * \param dst the stream to which data will be written.
874 * \param value the data to be written, in native format.
875 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
876 * SDL_GetError() for more information.
877 *
878 * \since This function is available since SDL 3.0.0.
879 */
880extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value);
881
882/**
883 * Use this function to write 16 bits in native format to an SDL_IOStream as
884 * little-endian data.
885 *
886 * SDL byteswaps the data only if necessary, so the application always
887 * specifies native format, and the data written will be in little-endian
888 * format.
889 *
890 * \param dst the stream to which data will be written.
891 * \param value the data to be written, in native format.
892 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
893 * SDL_GetError() for more information.
894 *
895 * \since This function is available since SDL 3.0.0.
896 */
897extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value);
898
899/**
900 * Use this function to write 16 bits in native format to an SDL_IOStream as
901 * big-endian data.
902 *
903 * SDL byteswaps the data only if necessary, so the application always
904 * specifies native format, and the data written will be in big-endian format.
905 *
906 * \param dst the stream to which data will be written.
907 * \param value the data to be written, in native format.
908 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
909 * SDL_GetError() for more information.
910 *
911 * \since This function is available since SDL 3.0.0.
912 */
913extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value);
914
915/**
916 * Use this function to write 16 bits in native format to an SDL_IOStream as
917 * big-endian data.
918 *
919 * SDL byteswaps the data only if necessary, so the application always
920 * specifies native format, and the data written will be in big-endian format.
921 *
922 * \param dst the stream to which data will be written.
923 * \param value the data to be written, in native format.
924 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
925 * SDL_GetError() for more information.
926 *
927 * \since This function is available since SDL 3.0.0.
928 */
929extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value);
930
931/**
932 * Use this function to write 32 bits in native format to an SDL_IOStream as
933 * little-endian data.
934 *
935 * SDL byteswaps the data only if necessary, so the application always
936 * specifies native format, and the data written will be in little-endian
937 * format.
938 *
939 * \param dst the stream to which data will be written.
940 * \param value the data to be written, in native format.
941 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
942 * SDL_GetError() for more information.
943 *
944 * \since This function is available since SDL 3.0.0.
945 */
946extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value);
947
948/**
949 * Use this function to write 32 bits in native format to an SDL_IOStream as
950 * little-endian data.
951 *
952 * SDL byteswaps the data only if necessary, so the application always
953 * specifies native format, and the data written will be in little-endian
954 * format.
955 *
956 * \param dst the stream to which data will be written.
957 * \param value the data to be written, in native format.
958 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
959 * SDL_GetError() for more information.
960 *
961 * \since This function is available since SDL 3.0.0.
962 */
963extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value);
964
965/**
966 * Use this function to write 32 bits in native format to an SDL_IOStream as
967 * big-endian data.
968 *
969 * SDL byteswaps the data only if necessary, so the application always
970 * specifies native format, and the data written will be in big-endian format.
971 *
972 * \param dst the stream to which data will be written.
973 * \param value the data to be written, in native format.
974 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
975 * SDL_GetError() for more information.
976 *
977 * \since This function is available since SDL 3.0.0.
978 */
979extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value);
980
981/**
982 * Use this function to write 32 bits in native format to an SDL_IOStream as
983 * big-endian data.
984 *
985 * SDL byteswaps the data only if necessary, so the application always
986 * specifies native format, and the data written will be in big-endian format.
987 *
988 * \param dst the stream to which data will be written.
989 * \param value the data to be written, in native format.
990 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
991 * SDL_GetError() for more information.
992 *
993 * \since This function is available since SDL 3.0.0.
994 */
995extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value);
996
997/**
998 * Use this function to write 64 bits in native format to an SDL_IOStream as
999 * little-endian data.
1000 *
1001 * SDL byteswaps the data only if necessary, so the application always
1002 * specifies native format, and the data written will be in little-endian
1003 * format.
1004 *
1005 * \param dst the stream to which data will be written.
1006 * \param value the data to be written, in native format.
1007 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
1008 * SDL_GetError() for more information.
1009 *
1010 * \since This function is available since SDL 3.0.0.
1011 */
1012extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value);
1013
1014/**
1015 * Use this function to write 64 bits in native format to an SDL_IOStream as
1016 * little-endian data.
1017 *
1018 * SDL byteswaps the data only if necessary, so the application always
1019 * specifies native format, and the data written will be in little-endian
1020 * format.
1021 *
1022 * \param dst the stream to which data will be written.
1023 * \param value the data to be written, in native format.
1024 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
1025 * SDL_GetError() for more information.
1026 *
1027 * \since This function is available since SDL 3.0.0.
1028 */
1029extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value);
1030
1031/**
1032 * Use this function to write 64 bits in native format to an SDL_IOStream as
1033 * big-endian data.
1034 *
1035 * SDL byteswaps the data only if necessary, so the application always
1036 * specifies native format, and the data written will be in big-endian format.
1037 *
1038 * \param dst the stream to which data will be written.
1039 * \param value the data to be written, in native format.
1040 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
1041 * SDL_GetError() for more information.
1042 *
1043 * \since This function is available since SDL 3.0.0.
1044 */
1045extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value);
1046
1047/**
1048 * Use this function to write 64 bits in native format to an SDL_IOStream as
1049 * big-endian data.
1050 *
1051 * SDL byteswaps the data only if necessary, so the application always
1052 * specifies native format, and the data written will be in big-endian format.
1053 *
1054 * \param dst the stream to which data will be written.
1055 * \param value the data to be written, in native format.
1056 * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
1057 * SDL_GetError() for more information.
1058 *
1059 * \since This function is available since SDL 3.0.0.
1060 */
1061extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value);
1062
1063/* @} *//* Write endian functions */
1064
1065/* Ends C function definitions when using C++ */
1066#ifdef __cplusplus
1067}
1068#endif
1069#include <SDL3/SDL_close_code.h>
1070
1071#endif /* SDL_iostream_h_ */
SDL_bool SDL_ReadU8(SDL_IOStream *src, Uint8 *value)
SDL_IOStream * SDL_IOFromConstMem(const void *mem, size_t size)
SDL_IOStream * SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata)
SDL_IOStatus
@ SDL_IO_STATUS_ERROR
@ SDL_IO_STATUS_EOF
@ SDL_IO_STATUS_NOT_READY
@ SDL_IO_STATUS_READY
@ SDL_IO_STATUS_WRITEONLY
@ SDL_IO_STATUS_READONLY
SDL_bool SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value)
SDL_bool SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value)
SDL_bool SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value)
size_t SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size)
SDL_bool SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value)
Sint64 SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence)
SDL_bool SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value)
size_t SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2)
SDL_bool SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value)
SDL_bool SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value)
SDL_IOStream * SDL_IOFromFile(const char *file, const char *mode)
SDL_bool SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value)
Sint64 SDL_TellIO(SDL_IOStream *context)
SDL_bool SDL_CloseIO(SDL_IOStream *context)
SDL_bool SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value)
SDL_bool SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value)
size_t SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void * SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio)
SDL_bool SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value)
SDL_bool SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value)
SDL_bool SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value)
SDL_bool SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value)
SDL_bool SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value)
SDL_bool SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value)
SDL_IOStream * SDL_IOFromDynamicMem(void)
SDL_bool SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value)
SDL_bool SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value)
struct SDL_IOStream SDL_IOStream
SDL_bool SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
Sint64 SDL_GetIOSize(SDL_IOStream *context)
SDL_bool SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value)
SDL_bool SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value)
SDL_bool SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value)
SDL_bool SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
SDL_bool SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
SDL_bool SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value)
SDL_IOStatus SDL_GetIOStatus(SDL_IOStream *context)
SDL_IOStream * SDL_IOFromMem(void *mem, size_t size)
SDL_bool SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value)
SDL_PropertiesID SDL_GetIOProperties(SDL_IOStream *context)
SDL_bool SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value)
size_t SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size)
void * SDL_LoadFile(const char *file, size_t *datasize)
SDL_IOWhence
@ SDL_IO_SEEK_CUR
@ SDL_IO_SEEK_SET
@ SDL_IO_SEEK_END
Uint32 SDL_PropertiesID
uint8_t Uint8
Definition SDL_stdinc.h:232
int64_t Sint64
Definition SDL_stdinc.h:279
uint16_t Uint16
Definition SDL_stdinc.h:250
#define SDL_PRINTF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:459
int8_t Sint8
Definition SDL_stdinc.h:223
int32_t Sint32
Definition SDL_stdinc.h:259
SDL_MALLOC size_t size
Definition SDL_stdinc.h:535
int16_t Sint16
Definition SDL_stdinc.h:241
#define SDL_PRINTF_FORMAT_STRING
Definition SDL_stdinc.h:447
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:458
uint64_t Uint64
Definition SDL_stdinc.h:290
uint32_t Uint32
Definition SDL_stdinc.h:268
bool SDL_bool
Definition SDL_stdinc.h:216
Sint64(* size)(void *userdata)
size_t(* read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status)
Sint64(* seek)(void *userdata, Sint64 offset, SDL_IOWhence whence)
size_t(* write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status)
SDL_bool(* close)(void *userdata)