123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413 |
- /*
- Simple DirectMedia Layer
- Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
- This software is provided 'as-is', without any express or implied
- warranty. In no event will the authors be held liable for any damages
- arising from the use of this software.
- Permission is granted to anyone to use this software for any purpose,
- including commercial applications, and to alter it and redistribute it
- freely, subject to the following restrictions:
- 1. The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
- 2. Altered source versions must be plainly marked as such, and must not be
- misrepresented as being the original software.
- 3. This notice may not be removed or altered from any source distribution.
- */
- /**
- * \file SDL_rwops.h
- *
- * This file provides a general interface for SDL to read and write
- * data streams. It can easily be extended to files, memory, etc.
- */
- #ifndef SDL_rwops_h_
- #define SDL_rwops_h_
- #include "SDL_stdinc.h"
- #include "SDL_error.h"
- #include "begin_code.h"
- /* Set up for C function definitions, even when using C++ */
- #ifdef __cplusplus
- extern "C" {
- #endif
- /* RWops Types */
- #define SDL_RWOPS_UNKNOWN 0U /**< Unknown stream type */
- #define SDL_RWOPS_WINFILE 1U /**< Win32 file */
- #define SDL_RWOPS_STDFILE 2U /**< Stdio file */
- #define SDL_RWOPS_JNIFILE 3U /**< Android asset */
- #define SDL_RWOPS_MEMORY 4U /**< Memory stream */
- #define SDL_RWOPS_MEMORY_RO 5U /**< Read-Only memory stream */
- #if defined(__VITA__)
- #define SDL_RWOPS_VITAFILE 6U /**< Vita file */
- #endif
- /**
- * This is the read/write operation structure -- very basic.
- */
- typedef struct SDL_RWops
- {
- /**
- * Return the size of the file in this rwops, or -1 if unknown
- */
- Sint64 (SDLCALL * size) (struct SDL_RWops * context);
- /**
- * Seek to \c offset relative to \c whence, one of stdio's whence values:
- * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
- *
- * \return the final offset in the data stream, or -1 on error.
- */
- Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
- int whence);
- /**
- * Read up to \c maxnum objects each of size \c size from the data
- * stream to the area pointed at by \c ptr.
- *
- * \return the number of objects read, or 0 at error or end of file.
- */
- size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
- size_t size, size_t maxnum);
- /**
- * Write exactly \c num objects each of size \c size from the area
- * pointed at by \c ptr to data stream.
- *
- * \return the number of objects written, or 0 at error or end of file.
- */
- size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
- size_t size, size_t num);
- /**
- * Close and free an allocated SDL_RWops structure.
- *
- * \return 0 if successful or -1 on write error when flushing data.
- */
- int (SDLCALL * close) (struct SDL_RWops * context);
- Uint32 type;
- union
- {
- #if defined(__ANDROID__)
- struct
- {
- void *asset;
- } androidio;
- #elif defined(__WIN32__)
- struct
- {
- SDL_bool append;
- void *h;
- struct
- {
- void *data;
- size_t size;
- size_t left;
- } buffer;
- } windowsio;
- #elif defined(__VITA__)
- struct
- {
- int h;
- struct
- {
- void *data;
- size_t size;
- size_t left;
- } buffer;
- } vitaio;
- #endif
- #ifdef HAVE_STDIO_H
- struct
- {
- SDL_bool autoclose;
- FILE *fp;
- } stdio;
- #endif
- struct
- {
- Uint8 *base;
- Uint8 *here;
- Uint8 *stop;
- } mem;
- struct
- {
- void *data1;
- void *data2;
- } unknown;
- } hidden;
- } SDL_RWops;
- /**
- * \name RWFrom functions
- *
- * Functions to create SDL_RWops structures from various data streams.
- */
- /* @{ */
- extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
- const char *mode);
- #ifdef HAVE_STDIO_H
- extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp,
- SDL_bool autoclose);
- #else
- extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp,
- SDL_bool autoclose);
- #endif
- extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
- extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
- int size);
- /* @} *//* RWFrom functions */
- extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
- extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
- #define RW_SEEK_SET 0 /**< Seek from the beginning of data */
- #define RW_SEEK_CUR 1 /**< Seek relative to current read point */
- #define RW_SEEK_END 2 /**< Seek relative to the end of data */
- /**
- * Use this macro to get the size of the data stream in an SDL_RWops.
- *
- * \param context the SDL_RWops to get the size of the data stream from
- * \returns the size of the data stream in the SDL_RWops on success, -1 if
- * unknown or a negative error code on failure; call SDL_GetError()
- * for more information.
- *
- * \since This function is available since SDL 2.0.0.
- */
- extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
- /**
- * Seek within an SDL_RWops data stream.
- *
- * This function seeks to byte `offset`, relative to `whence`.
- *
- * `whence` may be any of the following values:
- *
- * - `RW_SEEK_SET`: seek from the beginning of data
- * - `RW_SEEK_CUR`: seek relative to current read point
- * - `RW_SEEK_END`: seek relative to the end of data
- *
- * If this stream can not seek, it will return -1.
- *
- * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
- * `seek` method appropriately, to simplify application development.
- *
- * \param context a pointer to an SDL_RWops structure
- * \param offset an offset in bytes, relative to **whence** location; can be
- * negative
- * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
- * \returns the final offset in the data stream after the seek or -1 on error.
- *
- * \sa SDL_RWclose
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromFP
- * \sa SDL_RWFromMem
- * \sa SDL_RWread
- * \sa SDL_RWtell
- * \sa SDL_RWwrite
- */
- extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
- Sint64 offset, int whence);
- /**
- * Determine the current read/write offset in an SDL_RWops data stream.
- *
- * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's
- * `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
- * application development.
- *
- * \param context a SDL_RWops data stream object from which to get the current
- * offset
- * \returns the current offset in the stream, or -1 if the information can not
- * be determined.
- *
- * \sa SDL_RWclose
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromFP
- * \sa SDL_RWFromMem
- * \sa SDL_RWread
- * \sa SDL_RWseek
- * \sa SDL_RWwrite
- */
- extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
- /**
- * Read from a data source.
- *
- * This function reads up to `maxnum` objects each of size `size` from the
- * data source to the area pointed at by `ptr`. This function may read less
- * objects than requested. It will return zero when there has been an error or
- * the data stream is completely read.
- *
- * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
- * `read` method appropriately, to simplify application development.
- *
- * \param context a pointer to an SDL_RWops structure
- * \param ptr a pointer to a buffer to read data into
- * \param size the size of each object to read, in bytes
- * \param maxnum the maximum number of objects to be read
- * \returns the number of objects read, or 0 at error or end of file; call
- * SDL_GetError() for more information.
- *
- * \sa SDL_RWclose
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromFP
- * \sa SDL_RWFromMem
- * \sa SDL_RWseek
- * \sa SDL_RWwrite
- */
- extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
- void *ptr, size_t size,
- size_t maxnum);
- /**
- * Write to an SDL_RWops data stream.
- *
- * This function writes exactly `num` objects each of size `size` from the
- * area pointed at by `ptr` to the stream. If this fails for any reason,
- * it'll return less than `num` to demonstrate how far the write progressed.
- * On success, it returns `num`.
- *
- * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
- * `write` method appropriately, to simplify application development.
- *
- * \param context a pointer to an SDL_RWops structure
- * \param ptr a pointer to a buffer containing data to write
- * \param size the size of an object to write, in bytes
- * \param num the number of objects to write
- * \returns the number of objects written, which will be less than **num** on
- * error; call SDL_GetError() for more information.
- *
- * \sa SDL_RWclose
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromFP
- * \sa SDL_RWFromMem
- * \sa SDL_RWread
- * \sa SDL_RWseek
- */
- extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
- const void *ptr, size_t size,
- size_t num);
- /**
- * Close and free an allocated SDL_RWops structure.
- *
- * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
- * resources used by the stream and frees the SDL_RWops itself with
- * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
- * flush to its output (e.g. to disk).
- *
- * Note that if this fails to flush the stream to disk, this function reports
- * an error, but the SDL_RWops is still invalid once this function returns.
- *
- * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close`
- * method appropriately, to simplify application development.
- *
- * \param context SDL_RWops structure to close
- * \returns 0 on success or a negative error code on failure; call
- * SDL_GetError() for more information.
- *
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromFP
- * \sa SDL_RWFromMem
- * \sa SDL_RWread
- * \sa SDL_RWseek
- * \sa SDL_RWwrite
- */
- extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
- /**
- * Load all the data from an SDL data stream.
- *
- * The data is allocated with a zero byte at the end (null terminated) for
- * convenience. This extra byte is not included in the value reported via
- * `datasize`.
- *
- * The data should be freed with SDL_free().
- *
- * \param src the SDL_RWops to read all available data from
- * \param datasize if not NULL, will store the number of bytes read
- * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
- * \returns the data, or NULL if there was an error.
- */
- extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
- size_t *datasize,
- int freesrc);
- /**
- * Load all the data from a file path.
- *
- * The data is allocated with a zero byte at the end (null terminated) for
- * convenience. This extra byte is not included in the value reported via
- * `datasize`.
- *
- * The data should be freed with SDL_free().
- *
- * \param file the path to read all available data from
- * \param datasize if not NULL, will store the number of bytes read
- * \returns the data, or NULL if there was an error.
- */
- extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
- /**
- * \name Read endian functions
- *
- * Read an item of the specified endianness and return in native format.
- */
- /* @{ */
- extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src);
- extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
- extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
- extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
- extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
- extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
- extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
- /* @} *//* Read endian functions */
- /**
- * \name Write endian functions
- *
- * Write an item of native format to the specified endianness.
- */
- /* @{ */
- extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
- extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
- /* @} *//* Write endian functions */
- /* Ends C function definitions when using C++ */
- #ifdef __cplusplus
- }
- #endif
- #include "close_code.h"
- #endif /* SDL_rwops_h_ */
- /* vi: set ts=4 sw=4 expandtab: */
|