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_rwops.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
29#ifndef SDL_rwops_h_
30#define SDL_rwops_h_
31
32#include "SDL_stdinc.h"
33#include "SDL_error.h"
34
35#include "begin_code.h"
36/* Set up for C function definitions, even when using C++ */
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/* RWops Types */
42#define SDL_RWOPS_UNKNOWN 0U /**< Unknown stream type */
43#define SDL_RWOPS_WINFILE 1U /**< Win32 file */
44#define SDL_RWOPS_STDFILE 2U /**< Stdio file */
45#define SDL_RWOPS_JNIFILE 3U /**< Android asset */
46#define SDL_RWOPS_MEMORY 4U /**< Memory stream */
47#define SDL_RWOPS_MEMORY_RO 5U /**< Read-Only memory stream */
48
49/**
50 * This is the read/write operation structure -- very basic.
51 */
52typedef struct SDL_RWops
53{
54 /**
55 * Return the size of the file in this rwops, or -1 if unknown
56 */
57 Sint64 (SDLCALL * size) (struct SDL_RWops * context);
58
59 /**
60 * Seek to \c offset relative to \c whence, one of stdio's whence values:
61 * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
62 *
63 * \return the final offset in the data stream, or -1 on error.
64 */
65 Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
66 int whence);
67
68 /**
69 * Read up to \c maxnum objects each of size \c size from the data
70 * stream to the area pointed at by \c ptr.
71 *
72 * \return the number of objects read, or 0 at error or end of file.
73 */
74 size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
75 size_t size, size_t maxnum);
76
77 /**
78 * Write exactly \c num objects each of size \c size from the area
79 * pointed at by \c ptr to data stream.
80 *
81 * \return the number of objects written, or 0 at error or end of file.
82 */
83 size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
84 size_t size, size_t num);
85
86 /**
87 * Close and free an allocated SDL_RWops structure.
88 *
89 * \return 0 if successful or -1 on write error when flushing data.
90 */
91 int (SDLCALL * close) (struct SDL_RWops * context);
92
93 Uint32 type;
94 union
95 {
96#if defined(__ANDROID__)
97 struct
98 {
99 void *asset;
100 } androidio;
101#elif defined(__WIN32__) || defined(__GDK__)
102 struct
103 {
104 SDL_bool append;
105 void *h;
106 struct
107 {
108 void *data;
109 size_t size;
110 size_t left;
111 } buffer;
112 } windowsio;
113#endif
114
115#ifdef HAVE_STDIO_H
116 struct
117 {
118 SDL_bool autoclose;
119 FILE *fp;
120 } stdio;
121#endif
122 struct
123 {
124 Uint8 *base;
125 Uint8 *here;
126 Uint8 *stop;
127 } mem;
128 struct
129 {
130 void *data1;
131 void *data2;
132 } unknown;
133 } hidden;
134
135} SDL_RWops;
136
137
138/**
139 * \name RWFrom functions
140 *
141 * Functions to create SDL_RWops structures from various data streams.
142 */
143/* @{ */
144
145/**
146 * Use this function to create a new SDL_RWops structure for reading from
147 * and/or writing to a named file.
148 *
149 * The `mode` string is treated roughly the same as in a call to the C
150 * library's fopen(), even if SDL doesn't happen to use fopen() behind the
151 * scenes.
152 *
153 * Available `mode` strings:
154 *
155 * - "r": Open a file for reading. The file must exist.
156 * - "w": Create an empty file for writing. If a file with the same name
157 * already exists its content is erased and the file is treated as a new
158 * empty file.
159 * - "a": Append to a file. Writing operations append data at the end of the
160 * file. The file is created if it does not exist.
161 * - "r+": Open a file for update both reading and writing. The file must
162 * exist.
163 * - "w+": Create an empty file for both reading and writing. If a file with
164 * the same name already exists its content is erased and the file is
165 * treated as a new empty file.
166 * - "a+": Open a file for reading and appending. All writing operations are
167 * performed at the end of the file, protecting the previous content to be
168 * overwritten. You can reposition (fseek, rewind) the internal pointer to
169 * anywhere in the file for reading, but writing operations will move it
170 * back to the end of file. The file is created if it does not exist.
171 *
172 * **NOTE**: In order to open a file as a binary file, a "b" character has to
173 * be included in the `mode` string. This additional "b" character can either
174 * be appended at the end of the string (thus making the following compound
175 * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the
176 * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+").
177 * Additional characters may follow the sequence, although they should have no
178 * effect. For example, "t" is sometimes appended to make explicit the file is
179 * a text file.
180 *
181 * This function supports Unicode filenames, but they must be encoded in UTF-8
182 * format, regardless of the underlying operating system.
183 *
184 * As a fallback, SDL_RWFromFile() will transparently open a matching filename
185 * in an Android app's `assets`.
186 *
187 * Closing the SDL_RWops will close the file handle SDL is holding internally.
188 *
189 * \param file a UTF-8 string representing the filename to open
190 * \param mode an ASCII string representing the mode to be used for opening
191 * the file.
192 * \returns a pointer to the SDL_RWops structure that is created, or NULL on
193 * failure; call SDL_GetError() for more information.
194 *
195 * \since This function is available since SDL 2.0.0.
196 *
197 * \sa SDL_RWclose
198 * \sa SDL_RWFromConstMem
199 * \sa SDL_RWFromFP
200 * \sa SDL_RWFromMem
201 * \sa SDL_RWread
202 * \sa SDL_RWseek
203 * \sa SDL_RWtell
204 * \sa SDL_RWwrite
205 */
206extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
207 const char *mode);
208
209#ifdef HAVE_STDIO_H
210
211extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose);
212
213#else
214
215/**
216 * Use this function to create an SDL_RWops structure from a standard I/O file
217 * pointer (stdio.h's `FILE*`).
218 *
219 * This function is not available on Windows, since files opened in an
220 * application on that platform cannot be used by a dynamically linked
221 * library.
222 *
223 * On some platforms, the first parameter is a `void*`, on others, it's a
224 * `FILE*`, depending on what system headers are available to SDL. It is
225 * always intended to be the `FILE*` type from the C runtime's stdio.h.
226 *
227 * \param fp the `FILE*` that feeds the SDL_RWops stream
228 * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops,
229 * SDL_FALSE to leave the `FILE*` open when the RWops is
230 * closed
231 * \returns a pointer to the SDL_RWops structure that is created, or NULL on
232 * failure; call SDL_GetError() for more information.
233 *
234 * \since This function is available since SDL 2.0.0.
235 *
236 * \sa SDL_RWclose
237 * \sa SDL_RWFromConstMem
238 * \sa SDL_RWFromFile
239 * \sa SDL_RWFromMem
240 * \sa SDL_RWread
241 * \sa SDL_RWseek
242 * \sa SDL_RWtell
243 * \sa SDL_RWwrite
244 */
245extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp,
246 SDL_bool autoclose);
247#endif
248
249/**
250 * Use this function to prepare a read-write memory buffer for use with
251 * SDL_RWops.
252 *
253 * This function sets up an SDL_RWops struct based on a memory area of a
254 * certain size, for both read and write access.
255 *
256 * This memory buffer is not copied by the RWops; the pointer you provide must
257 * remain valid until you close the stream. Closing the stream will not free
258 * the original buffer.
259 *
260 * If you need to make sure the RWops never writes to the memory buffer, you
261 * should use SDL_RWFromConstMem() with a read-only buffer of memory instead.
262 *
263 * \param mem a pointer to a buffer to feed an SDL_RWops stream
264 * \param size the buffer size, in bytes
265 * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call
266 * SDL_GetError() for more information.
267 *
268 * \since This function is available since SDL 2.0.0.
269 *
270 * \sa SDL_RWclose
271 * \sa SDL_RWFromConstMem
272 * \sa SDL_RWFromFile
273 * \sa SDL_RWFromFP
274 * \sa SDL_RWFromMem
275 * \sa SDL_RWread
276 * \sa SDL_RWseek
277 * \sa SDL_RWtell
278 * \sa SDL_RWwrite
279 */
280extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
281
282/**
283 * Use this function to prepare a read-only memory buffer for use with RWops.
284 *
285 * This function sets up an SDL_RWops struct based on a memory area of a
286 * certain size. It assumes the memory area is not writable.
287 *
288 * Attempting to write to this RWops stream will report an error without
289 * writing to the memory buffer.
290 *
291 * This memory buffer is not copied by the RWops; the pointer you provide must
292 * remain valid until you close the stream. Closing the stream will not free
293 * the original buffer.
294 *
295 * If you need to write to a memory buffer, you should use SDL_RWFromMem()
296 * with a writable buffer of memory instead.
297 *
298 * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream
299 * \param size the buffer size, in bytes
300 * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call
301 * SDL_GetError() for more information.
302 *
303 * \since This function is available since SDL 2.0.0.
304 *
305 * \sa SDL_RWclose
306 * \sa SDL_RWFromConstMem
307 * \sa SDL_RWFromFile
308 * \sa SDL_RWFromFP
309 * \sa SDL_RWFromMem
310 * \sa SDL_RWread
311 * \sa SDL_RWseek
312 * \sa SDL_RWtell
313 */
314extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
315 int size);
316
317/* @} *//* RWFrom functions */
318
319
320/**
321 * Use this function to allocate an empty, unpopulated SDL_RWops structure.
322 *
323 * Applications do not need to use this function unless they are providing
324 * their own SDL_RWops implementation. If you just need a SDL_RWops to
325 * read/write a common data source, you should use the built-in
326 * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc.
327 *
328 * You must free the returned pointer with SDL_FreeRW(). Depending on your
329 * operating system and compiler, there may be a difference between the
330 * malloc() and free() your program uses and the versions SDL calls
331 * internally. Trying to mix the two can cause crashing such as segmentation
332 * faults. Since all SDL_RWops must free themselves when their **close**
333 * method is called, all SDL_RWops must be allocated through this function, so
334 * they can all be freed correctly with SDL_FreeRW().
335 *
336 * \returns a pointer to the allocated memory on success, or NULL on failure;
337 * call SDL_GetError() for more information.
338 *
339 * \since This function is available since SDL 2.0.0.
340 *
341 * \sa SDL_FreeRW
342 */
343extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
344
345/**
346 * Use this function to free an SDL_RWops structure allocated by
347 * SDL_AllocRW().
348 *
349 * Applications do not need to use this function unless they are providing
350 * their own SDL_RWops implementation. If you just need a SDL_RWops to
351 * read/write a common data source, you should use the built-in
352 * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc, and
353 * call the **close** method on those SDL_RWops pointers when you are done
354 * with them.
355 *
356 * Only use SDL_FreeRW() on pointers returned by SDL_AllocRW(). The pointer is
357 * invalid as soon as this function returns. Any extra memory allocated during
358 * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must
359 * be responsible for managing that memory in their **close** method.
360 *
361 * \param area the SDL_RWops structure to be freed
362 *
363 * \since This function is available since SDL 2.0.0.
364 *
365 * \sa SDL_AllocRW
366 */
367extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
368
369#define RW_SEEK_SET 0 /**< Seek from the beginning of data */
370#define RW_SEEK_CUR 1 /**< Seek relative to current read point */
371#define RW_SEEK_END 2 /**< Seek relative to the end of data */
372
373/**
374 * Use this function to get the size of the data stream in an SDL_RWops.
375 *
376 * Prior to SDL 2.0.10, this function was a macro.
377 *
378 * \param context the SDL_RWops to get the size of the data stream from
379 * \returns the size of the data stream in the SDL_RWops on success, -1 if
380 * unknown or a negative error code on failure; call SDL_GetError()
381 * for more information.
382 *
383 * \since This function is available since SDL 2.0.10.
384 */
385extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
386
387/**
388 * Seek within an SDL_RWops data stream.
389 *
390 * This function seeks to byte `offset`, relative to `whence`.
391 *
392 * `whence` may be any of the following values:
393 *
394 * - `RW_SEEK_SET`: seek from the beginning of data
395 * - `RW_SEEK_CUR`: seek relative to current read point
396 * - `RW_SEEK_END`: seek relative to the end of data
397 *
398 * If this stream can not seek, it will return -1.
399 *
400 * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
401 * `seek` method appropriately, to simplify application development.
402 *
403 * Prior to SDL 2.0.10, this function was a macro.
404 *
405 * \param context a pointer to an SDL_RWops structure
406 * \param offset an offset in bytes, relative to **whence** location; can be
407 * negative
408 * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
409 * \returns the final offset in the data stream after the seek or -1 on error.
410 *
411 * \since This function is available since SDL 2.0.10.
412 *
413 * \sa SDL_RWclose
414 * \sa SDL_RWFromConstMem
415 * \sa SDL_RWFromFile
416 * \sa SDL_RWFromFP
417 * \sa SDL_RWFromMem
418 * \sa SDL_RWread
419 * \sa SDL_RWtell
420 * \sa SDL_RWwrite
421 */
422extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
423 Sint64 offset, int whence);
424
425/**
426 * Determine the current read/write offset in an SDL_RWops data stream.
427 *
428 * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
429 * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
430 * application development.
431 *
432 * Prior to SDL 2.0.10, this function was a macro.
433 *
434 * \param context a SDL_RWops data stream object from which to get the current
435 * offset
436 * \returns the current offset in the stream, or -1 if the information can not
437 * be determined.
438 *
439 * \since This function is available since SDL 2.0.10.
440 *
441 * \sa SDL_RWclose
442 * \sa SDL_RWFromConstMem
443 * \sa SDL_RWFromFile
444 * \sa SDL_RWFromFP
445 * \sa SDL_RWFromMem
446 * \sa SDL_RWread
447 * \sa SDL_RWseek
448 * \sa SDL_RWwrite
449 */
450extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
451
452/**
453 * Read from a data source.
454 *
455 * This function reads up to `maxnum` objects each of size `size` from the
456 * data source to the area pointed at by `ptr`. This function may read less
457 * objects than requested. It will return zero when there has been an error or
458 * the data stream is completely read.
459 *
460 * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
461 * `read` method appropriately, to simplify application development.
462 *
463 * Prior to SDL 2.0.10, this function was a macro.
464 *
465 * \param context a pointer to an SDL_RWops structure
466 * \param ptr a pointer to a buffer to read data into
467 * \param size the size of each object to read, in bytes
468 * \param maxnum the maximum number of objects to be read
469 * \returns the number of objects read, or 0 at error or end of file; call
470 * SDL_GetError() for more information.
471 *
472 * \since This function is available since SDL 2.0.10.
473 *
474 * \sa SDL_RWclose
475 * \sa SDL_RWFromConstMem
476 * \sa SDL_RWFromFile
477 * \sa SDL_RWFromFP
478 * \sa SDL_RWFromMem
479 * \sa SDL_RWseek
480 * \sa SDL_RWwrite
481 */
482extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
483 void *ptr, size_t size,
484 size_t maxnum);
485
486/**
487 * Write to an SDL_RWops data stream.
488 *
489 * This function writes exactly `num` objects each of size `size` from the
490 * area pointed at by `ptr` to the stream. If this fails for any reason, it'll
491 * return less than `num` to demonstrate how far the write progressed. On
492 * success, it returns `num`.
493 *
494 * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
495 * `write` method appropriately, to simplify application development.
496 *
497 * Prior to SDL 2.0.10, this function was a macro.
498 *
499 * \param context a pointer to an SDL_RWops structure
500 * \param ptr a pointer to a buffer containing data to write
501 * \param size the size of an object to write, in bytes
502 * \param num the number of objects to write
503 * \returns the number of objects written, which will be less than **num** on
504 * error; call SDL_GetError() for more information.
505 *
506 * \since This function is available since SDL 2.0.10.
507 *
508 * \sa SDL_RWclose
509 * \sa SDL_RWFromConstMem
510 * \sa SDL_RWFromFile
511 * \sa SDL_RWFromFP
512 * \sa SDL_RWFromMem
513 * \sa SDL_RWread
514 * \sa SDL_RWseek
515 */
516extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
517 const void *ptr, size_t size,
518 size_t num);
519
520/**
521 * Close and free an allocated SDL_RWops structure.
522 *
523 * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
524 * resources used by the stream and frees the SDL_RWops itself with
525 * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
526 * flush to its output (e.g. to disk).
527 *
528 * Note that if this fails to flush the stream to disk, this function reports
529 * an error, but the SDL_RWops is still invalid once this function returns.
530 *
531 * Prior to SDL 2.0.10, this function was a macro.
532 *
533 * \param context SDL_RWops structure to close
534 * \returns 0 on success or a negative error code on failure; call
535 * SDL_GetError() for more information.
536 *
537 * \since This function is available since SDL 2.0.10.
538 *
539 * \sa SDL_RWFromConstMem
540 * \sa SDL_RWFromFile
541 * \sa SDL_RWFromFP
542 * \sa SDL_RWFromMem
543 * \sa SDL_RWread
544 * \sa SDL_RWseek
545 * \sa SDL_RWwrite
546 */
547extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
548
549/**
550 * Load all the data from an SDL data stream.
551 *
552 * The data is allocated with a zero byte at the end (null terminated) for
553 * convenience. This extra byte is not included in the value reported via
554 * `datasize`.
555 *
556 * The data should be freed with SDL_free().
557 *
558 * \param src the SDL_RWops to read all available data from
559 * \param datasize if not NULL, will store the number of bytes read
560 * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
561 * \returns the data, or NULL if there was an error.
562 *
563 * \since This function is available since SDL 2.0.6.
564 */
565extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
566 size_t *datasize,
567 int freesrc);
568
569/**
570 * Load all the data from a file path.
571 *
572 * The data is allocated with a zero byte at the end (null terminated) for
573 * convenience. This extra byte is not included in the value reported via
574 * `datasize`.
575 *
576 * The data should be freed with SDL_free().
577 *
578 * Prior to SDL 2.0.10, this function was a macro wrapping around
579 * SDL_LoadFile_RW.
580 *
581 * \param file the path to read all available data from
582 * \param datasize if not NULL, will store the number of bytes read
583 * \returns the data, or NULL if there was an error.
584 *
585 * \since This function is available since SDL 2.0.10.
586 */
587extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
588
589/**
590 * \name Read endian functions
591 *
592 * Read an item of the specified endianness and return in native format.
593 */
594/* @{ */
595
596/**
597 * Use this function to read a byte from an SDL_RWops.
598 *
599 * \param src the SDL_RWops to read from
600 * \returns the read byte on success or 0 on failure; call SDL_GetError() for
601 * more information.
602 *
603 * \since This function is available since SDL 2.0.0.
604 *
605 * \sa SDL_WriteU8
606 */
607extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src);
608
609/**
610 * Use this function to read 16 bits of little-endian data from an SDL_RWops
611 * and return in native format.
612 *
613 * SDL byteswaps the data only if necessary, so the data returned will be in
614 * the native byte order.
615 *
616 * \param src the stream from which to read data
617 * \returns 16 bits of data in the native byte order of the platform.
618 *
619 * \since This function is available since SDL 2.0.0.
620 *
621 * \sa SDL_ReadBE16
622 */
623extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
624
625/**
626 * Use this function to read 16 bits of big-endian data from an SDL_RWops and
627 * return in native format.
628 *
629 * SDL byteswaps the data only if necessary, so the data returned will be in
630 * the native byte order.
631 *
632 * \param src the stream from which to read data
633 * \returns 16 bits of data in the native byte order of the platform.
634 *
635 * \since This function is available since SDL 2.0.0.
636 *
637 * \sa SDL_ReadLE16
638 */
639extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
640
641/**
642 * Use this function to read 32 bits of little-endian data from an SDL_RWops
643 * 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 * \returns 32 bits of data in the native byte order of the platform.
650 *
651 * \since This function is available since SDL 2.0.0.
652 *
653 * \sa SDL_ReadBE32
654 */
655extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
656
657/**
658 * Use this function to read 32 bits of big-endian data from an SDL_RWops and
659 * 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 * \returns 32 bits of data in the native byte order of the platform.
666 *
667 * \since This function is available since SDL 2.0.0.
668 *
669 * \sa SDL_ReadLE32
670 */
671extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
672
673/**
674 * Use this function to read 64 bits of little-endian data from an SDL_RWops
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 * \returns 64 bits of data in the native byte order of the platform.
682 *
683 * \since This function is available since SDL 2.0.0.
684 *
685 * \sa SDL_ReadBE64
686 */
687extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
688
689/**
690 * Use this function to read 64 bits of big-endian data from an SDL_RWops and
691 * 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 * \returns 64 bits of data in the native byte order of the platform.
698 *
699 * \since This function is available since SDL 2.0.0.
700 *
701 * \sa SDL_ReadLE64
702 */
703extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
704/* @} *//* Read endian functions */
705
706/**
707 * \name Write endian functions
708 *
709 * Write an item of native format to the specified endianness.
710 */
711/* @{ */
712
713/**
714 * Use this function to write a byte to an SDL_RWops.
715 *
716 * \param dst the SDL_RWops to write to
717 * \param value the byte value to write
718 * \returns 1 on success or 0 on failure; call SDL_GetError() for more
719 * information.
720 *
721 * \since This function is available since SDL 2.0.0.
722 *
723 * \sa SDL_ReadU8
724 */
725extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value);
726
727/**
728 * Use this function to write 16 bits in native format to a SDL_RWops as
729 * little-endian data.
730 *
731 * SDL byteswaps the data only if necessary, so the application always
732 * specifies native format, and the data written will be in little-endian
733 * format.
734 *
735 * \param dst the stream to which data will be written
736 * \param value the data to be written, in native format
737 * \returns 1 on successful write, 0 on error.
738 *
739 * \since This function is available since SDL 2.0.0.
740 *
741 * \sa SDL_WriteBE16
742 */
743extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
744
745/**
746 * Use this function to write 16 bits in native format to a SDL_RWops as
747 * big-endian data.
748 *
749 * SDL byteswaps the data only if necessary, so the application always
750 * specifies native format, and the data written will be in big-endian format.
751 *
752 * \param dst the stream to which data will be written
753 * \param value the data to be written, in native format
754 * \returns 1 on successful write, 0 on error.
755 *
756 * \since This function is available since SDL 2.0.0.
757 *
758 * \sa SDL_WriteLE16
759 */
760extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
761
762/**
763 * Use this function to write 32 bits in native format to a SDL_RWops as
764 * little-endian data.
765 *
766 * SDL byteswaps the data only if necessary, so the application always
767 * specifies native format, and the data written will be in little-endian
768 * format.
769 *
770 * \param dst the stream to which data will be written
771 * \param value the data to be written, in native format
772 * \returns 1 on successful write, 0 on error.
773 *
774 * \since This function is available since SDL 2.0.0.
775 *
776 * \sa SDL_WriteBE32
777 */
778extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
779
780/**
781 * Use this function to write 32 bits in native format to a SDL_RWops as
782 * big-endian data.
783 *
784 * SDL byteswaps the data only if necessary, so the application always
785 * specifies native format, and the data written will be in big-endian format.
786 *
787 * \param dst the stream to which data will be written
788 * \param value the data to be written, in native format
789 * \returns 1 on successful write, 0 on error.
790 *
791 * \since This function is available since SDL 2.0.0.
792 *
793 * \sa SDL_WriteLE32
794 */
795extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
796
797/**
798 * Use this function to write 64 bits in native format to a SDL_RWops as
799 * little-endian data.
800 *
801 * SDL byteswaps the data only if necessary, so the application always
802 * specifies native format, and the data written will be in little-endian
803 * format.
804 *
805 * \param dst the stream to which data will be written
806 * \param value the data to be written, in native format
807 * \returns 1 on successful write, 0 on error.
808 *
809 * \since This function is available since SDL 2.0.0.
810 *
811 * \sa SDL_WriteBE64
812 */
813extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
814
815/**
816 * Use this function to write 64 bits in native format to a SDL_RWops as
817 * big-endian data.
818 *
819 * SDL byteswaps the data only if necessary, so the application always
820 * specifies native format, and the data written will be in big-endian format.
821 *
822 * \param dst the stream to which data will be written
823 * \param value the data to be written, in native format
824 * \returns 1 on successful write, 0 on error.
825 *
826 * \since This function is available since SDL 2.0.0.
827 *
828 * \sa SDL_WriteLE64
829 */
830extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
831/* @} *//* Write endian functions */
832
833/* Ends C function definitions when using C++ */
834#ifdef __cplusplus
835}
836#endif
837#include "close_code.h"
838
839#endif /* SDL_rwops_h_ */
840
841/* vi: set ts=4 sw=4 expandtab: */
842