gnunet_bio_lib.h (17618B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2009 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup libgnunetutil 23 * Multi-function utilities library for GNUnet programs 24 * @{ 25 * 26 * @author Christian Grothoff 27 * 28 * @file 29 * Buffered IO library 30 * 31 * @defgroup bio BIO library 32 * Buffered binary disk IO (with endianness conversion) 33 * @{ 34 */ 35 36 #include "gnunet_common.h" 37 #if !defined (__GNUNET_UTIL_LIB_H_INSIDE__) 38 #error "Only <gnunet_util_lib.h> can be included directly." 39 #endif 40 41 #ifndef GNUNET_BIO_LIB_H 42 #define GNUNET_BIO_LIB_H 43 44 45 #include "gnunet_container_lib.h" 46 47 #ifdef __cplusplus 48 extern "C" 49 { 50 #if 0 /* keep Emacsens' auto-indent happy */ 51 } 52 #endif 53 #endif 54 55 /****************************** READING API *******************************/ 56 57 /** 58 * Handle for buffered reading. 59 */ 60 struct GNUNET_BIO_ReadHandle; 61 62 63 /** 64 * Open a file for reading. 65 * 66 * @param fn file name to be opened 67 * @return IO handle on success, NULL on error 68 */ 69 struct GNUNET_BIO_ReadHandle * 70 GNUNET_BIO_read_open_file (const char *fn); 71 72 73 /** 74 * Create a handle from an existing allocated buffer. 75 * 76 * @param buffer the buffer to use as source 77 * @param size the total size in bytes of the buffer 78 * @return IO handle on success, NULL on error 79 */ 80 struct GNUNET_BIO_ReadHandle * 81 GNUNET_BIO_read_open_buffer (void *buffer, size_t size); 82 83 84 /** 85 * Close an open handle. Reports if any errors reading 86 * from the file were encountered. 87 * 88 * @param h file handle 89 * @param emsg set to the error message 90 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 91 */ 92 enum GNUNET_GenericReturnValue 93 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg); 94 95 /** 96 * Set read error to handle 97 * 98 * @param h the handle 99 * @param emsg the message 100 */ 101 void 102 GNUNET_BIO_read_set_error (struct GNUNET_BIO_ReadHandle *h, const char* emsg); 103 104 105 /** 106 * Read some contents into a buffer. 107 * 108 * @param h the IO handle to read from 109 * @param what describes what is being read (for error message creation) 110 * @param result the buffer to write the result to 111 * @param len the number of bytes to read 112 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 113 */ 114 enum GNUNET_GenericReturnValue 115 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, 116 const char *what, 117 void *result, 118 size_t len); 119 120 121 /** 122 * Read 0-terminated string. 123 * 124 * @param h the IO handle to read from 125 * @param what describes what is being read (for error message creation) 126 * @param result where to store the pointer to the (allocated) string 127 * (note that *result could be set to NULL as well) 128 * @param max_length maximum allowed length for the string 129 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 130 */ 131 enum GNUNET_GenericReturnValue 132 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, 133 const char *what, 134 char **result, 135 size_t max_length); 136 137 138 139 /** 140 * Read a float. 141 * 142 * @param h the IO handle to read from 143 * @param what describes what is being read (for error message creation) 144 * @param f address of float to read 145 */ 146 enum GNUNET_GenericReturnValue 147 GNUNET_BIO_read_float (struct GNUNET_BIO_ReadHandle *h, 148 const char *what, 149 float *f); 150 151 152 /** 153 * Read a double. 154 * 155 * @param h the IO handle to read from 156 * @param what describes what is being read (for error message creation) 157 * @param f address of double to read 158 */ 159 enum GNUNET_GenericReturnValue 160 GNUNET_BIO_read_double (struct GNUNET_BIO_ReadHandle *h, 161 const char *what, 162 double *f); 163 164 165 /** 166 * Read an (u)int32_t. 167 * 168 * @param h the IO handle to read from 169 * @param what describes what is being read (for error message creation) 170 * @param i where to store the data 171 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 172 */ 173 enum GNUNET_GenericReturnValue 174 GNUNET_BIO_read_int32 (struct GNUNET_BIO_ReadHandle *h, 175 const char *what, 176 int32_t *i); 177 178 179 /** 180 * Read an (u)int64_t. 181 * 182 * @param h the IO handle to read from 183 * @param what describes what is being read (for error message creation) 184 * @param i where to store the data 185 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 186 */ 187 enum GNUNET_GenericReturnValue 188 GNUNET_BIO_read_int64 (struct GNUNET_BIO_ReadHandle *h, 189 const char *what, 190 int64_t *i); 191 192 193 /****************************** WRITING API *******************************/ 194 195 /** 196 * Handle for buffered writing. 197 */ 198 struct GNUNET_BIO_WriteHandle; 199 200 /** 201 * Open a file for writing. 202 * 203 * @param fn name of the file to be opened 204 * @return IO handle on success, NULL on error 205 */ 206 struct GNUNET_BIO_WriteHandle * 207 GNUNET_BIO_write_open_file (const char *fn); 208 209 210 /** 211 * Create a handle backed by an in-memory buffer. 212 * 213 * @return IO handle on success, NULL on error 214 */ 215 struct GNUNET_BIO_WriteHandle * 216 GNUNET_BIO_write_open_buffer (void); 217 218 219 /** 220 * Force a file-based buffered writer to flush its buffer. 221 * If the handle does not use a file, this function returns #GNUNET_OK 222 * without doing anything. 223 * 224 * @param h the IO handle 225 * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned 226 * and the file is closed 227 */ 228 enum GNUNET_GenericReturnValue 229 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h); 230 231 232 /** 233 * Get the IO handle's contents. 234 * If the handle doesn't use an in-memory buffer, this function returns 235 * #GNUNET_SYSERR. 236 * 237 * @param h the IO handle 238 * @param emsg set to the (allocated) error message 239 * if the handle has an error message the return value is #GNUNET_SYSERR 240 * @param contents where to store the pointer to the handle's contents 241 * @param size where to store the size of @e contents 242 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 243 */ 244 enum GNUNET_GenericReturnValue 245 GNUNET_BIO_get_buffer_contents (struct GNUNET_BIO_WriteHandle *h, 246 char **emsg, 247 void **contents, 248 size_t *size); 249 250 251 /** 252 * Close an IO handle. 253 * If the handle was using a file, the file will be closed. 254 * 255 * @param h file handle 256 * @param emsg set to the (allocated) error message 257 * if the handle has an error message, the return value is #GNUNET_SYSERR 258 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 259 */ 260 enum GNUNET_GenericReturnValue 261 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h, char **emsg); 262 263 264 /** 265 * Write a buffer to a handle. 266 * 267 * @param h the IO handle to write to 268 * @param what what is being written (for error message creation) 269 * @param buffer the data to write 270 * @param n number of bytes to write 271 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 272 */ 273 enum GNUNET_GenericReturnValue 274 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, 275 const char *what, 276 const void *buffer, 277 size_t n); 278 279 280 /** 281 * Write a 0-terminated string. 282 * 283 * @param h the IO handle to write to 284 * @param what what is being written (for error message creation) 285 * @param s string to write (can be NULL) 286 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 287 */ 288 enum GNUNET_GenericReturnValue 289 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, 290 const char *what, 291 const char *s); 292 293 294 295 /** 296 * Write a float. 297 * 298 * @param h the IO handle to write to 299 * @param what what is being written (for error message creation) 300 * @param f float to write (must be a variable) 301 */ 302 enum GNUNET_GenericReturnValue 303 GNUNET_BIO_write_float (struct GNUNET_BIO_WriteHandle *h, 304 const char *what, 305 float f); 306 307 /** 308 * Write a double. 309 * 310 * @param h the IO handle to write to 311 * @param what what is being written (for error message creation) 312 * @param f double to write (must be a variable) 313 */ 314 enum GNUNET_GenericReturnValue 315 GNUNET_BIO_write_double (struct GNUNET_BIO_WriteHandle *h, 316 const char *what, 317 double f); 318 319 320 /** 321 * Write an (u)int32_t. 322 * 323 * @param h the IO handle to write to 324 * @param what what is being written (for error message creation) 325 * @param i 32-bit integer to write 326 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 327 */ 328 enum GNUNET_GenericReturnValue 329 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, 330 const char *what, 331 int32_t i); 332 333 334 /** 335 * Write an (u)int64_t. 336 * 337 * @param h the IO handle to write to 338 * @param what what is being written (for error message creation) 339 * @param i 64-bit integer to write 340 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 341 */ 342 enum GNUNET_GenericReturnValue 343 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, 344 const char *what, 345 int64_t i); 346 347 348 /****************************** READ SPEC API ***************************/ 349 350 351 /** 352 * Function used to deserialize data read from @a h and store it into @a 353 * target. 354 * 355 * @param cls closure (can be NULL) 356 * @param h the IO handle to read from 357 * @param what what is being read (for error message creation) 358 * @param target where to store the data 359 * @param target_size how many bytes can be written in @a target 360 * can be 0 if the size is unknown or is not fixed 361 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 362 */ 363 typedef int 364 (*GNUNET_BIO_ReadHandler)(void *cls, 365 struct GNUNET_BIO_ReadHandle *h, 366 const char *what, 367 void *target, 368 size_t target_size); 369 370 371 /** 372 * Structure specifying a reading operation on an IO handle. 373 */ 374 struct GNUNET_BIO_ReadSpec 375 { 376 /** 377 * Function performing data deserialization. 378 */ 379 GNUNET_BIO_ReadHandler rh; 380 381 /** 382 * Closure for @e rh. Can be NULL. 383 */ 384 void *cls; 385 386 /** 387 * What is being read (for error message creation) 388 */ 389 const char *what; 390 391 /** 392 * Destination buffer. Can also be a pointer to a pointer, especially for 393 * dynamically allocated structures. 394 */ 395 void *target; 396 397 /** 398 * Size of @e target. Can be 0 if unknown or not fixed. 399 */ 400 size_t size; 401 }; 402 403 404 /** 405 * End of specifications marker. 406 */ 407 #define GNUNET_BIO_read_spec_end() \ 408 { NULL, NULL, NULL, NULL, 0 } 409 410 411 /** 412 * Create the specification to read a certain amount of bytes. 413 * 414 * @param what describes what is being read (for error message creation) 415 * @param result the buffer to write the result to 416 * @param len the number of bytes to read 417 * @return the read spec 418 */ 419 struct GNUNET_BIO_ReadSpec 420 GNUNET_BIO_read_spec_object (const char *what, 421 void *result, 422 size_t size); 423 424 425 /** 426 * Create the specification to read a 0-terminated string. 427 * 428 * @param what describes what is being read (for error message creation) 429 * @param result where to store the pointer to the (allocated) string 430 * (note that *result could be set to NULL as well) 431 * @param max_length maximum allowed length for the string 432 * @return the read spec 433 */ 434 struct GNUNET_BIO_ReadSpec 435 GNUNET_BIO_read_spec_string (const char *what, 436 char **result, 437 size_t max_length); 438 439 440 441 /** 442 * Create the specification to read an (u)int32_t. 443 * 444 * @param what describes what is being read (for error message creation) 445 * @param i where to store the data 446 * @return the read spec 447 */ 448 struct GNUNET_BIO_ReadSpec 449 GNUNET_BIO_read_spec_int32 (const char *what, 450 int32_t *i); 451 452 453 /** 454 * Create the specification to read an (u)int64_t. 455 * 456 * @param what describes what is being read (for error message creation) 457 * @param i where to store the data 458 * @return the read spec 459 */ 460 struct GNUNET_BIO_ReadSpec 461 GNUNET_BIO_read_spec_int64 (const char *what, 462 int64_t *i); 463 464 465 /** 466 * Create the specification to read a float. 467 * 468 * @param what describes what is being read (for error message creation) 469 * @param f address of float to read 470 */ 471 struct GNUNET_BIO_ReadSpec 472 GNUNET_BIO_read_spec_float (const char *what, float *f); 473 474 475 /** 476 * Create the specification to read a double. 477 * 478 * @param what describes what is being read (for error message creation) 479 * @param f address of double to read 480 */ 481 struct GNUNET_BIO_ReadSpec 482 GNUNET_BIO_read_spec_double (const char *what, double *f); 483 484 485 /** 486 * Execute the read specifications in order. 487 * 488 * @param h the IO handle to read from 489 * @param rs array of read specs 490 * the last element must be #GNUNET_BIO_read_spec_end 491 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 492 */ 493 enum GNUNET_GenericReturnValue 494 GNUNET_BIO_read_spec_commit (struct GNUNET_BIO_ReadHandle *h, 495 struct GNUNET_BIO_ReadSpec *rs); 496 497 498 /******************************* WRITE SPEC API *****************************/ 499 500 501 /** 502 * Function used to serialize data from a buffer and write it to @a h. 503 * 504 * @param cls closure (can be NULL) 505 * @param h the IO handle to write to 506 * @param what what is being written (for error message creation) 507 * @param source the data to write 508 * @param source_size how many bytes should be written 509 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 510 */ 511 typedef int 512 (*GNUNET_BIO_WriteHandler) (void *cls, 513 struct GNUNET_BIO_WriteHandle *h, 514 const char *what, 515 void *source, 516 size_t source_size); 517 518 519 /** 520 * Structure specifying a writing operation on an IO handle. 521 */ 522 struct GNUNET_BIO_WriteSpec 523 { 524 /** 525 * Function performing data serialization. 526 */ 527 GNUNET_BIO_WriteHandler wh; 528 529 /** 530 * Closure for @e rh. Can be NULL. 531 */ 532 void *cls; 533 534 /** 535 * What is being read (for error message creation) 536 */ 537 const char *what; 538 539 /** 540 * Source buffer. The data in this buffer will be written to the handle. 541 */ 542 void *source; 543 544 /** 545 * Size of @e source. If it's smaller than the real size of @e source, only 546 * this many bytes will be written. 547 */ 548 size_t source_size; 549 }; 550 551 552 /** 553 * End of specifications marker. 554 */ 555 #define GNUNET_BIO_write_spec_end() \ 556 { NULL, NULL, NULL, NULL, 0 } 557 558 559 /** 560 * Create the specification to read some bytes. 561 * 562 * @param what describes what is being written (for error message creation) 563 * @param source the data to write 564 * @param size how many bytes should be written 565 * @return the write spec 566 */ 567 struct GNUNET_BIO_WriteSpec 568 GNUNET_BIO_write_spec_object (const char *what, 569 void *source, 570 size_t size); 571 572 573 /** 574 * Create the specification to write a 0-terminated string. 575 * 576 * @param what describes what is being read (for error message creation) 577 * @param s string to write (can be NULL) 578 * @return the read spec 579 */ 580 struct GNUNET_BIO_WriteSpec 581 GNUNET_BIO_write_spec_string (const char *what, 582 const char *s); 583 584 585 /** 586 * Create the specification to write an (u)int32_t. 587 * 588 * @param what describes what is being written (for error message creation) 589 * @param i pointer to a 32-bit integer 590 * @return the write spec 591 */ 592 struct GNUNET_BIO_WriteSpec 593 GNUNET_BIO_write_spec_int32 (const char *what, 594 int32_t *i); 595 596 597 /** 598 * Create the specification to write an (u)int64_t. 599 * 600 * @param what describes what is being written (for error message creation) 601 * @param i pointer to a 64-bit integer 602 * @return the write spec 603 */ 604 struct GNUNET_BIO_WriteSpec 605 GNUNET_BIO_write_spec_int64 (const char *what, 606 int64_t *i); 607 608 609 /** 610 * Create the specification to write a float. 611 * 612 * @param what describes what is being written (for error message creation) 613 * @param f pointer to a float 614 * @return the write spec 615 */ 616 struct GNUNET_BIO_WriteSpec 617 GNUNET_BIO_write_spec_float (const char *what, float *f); 618 619 620 /** 621 * Create the specification to write an double. 622 * 623 * @param what describes what is being written (for error message creation) 624 * @param f pointer to a double 625 * @return the write spec 626 */ 627 struct GNUNET_BIO_WriteSpec 628 GNUNET_BIO_write_spec_double (const char *what, double *f); 629 630 631 /** 632 * Execute the write specifications in order. 633 * 634 * @param h the IO handle to write to 635 * @param ws array of write specs 636 * the last element must be #GNUNET_BIO_write_spec_end 637 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 638 */ 639 enum GNUNET_GenericReturnValue 640 GNUNET_BIO_write_spec_commit (struct GNUNET_BIO_WriteHandle *h, 641 struct GNUNET_BIO_WriteSpec *ws); 642 643 644 #if 0 /* keep Emacsens' auto-indent happy */ 645 { 646 #endif 647 #ifdef __cplusplus 648 } 649 #endif 650 651 /* ifndef GNUNET_BIO_LIB_H */ 652 #endif 653 654 /** @} */ /* end of group bio */ 655 656 /** @} */ /* end of group addition */ 657 658 /* end of gnunet_bio_lib.h */