Mercurial > sdl-ios-xcode

comparison include/SDL_rwops.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 5d7ef5970073
children d264d99576c1
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** 23 /**
24 * \file SDL_rwops.h 24 * \file SDL_rwops.h
25 * 25 *
26 * This file provides a general interface for SDL to read and write 26 * This file provides a general interface for SDL to read and write
27 * data sources. It can easily be extended to files, memory, etc. 27 * data sources. It can easily be extended to files, memory, etc.
28 */ 28 */
29 29
30 #ifndef _SDL_rwops_h 30 #ifndef _SDL_rwops_h
31 #define _SDL_rwops_h 31 #define _SDL_rwops_h
32 32
39 /* *INDENT-OFF* */ 39 /* *INDENT-OFF* */
40 extern "C" { 40 extern "C" {
41 /* *INDENT-ON* */ 41 /* *INDENT-ON* */
42 #endif 42 #endif
43 43
44 /* This is the read/write operation structure -- very basic */ 44 /**
45 45 * This is the read/write operation structure -- very basic.
46 */
46 typedef struct SDL_RWops 47 typedef struct SDL_RWops
47 { 48 {
48 /* Seek to 'offset' relative to whence, one of stdio's whence values: 49 /**
49 RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END 50 * Seek to \c offset relative to \c whence, one of stdio's whence values:
50 Returns the final offset in the data source. 51 * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
52 *
53 * \return the final offset in the data source.
51 */ 54 */
52 long (SDLCALL * seek) (struct SDL_RWops * context, long offset, 55 long (SDLCALL * seek) (struct SDL_RWops * context, long offset,
53 int whence); 56 int whence);
54 57
55 /* Read up to 'num' objects each of size 'objsize' from the data 58 /**
56 source to the area pointed at by 'ptr'. 59 * Read up to \c num objects each of size \c objsize from the data
57 Returns the number of objects read, or 0 at error or end of file. 60 * source to the area pointed at by \c ptr.
58 */ 61 *
59 size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr, 62 * \return the number of objects read, or 0 at error or end of file.
60 size_t size, size_t maxnum); 63 */
61 64 size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr,
62 /* Write exactly 'num' objects each of size 'objsize' from the area 65 size_t size, size_t maxnum);
63 pointed at by 'ptr' to data source. 66
64 Returns the number of objects written, or 0 at error or end of file. 67 /**
65 */ 68 * Write exactly \c num objects each of size \c objsize from the area
66 size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr, 69 * pointed at by \c ptr to data source.
67 size_t size, size_t num); 70 *
68 71 * \return the number of objects written, or 0 at error or end of file.
69 /* Close and free an allocated SDL_RWops structure. 72 */
70 Returns 0 if successful or -1 on write error when flushing data. 73 size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
74 size_t size, size_t num);
75
76 /**
77 * Close and free an allocated SDL_RWops structure.
78 *
79 * \return 0 if successful or -1 on write error when flushing data.
71 */ 80 */
72 int (SDLCALL * close) (struct SDL_RWops * context); 81 int (SDLCALL * close) (struct SDL_RWops * context);
73 82
74 Uint32 type; 83 Uint32 type;
75 union 84 union
107 } hidden; 116 } hidden;
108 117
109 } SDL_RWops; 118 } SDL_RWops;
110 119
111 120
112 /* Functions to create SDL_RWops structures from various data sources */ 121 /**
122 * \name RWFrom functions
123 *
124 * Functions to create SDL_RWops structures from various data sources.
125 */
126 /*@{*/
113 127
114 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file, 128 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
115 const char *mode); 129 const char *mode);
116 130
117 #ifdef HAVE_STDIO_H 131 #ifdef HAVE_STDIO_H
121 135
122 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); 136 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
123 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem, 137 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
124 int size); 138 int size);
125 139
140 /*@}*//*RWFrom functions*/
141
142
126 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); 143 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
127 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); 144 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
128 145
129 #define RW_SEEK_SET 0 /* Seek from the beginning of data */ 146 #define RW_SEEK_SET 0 /**< Seek from the beginning of data */
130 #define RW_SEEK_CUR 1 /* Seek relative to current read point */ 147 #define RW_SEEK_CUR 1 /**< Seek relative to current read point */
131 #define RW_SEEK_END 2 /* Seek relative to the end of data */ 148 #define RW_SEEK_END 2 /**< Seek relative to the end of data */
132 149
133 /* Macros to easily read and write from an SDL_RWops structure */ 150 /**
151 * \name Read/write macros
152 *
153 * Macros to easily read and write from an SDL_RWops structure.
154 */
155 /*@{*/
134 #define SDL_RWseek(ctx, offset, whence) (ctx)->seek(ctx, offset, whence) 156 #define SDL_RWseek(ctx, offset, whence) (ctx)->seek(ctx, offset, whence)
135 #define SDL_RWtell(ctx) (ctx)->seek(ctx, 0, RW_SEEK_CUR) 157 #define SDL_RWtell(ctx) (ctx)->seek(ctx, 0, RW_SEEK_CUR)
136 #define SDL_RWread(ctx, ptr, size, n) (ctx)->read(ctx, ptr, size, n) 158 #define SDL_RWread(ctx, ptr, size, n) (ctx)->read(ctx, ptr, size, n)
137 #define SDL_RWwrite(ctx, ptr, size, n) (ctx)->write(ctx, ptr, size, n) 159 #define SDL_RWwrite(ctx, ptr, size, n) (ctx)->write(ctx, ptr, size, n)
138 #define SDL_RWclose(ctx) (ctx)->close(ctx) 160 #define SDL_RWclose(ctx) (ctx)->close(ctx)
139 161 /*@}*//*Read/write macros*/
140 162
141 /* Read an item of the specified endianness and return in native format */ 163
164 /**
165 * \name Read endian functions
166 *
167 * Read an item of the specified endianness and return in native format.
168 */
169 /*@{*/
142 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); 170 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
143 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); 171 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
144 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); 172 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
145 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); 173 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
146 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); 174 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
147 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); 175 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
148 176 /*@}*//*Read endian functions*/
149 /* Write an item of native format to the specified endianness */ 177
178 /**
179 * \name Write endian functions
180 *
181 * Write an item of native format to the specified endianness.
182 */
183 /*@{*/
150 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); 184 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
151 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value); 185 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
152 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); 186 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
153 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value); 187 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
154 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); 188 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
155 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value); 189 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
190 /*@}*//*Write endian functions*/
156 191
157 192
158 /* Ends C function definitions when using C++ */ 193 /* Ends C function definitions when using C++ */
159 #ifdef __cplusplus 194 #ifdef __cplusplus
160 /* *INDENT-OFF* */ 195 /* *INDENT-OFF* */