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 |
38 | extern "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 | */ |
52 | typedef 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 | */ |
206 | extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file, |
207 | const char *mode); |
208 | |
209 | #ifdef HAVE_STDIO_H |
210 | |
211 | extern 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 | */ |
245 | extern 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 | */ |
280 | extern 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 | */ |
314 | extern 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 | */ |
343 | extern 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 | */ |
367 | extern 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 | */ |
385 | extern 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 | */ |
422 | extern 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 | */ |
450 | extern 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 | */ |
482 | extern 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 | */ |
516 | extern 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 | */ |
547 | extern 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 | */ |
565 | extern 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 | */ |
587 | extern 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 | */ |
607 | extern 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 | */ |
623 | extern 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 | */ |
639 | extern 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 | */ |
655 | extern 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 | */ |
671 | extern 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 | */ |
687 | extern 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 | */ |
703 | extern 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 | */ |
725 | extern 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 | */ |
743 | extern 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 | */ |
760 | extern 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 | */ |
778 | extern 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 | */ |
795 | extern 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 | */ |
813 | extern 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 | */ |
830 | extern 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 | |