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