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