diff options
author | Alessio Vanni <vannilla@firemail.cc> | 2020-05-14 16:03:10 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-05-19 02:41:47 +0200 |
commit | f4771fcc1c3fda21a46d0cb85d8b29e012254696 (patch) | |
tree | 012df74ed2cf44cb20605b239e1b88dab6edc645 /src/include | |
parent | 6a52ce5f9bc35a852b215e7073f3a0d2665ca8de (diff) | |
download | gnunet-f4771fcc1c3fda21a46d0cb85d8b29e012254696.tar.gz gnunet-f4771fcc1c3fda21a46d0cb85d8b29e012254696.zip |
Improved BIO API
BIO now supports reading from and writing to in-memory buffers.
For reading, an allocated buffer (array) and a size is passed as arguments to
the function opening the handle.
For writing, a GNUNET_Buffer is created and used internally. The buffer
contents can be extracted using the relevant function.
There is a new API in addition to the existing read/write: this new API is
more "declarative" in nature and is meant to mimic APIs like GNUNET_SQ.
The read/write operations are defined in an array of specs which are then
"commited" in a single (non-atomic) operation, rather than explicitly
executing multiple function calls and checking their return value.
Also there are small changes to GNUNET_Buffer to account for BIO's new
features.
Signed-off-by: Christian Grothoff <christian@grothoff.org>
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_bio_lib.h | 559 | ||||
-rw-r--r-- | src/include/gnunet_buffer_lib.h | 13 |
2 files changed, 475 insertions, 97 deletions
diff --git a/src/include/gnunet_bio_lib.h b/src/include/gnunet_bio_lib.h index 2f715ec97..687334c1c 100644 --- a/src/include/gnunet_bio_lib.h +++ b/src/include/gnunet_bio_lib.h | |||
@@ -42,6 +42,8 @@ extern "C" | |||
42 | #endif | 42 | #endif |
43 | #endif | 43 | #endif |
44 | 44 | ||
45 | /****************************** READING API *******************************/ | ||
46 | |||
45 | /** | 47 | /** |
46 | * Handle for buffered reading. | 48 | * Handle for buffered reading. |
47 | */ | 49 | */ |
@@ -55,11 +57,22 @@ struct GNUNET_BIO_ReadHandle; | |||
55 | * @return IO handle on success, NULL on error | 57 | * @return IO handle on success, NULL on error |
56 | */ | 58 | */ |
57 | struct GNUNET_BIO_ReadHandle * | 59 | struct GNUNET_BIO_ReadHandle * |
58 | GNUNET_BIO_read_open (const char *fn); | 60 | GNUNET_BIO_read_open_file (const char *fn); |
61 | |||
62 | |||
63 | /** | ||
64 | * Create a handle from an existing allocated buffer. | ||
65 | * | ||
66 | * @param buffer the buffer to use as source | ||
67 | * @param size the total size in bytes of the buffer | ||
68 | * @return IO handle on sucess, NULL on error | ||
69 | */ | ||
70 | struct GNUNET_BIO_ReadHandle * | ||
71 | GNUNET_BIO_read_open_buffer (void *buffer, size_t size); | ||
59 | 72 | ||
60 | 73 | ||
61 | /** | 74 | /** |
62 | * Close an open file. Reports if any errors reading | 75 | * Close an open handle. Reports if any errors reading |
63 | * from the file were encountered. | 76 | * from the file were encountered. |
64 | * | 77 | * |
65 | * @param h file handle | 78 | * @param h file handle |
@@ -71,51 +84,40 @@ GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg); | |||
71 | 84 | ||
72 | 85 | ||
73 | /** | 86 | /** |
74 | * Read the contents of a binary file into a buffer. | 87 | * Read some contents into a buffer. |
75 | * | 88 | * |
76 | * @param h handle to an open file | 89 | * @param h the IO handle to read from |
77 | * @param what describes what is being read (for error message creation) | 90 | * @param what describes what is being read (for error message creation) |
78 | * @param result the buffer to write the result to | 91 | * @param result the buffer to write the result to |
79 | * @param len the number of bytes to read | 92 | * @param len the number of bytes to read |
80 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | 93 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
81 | */ | 94 | */ |
82 | int | 95 | int |
83 | GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what, | 96 | GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, |
84 | void *result, size_t len); | 97 | const char *what, |
98 | void *result, | ||
99 | size_t len); | ||
85 | 100 | ||
86 | 101 | ||
87 | /** | 102 | /** |
88 | * Read the contents of a binary file into a buffer. | 103 | * Read 0-terminated string. |
89 | * | 104 | * |
90 | * @param h handle to an open file | 105 | * @param h the IO handle to read from |
91 | * @param file name of the source file | ||
92 | * @param line line number in the source file | ||
93 | * @param result the buffer to write the result to | ||
94 | * @param len the number of bytes to read | ||
95 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
96 | */ | ||
97 | int | ||
98 | GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h, | ||
99 | const char *file, int line, | ||
100 | void *result, size_t len); | ||
101 | |||
102 | /** | ||
103 | * Read 0-terminated string from a file. | ||
104 | * | ||
105 | * @param h handle to an open file | ||
106 | * @param what describes what is being read (for error message creation) | 106 | * @param what describes what is being read (for error message creation) |
107 | * @param result the buffer to store a pointer to the (allocated) string to | 107 | * @param result where to store the pointer to the (allocated) string |
108 | * (note that *result could be set to NULL as well) | 108 | * (note that *result could be set to NULL as well) |
109 | * @param max_length maximum allowed length for the string | 109 | * @param max_length maximum allowed length for the string |
110 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | 110 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
111 | */ | 111 | */ |
112 | int | 112 | int |
113 | GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what, | 113 | GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, |
114 | char **result, size_t max_length); | 114 | const char *what, |
115 | char **result, | ||
116 | size_t max_length); | ||
115 | 117 | ||
116 | 118 | ||
117 | /** | 119 | /** |
118 | * Read metadata container from a file. | 120 | * Read a metadata container. |
119 | * | 121 | * |
120 | * @param h handle to an open file | 122 | * @param h handle to an open file |
121 | * @param what describes what is being read (for error message creation) | 123 | * @param what describes what is being read (for error message creation) |
@@ -123,79 +125,69 @@ GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what, | |||
123 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | 125 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
124 | */ | 126 | */ |
125 | int | 127 | int |
126 | GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what, | 128 | GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, |
129 | const char *what, | ||
127 | struct GNUNET_CONTAINER_MetaData **result); | 130 | struct GNUNET_CONTAINER_MetaData **result); |
128 | 131 | ||
129 | 132 | ||
130 | /** | 133 | /** |
131 | * Read a float. | 134 | * Read a float. |
132 | * | 135 | * |
133 | * @param h hande to open file | 136 | * @param h the IO handle to read from |
137 | * @param what describes what is being read (for error message creation) | ||
134 | * @param f address of float to read | 138 | * @param f address of float to read |
135 | */ | 139 | */ |
136 | #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, \ | 140 | int |
137 | f, sizeof(float))) | 141 | GNUNET_BIO_read_float(struct GNUNET_BIO_ReadHandle *h, |
142 | const char *what, | ||
143 | float *f); | ||
138 | 144 | ||
139 | 145 | ||
140 | /** | 146 | /** |
141 | * Read a double. | 147 | * Read a double. |
142 | * | 148 | * |
143 | * @param h hande to open file | 149 | * @param h the IO handle to read from |
150 | * @param what describes what is being read (for error message creation) | ||
144 | * @param f address of double to read | 151 | * @param f address of double to read |
145 | */ | 152 | */ |
146 | #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, \ | 153 | int |
147 | f, sizeof(double))) | 154 | GNUNET_BIO_read_double(struct GNUNET_BIO_ReadHandle *h, |
155 | const char *what, | ||
156 | double *f); | ||
157 | |||
148 | 158 | ||
149 | 159 | ||
150 | /** | 160 | /** |
151 | * Read an (u)int32_t. | 161 | * Read an (u)int32_t. |
152 | * | 162 | * |
153 | * @param h hande to open file | 163 | * @param h the IO handle to read from |
154 | * @param file name of the source file | 164 | * @param what describes what is being read (for error message creation) |
155 | * @param line line number in the code | 165 | * @param i where to store the data |
156 | * @param i address of 32-bit integer to read | ||
157 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 166 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
158 | */ | 167 | */ |
159 | int | 168 | int |
160 | GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file, | 169 | GNUNET_BIO_read_int32 (struct GNUNET_BIO_ReadHandle *h, |
161 | int line, int32_t *i); | 170 | const char *what, |
162 | 171 | int32_t *i); | |
163 | 172 | ||
164 | /** | ||
165 | * Read an (u)int32_t. | ||
166 | * | ||
167 | * @param h hande to open file | ||
168 | * @param i address of 32-bit integer to read | ||
169 | */ | ||
170 | #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, \ | ||
171 | __LINE__, \ | ||
172 | (int32_t *) i) | ||
173 | 173 | ||
174 | 174 | ||
175 | /** | 175 | /** |
176 | * Read an (u)int64_t. | 176 | * Read an (u)int64_t. |
177 | * | 177 | * |
178 | * @param h hande to open file | 178 | * @param h the IO handle to read from |
179 | * @param file name of the source file | 179 | * @param what describes what is being read (for error message creation) |
180 | * @param line line number in the code | 180 | * @param i where to store the data |
181 | * @param i address of 64-bit integer to read | ||
182 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 181 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
183 | */ | 182 | */ |
184 | int | 183 | int |
185 | GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file, | 184 | GNUNET_BIO_read_int64 (struct GNUNET_BIO_ReadHandle *h, |
186 | int line, int64_t *i); | 185 | const char *what, |
186 | int64_t *i); | ||
187 | 187 | ||
188 | 188 | ||
189 | /** | ||
190 | * Read an (u)int64_t. | ||
191 | * | ||
192 | * @param h hande to open file | ||
193 | * @param i address of 64-bit integer to read | ||
194 | */ | ||
195 | #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, \ | ||
196 | __LINE__, \ | ||
197 | (int64_t *) i) | ||
198 | 189 | ||
190 | /****************************** WRITING API *******************************/ | ||
199 | 191 | ||
200 | /** | 192 | /** |
201 | * Handle for buffered writing. | 193 | * Handle for buffered writing. |
@@ -205,108 +197,481 @@ struct GNUNET_BIO_WriteHandle; | |||
205 | /** | 197 | /** |
206 | * Open a file for writing. | 198 | * Open a file for writing. |
207 | * | 199 | * |
208 | * @param fn file name to be opened | 200 | * @param fn name of the file to be opened |
209 | * @return IO handle on success, NULL on error | 201 | * @return IO handle on success, NULL on error |
210 | */ | 202 | */ |
211 | struct GNUNET_BIO_WriteHandle * | 203 | struct GNUNET_BIO_WriteHandle * |
212 | GNUNET_BIO_write_open (const char *fn); | 204 | GNUNET_BIO_write_open_file (const char *fn); |
213 | 205 | ||
214 | 206 | ||
215 | /** | 207 | /** |
216 | * Close an open file for writing. | 208 | * Create a handle backed by an in-memory buffer. |
217 | * | 209 | * |
218 | * @param h file handle | 210 | * @return IO handle on success, NULL on error |
219 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 211 | */ |
212 | struct GNUNET_BIO_WriteHandle * | ||
213 | GNUNET_BIO_write_open_buffer (void); | ||
214 | |||
215 | |||
216 | /** | ||
217 | * Force a file-based buffered writer to flush its buffer. | ||
218 | * If the handle does not use a file, this function returs #GNUNET_OK | ||
219 | * without doing anything. | ||
220 | * | ||
221 | * @param h the IO handle | ||
222 | * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned | ||
223 | * and the file is closed | ||
220 | */ | 224 | */ |
221 | int | 225 | int |
222 | GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h); | 226 | GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h); |
223 | 227 | ||
224 | 228 | ||
225 | /** | 229 | /** |
226 | * Write a buffer to a file. | 230 | * Get the IO handle's contents. |
231 | * If the handle doesn't use an in-memory buffer, this function returns | ||
232 | * #GNUNET_SYSERR. | ||
227 | * | 233 | * |
228 | * @param h handle to open file | 234 | * @param h the IO handle |
229 | * @param buffer the data to write | 235 | * @param emsg set to the (allocated) error message |
230 | * @param n number of bytes to write | 236 | * if the handle has an error message the return value is #GNUNET_SYSERR |
231 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 237 | * @param contents where to store the pointer to the handle's contents |
238 | * @param size where to store the size of @e contents | ||
239 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
232 | */ | 240 | */ |
233 | int | 241 | int |
234 | GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer, | 242 | GNUNET_BIO_get_buffer_contents (struct GNUNET_BIO_WriteHandle *h, |
235 | size_t n); | 243 | char **emsg, |
244 | void **contents, | ||
245 | size_t *size); | ||
246 | |||
247 | |||
248 | /** | ||
249 | * Close an IO handle. | ||
250 | * If the handle was using a file, the file will be closed. | ||
251 | * | ||
252 | * @param h file handle | ||
253 | * @param emsg set to the (allocated) error message | ||
254 | * if the handle has an error message, the return value is #GNUNET_SYSERR | ||
255 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
256 | */ | ||
257 | int | ||
258 | GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h, char **emsg); | ||
236 | 259 | ||
237 | 260 | ||
238 | /** | 261 | /** |
239 | * Force a buffered writer to flush its buffer | 262 | * Write a buffer to a handle. |
240 | * | 263 | * |
241 | * @param h the writer handle | 264 | * @param h the IO handle to write to |
242 | * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned and | 265 | * @param what what is being written (for error message creation) |
243 | * the file is closed | 266 | * @param buffer the data to write |
267 | * @param n number of bytes to write | ||
268 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | ||
244 | */ | 269 | */ |
245 | int | 270 | int |
246 | GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h); | 271 | GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, |
272 | const char *what, | ||
273 | const void *buffer, | ||
274 | size_t n); | ||
247 | 275 | ||
248 | 276 | ||
249 | /** | 277 | /** |
250 | * Write a string to a file. | 278 | * Write a 0-terminated string. |
251 | * | 279 | * |
252 | * @param h handle to open file | 280 | * @param h the IO handle to write to |
281 | * @param what what is being written (for error message creation) | ||
253 | * @param s string to write (can be NULL) | 282 | * @param s string to write (can be NULL) |
254 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 283 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
255 | */ | 284 | */ |
256 | int | 285 | int |
257 | GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s); | 286 | GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, |
287 | const char *what, | ||
288 | const char *s); | ||
258 | 289 | ||
259 | 290 | ||
260 | /** | 291 | /** |
261 | * Write metadata container to a file. | 292 | * Write a metadata container. |
262 | * | 293 | * |
263 | * @param h handle to open file | 294 | * @param h the IO handle to write to |
295 | * @param what what is being written (for error message creation) | ||
264 | * @param m metadata to write | 296 | * @param m metadata to write |
265 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 297 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
266 | */ | 298 | */ |
267 | int | 299 | int |
268 | GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, | 300 | GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, |
301 | const char *what, | ||
269 | const struct GNUNET_CONTAINER_MetaData *m); | 302 | const struct GNUNET_CONTAINER_MetaData *m); |
270 | 303 | ||
271 | 304 | ||
272 | /** | 305 | /** |
273 | * Write a float. | 306 | * Write a float. |
274 | * | 307 | * |
275 | * @param h hande to open file | 308 | * @param h the IO handle to write to |
309 | * @param what what is being written (for error message creation) | ||
276 | * @param f float to write (must be a variable) | 310 | * @param f float to write (must be a variable) |
277 | */ | 311 | */ |
278 | #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float)) | 312 | int |
279 | 313 | GNUNET_BIO_write_float(struct GNUNET_BIO_WriteHandle *h, | |
314 | const char *what, | ||
315 | float f); | ||
280 | 316 | ||
281 | /** | 317 | /** |
282 | * Write a double. | 318 | * Write a double. |
283 | * | 319 | * |
284 | * @param h hande to open file | 320 | * @param h the IO handle to write to |
321 | * @param what what is being written (for error message creation) | ||
285 | * @param f double to write (must be a variable) | 322 | * @param f double to write (must be a variable) |
286 | */ | 323 | */ |
287 | #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double)) | 324 | int |
325 | GNUNET_BIO_write_double(struct GNUNET_BIO_WriteHandle *h, | ||
326 | const char *what, | ||
327 | double f); | ||
288 | 328 | ||
289 | 329 | ||
290 | /** | 330 | /** |
291 | * Write an (u)int32_t. | 331 | * Write an (u)int32_t. |
292 | * | 332 | * |
293 | * @param h hande to open file | 333 | * @param h the IO handle to write to |
334 | * @param what what is being written (for error message creation) | ||
294 | * @param i 32-bit integer to write | 335 | * @param i 32-bit integer to write |
295 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 336 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
296 | */ | 337 | */ |
297 | int | 338 | int |
298 | GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i); | 339 | GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, |
340 | const char *what, | ||
341 | int32_t i); | ||
299 | 342 | ||
300 | 343 | ||
301 | /** | 344 | /** |
302 | * Write an (u)int64_t. | 345 | * Write an (u)int64_t. |
303 | * | 346 | * |
304 | * @param h hande to open file | 347 | * @param h the IO handle to write to |
348 | * @param what what is being written (for error message creation) | ||
305 | * @param i 64-bit integer to write | 349 | * @param i 64-bit integer to write |
306 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | 350 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
307 | */ | 351 | */ |
308 | int | 352 | int |
309 | GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i); | 353 | GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, |
354 | const char *what, | ||
355 | int64_t i); | ||
356 | |||
357 | |||
358 | /****************************** READ SPEC API ***************************/ | ||
359 | |||
360 | |||
361 | /** | ||
362 | * Function used to deserialize data read from @a h and store it into @a | ||
363 | * target. | ||
364 | * | ||
365 | * @param cls closure (can be NULL) | ||
366 | * @param h the IO handle to read from | ||
367 | * @param what what is being read (for error message creation) | ||
368 | * @param target where to store the data | ||
369 | * @param target_size how many bytes can be written in @a target | ||
370 | * can be 0 if the size is unknown or is not fixed | ||
371 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
372 | */ | ||
373 | typedef int | ||
374 | (*GNUNET_BIO_ReadHandler)(void *cls, | ||
375 | struct GNUNET_BIO_ReadHandle *h, | ||
376 | const char *what, | ||
377 | void *target, | ||
378 | size_t target_size); | ||
379 | |||
380 | |||
381 | /** | ||
382 | * Structure specifying a reading operation on an IO handle. | ||
383 | */ | ||
384 | struct GNUNET_BIO_ReadSpec | ||
385 | { | ||
386 | /** | ||
387 | * Function performing data deserialization. | ||
388 | */ | ||
389 | GNUNET_BIO_ReadHandler rh; | ||
390 | |||
391 | /** | ||
392 | * Closure for @e rh. Can be NULL. | ||
393 | */ | ||
394 | void *cls; | ||
395 | |||
396 | /** | ||
397 | * What is being read (for error message creation) | ||
398 | */ | ||
399 | const char *what; | ||
400 | |||
401 | /** | ||
402 | * Destination buffer. Can also be a pointer to a pointer, especially for | ||
403 | * dynamically allocated structures. | ||
404 | */ | ||
405 | void *target; | ||
406 | |||
407 | /** | ||
408 | * Size of @e target. Can be 0 if unknown or not fixed. | ||
409 | */ | ||
410 | size_t size; | ||
411 | }; | ||
412 | |||
413 | |||
414 | /** | ||
415 | * End of specifications marker. | ||
416 | */ | ||
417 | #define GNUNET_BIO_read_spec_end() \ | ||
418 | { NULL, NULL, NULL, NULL, 0 } | ||
419 | |||
420 | |||
421 | /** | ||
422 | * Create the specification to read a certain amount of bytes. | ||
423 | * | ||
424 | * @param what describes what is being read (for error message creation) | ||
425 | * @param result the buffer to write the result to | ||
426 | * @param len the number of bytes to read | ||
427 | * @return the read spec | ||
428 | */ | ||
429 | struct GNUNET_BIO_ReadSpec | ||
430 | GNUNET_BIO_read_spec_object (const char *what, | ||
431 | void *result, | ||
432 | size_t size); | ||
433 | |||
434 | |||
435 | /** | ||
436 | * Create the specification to read a 0-terminated string. | ||
437 | * | ||
438 | * @param what describes what is being read (for error message creation) | ||
439 | * @param result where to store the pointer to the (allocated) string | ||
440 | * (note that *result could be set to NULL as well) | ||
441 | * @param max_length maximum allowed length for the string | ||
442 | * @return the read spec | ||
443 | */ | ||
444 | struct GNUNET_BIO_ReadSpec | ||
445 | GNUNET_BIO_read_spec_string (const char *what, | ||
446 | char **result, | ||
447 | size_t max_length); | ||
448 | |||
449 | |||
450 | /** | ||
451 | * Create the specification to read a metadata container. | ||
452 | * | ||
453 | * @param what describes what is being read (for error message creation) | ||
454 | * @param result the buffer to store a pointer to the (allocated) metadata | ||
455 | * @return the read spec | ||
456 | */ | ||
457 | struct GNUNET_BIO_ReadSpec | ||
458 | GNUNET_BIO_read_spec_meta_data (const char *what, | ||
459 | struct GNUNET_CONTAINER_MetaData **result); | ||
460 | |||
461 | |||
462 | /** | ||
463 | * Create the specification to read an (u)int32_t. | ||
464 | * | ||
465 | * @param what describes what is being read (for error message creation) | ||
466 | * @param i where to store the data | ||
467 | * @return the read spec | ||
468 | */ | ||
469 | struct GNUNET_BIO_ReadSpec | ||
470 | GNUNET_BIO_read_spec_int32 (const char *what, | ||
471 | int32_t *i); | ||
472 | |||
473 | |||
474 | /** | ||
475 | * Create the specification to read an (u)int64_t. | ||
476 | * | ||
477 | * @param what describes what is being read (for error message creation) | ||
478 | * @param i where to store the data | ||
479 | * @return the read spec | ||
480 | */ | ||
481 | struct GNUNET_BIO_ReadSpec | ||
482 | GNUNET_BIO_read_spec_int64 (const char *what, | ||
483 | int64_t *i); | ||
484 | |||
485 | |||
486 | /** | ||
487 | * Create the specification to read a float. | ||
488 | * | ||
489 | * @param what describes what is being read (for error message creation) | ||
490 | * @param f address of float to read | ||
491 | */ | ||
492 | struct GNUNET_BIO_ReadSpec | ||
493 | GNUNET_BIO_read_spec_float(const char *what, float *f); | ||
494 | |||
495 | |||
496 | /** | ||
497 | * Create the specification to read a double. | ||
498 | * | ||
499 | * @param what describes what is being read (for error message creation) | ||
500 | * @param f address of double to read | ||
501 | */ | ||
502 | struct GNUNET_BIO_ReadSpec | ||
503 | GNUNET_BIO_read_spec_double(const char *what, double *f); | ||
504 | |||
505 | |||
506 | /** | ||
507 | * Execute the read specifications in order. | ||
508 | * | ||
509 | * @param h the IO handle to read from | ||
510 | * @param rs array of read specs | ||
511 | * the last element must be #GNUNET_BIO_read_spec_end | ||
512 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
513 | */ | ||
514 | int | ||
515 | GNUNET_BIO_read_spec_commit (struct GNUNET_BIO_ReadHandle *h, | ||
516 | struct GNUNET_BIO_ReadSpec *rs); | ||
517 | |||
518 | |||
519 | /******************************* WRITE SPEC API *****************************/ | ||
520 | |||
521 | |||
522 | /** | ||
523 | * Function used to serialize data from a buffer and write it to @a h. | ||
524 | * | ||
525 | * @param cls closure (can be NULL) | ||
526 | * @param h the IO handle to write to | ||
527 | * @param what what is being written (for error message creation) | ||
528 | * @param source the data to write | ||
529 | * @param source_size how many bytes should be written | ||
530 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
531 | */ | ||
532 | typedef int | ||
533 | (*GNUNET_BIO_WriteHandler) (void *cls, | ||
534 | struct GNUNET_BIO_WriteHandle *h, | ||
535 | const char *what, | ||
536 | void *source, | ||
537 | size_t source_size); | ||
538 | |||
539 | |||
540 | /** | ||
541 | * Structure specifying a writing operation on an IO handle. | ||
542 | */ | ||
543 | struct GNUNET_BIO_WriteSpec | ||
544 | { | ||
545 | /** | ||
546 | * Function performing data serialization. | ||
547 | */ | ||
548 | GNUNET_BIO_WriteHandler wh; | ||
549 | |||
550 | /** | ||
551 | * Closure for @e rh. Can be NULL. | ||
552 | */ | ||
553 | void *cls; | ||
554 | |||
555 | /** | ||
556 | * What is being read (for error message creation) | ||
557 | */ | ||
558 | const char *what; | ||
559 | |||
560 | /** | ||
561 | * Source buffer. The data in this buffer will be written to the handle. | ||
562 | */ | ||
563 | void *source; | ||
564 | |||
565 | /** | ||
566 | * Size of @e source. If it's smaller than the real size of @e source, only | ||
567 | * this many bytes will be written. | ||
568 | */ | ||
569 | size_t source_size; | ||
570 | }; | ||
571 | |||
572 | |||
573 | /** | ||
574 | * End of specifications marker. | ||
575 | */ | ||
576 | #define GNUNET_BIO_write_spec_end() \ | ||
577 | { NULL, NULL, NULL, NULL, 0 } | ||
578 | |||
579 | |||
580 | /** | ||
581 | * Create the specification to read some bytes. | ||
582 | * | ||
583 | * @param what describes what is being written (for error message creation) | ||
584 | * @param source the data to write | ||
585 | * @param size how many bytes should be written | ||
586 | * @return the write spec | ||
587 | */ | ||
588 | struct GNUNET_BIO_WriteSpec | ||
589 | GNUNET_BIO_write_spec_object (const char *what, | ||
590 | void *source, | ||
591 | size_t size); | ||
592 | |||
593 | |||
594 | /** | ||
595 | * Create the specification to write a 0-terminated string. | ||
596 | * | ||
597 | * @param what describes what is being read (for error message creation) | ||
598 | * @param s string to write (can be NULL) | ||
599 | * @return the read spec | ||
600 | */ | ||
601 | struct GNUNET_BIO_WriteSpec | ||
602 | GNUNET_BIO_write_spec_string (const char *what, | ||
603 | const char *s); | ||
604 | |||
605 | |||
606 | /** | ||
607 | * Create the specification to write a metadata container. | ||
608 | * | ||
609 | * @param what what is being written (for error message creation) | ||
610 | * @param m metadata to write | ||
611 | * @return the write spec | ||
612 | */ | ||
613 | struct GNUNET_BIO_WriteSpec | ||
614 | GNUNET_BIO_write_spec_meta_data (const char *what, | ||
615 | const struct GNUNET_CONTAINER_MetaData *m); | ||
616 | |||
617 | |||
618 | /** | ||
619 | * Create the specification to write an (u)int32_t. | ||
620 | * | ||
621 | * @param what describes what is being written (for error message creation) | ||
622 | * @param i pointer to a 32-bit integer | ||
623 | * @return the write spec | ||
624 | */ | ||
625 | struct GNUNET_BIO_WriteSpec | ||
626 | GNUNET_BIO_write_spec_int32 (const char *what, | ||
627 | int32_t *i); | ||
628 | |||
629 | |||
630 | /** | ||
631 | * Create the specification to write an (u)int64_t. | ||
632 | * | ||
633 | * @param what describes what is being written (for error message creation) | ||
634 | * @param i pointer to a 64-bit integer | ||
635 | * @return the write spec | ||
636 | */ | ||
637 | struct GNUNET_BIO_WriteSpec | ||
638 | GNUNET_BIO_write_spec_int64 (const char *what, | ||
639 | int64_t *i); | ||
640 | |||
641 | |||
642 | /** | ||
643 | * Create the specification to write a float. | ||
644 | * | ||
645 | * @param what describes what is being written (for error message creation) | ||
646 | * @param f pointer to a float | ||
647 | * @return the write spec | ||
648 | */ | ||
649 | struct GNUNET_BIO_WriteSpec | ||
650 | GNUNET_BIO_write_spec_float(const char *what, float *f); | ||
651 | |||
652 | |||
653 | /** | ||
654 | * Create the specification to write an double. | ||
655 | * | ||
656 | * @param what describes what is being written (for error message creation) | ||
657 | * @param f pointer to a double | ||
658 | * @return the write spec | ||
659 | */ | ||
660 | struct GNUNET_BIO_WriteSpec | ||
661 | GNUNET_BIO_write_spec_double(const char *what, double *f); | ||
662 | |||
663 | |||
664 | /** | ||
665 | * Execute the write specifications in order. | ||
666 | * | ||
667 | * @param h the IO handle to write to | ||
668 | * @param ws array of write specs | ||
669 | * the last element must be #GNUNET_BIO_write_spec_end | ||
670 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise | ||
671 | */ | ||
672 | int | ||
673 | GNUNET_BIO_write_spec_commit (struct GNUNET_BIO_WriteHandle *h, | ||
674 | struct GNUNET_BIO_WriteSpec *ws); | ||
310 | 675 | ||
311 | 676 | ||
312 | #if 0 /* keep Emacsens' auto-indent happy */ | 677 | #if 0 /* keep Emacsens' auto-indent happy */ |
diff --git a/src/include/gnunet_buffer_lib.h b/src/include/gnunet_buffer_lib.h index c0ae06d77..e23536ab2 100644 --- a/src/include/gnunet_buffer_lib.h +++ b/src/include/gnunet_buffer_lib.h | |||
@@ -165,6 +165,19 @@ GNUNET_buffer_reap_str (struct GNUNET_Buffer *buf); | |||
165 | 165 | ||
166 | 166 | ||
167 | /** | 167 | /** |
168 | * Clear the buffer and return its contents. | ||
169 | * The caller is responsible to eventually #GNUNET_free | ||
170 | * the returned data. | ||
171 | * | ||
172 | * @param buf the buffer to reap the contents from | ||
173 | * @param size where to store the size of the returned data | ||
174 | * @returns the data contained in the string | ||
175 | */ | ||
176 | void * | ||
177 | GNUNET_buffer_reap (struct GNUNET_Buffer *buf, size_t *size); | ||
178 | |||
179 | |||
180 | /** | ||
168 | * Free the backing memory of the given buffer. | 181 | * Free the backing memory of the given buffer. |
169 | * Does not free the memory of the buffer control structure, | 182 | * Does not free the memory of the buffer control structure, |
170 | * which is typically stack-allocated. | 183 | * which is typically stack-allocated. |