src/include/gnunet_bio_lib.h

   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  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Buffered IO library
  26  *
  27  * @defgroup bio  BIO library
  28  * Buffered binary disk IO (with endianess conversion)
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_BIO_LIB_H
  33 #define GNUNET_BIO_LIB_H
  34
  35 #include "gnunet_container_lib.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 /****************************** READING API *******************************/
  46
  47 /**
  48  * Handle for buffered reading.
  49  */
  50 struct GNUNET_BIO_ReadHandle;
  51
  52
  53 /**
  54  * Open a file for reading.
  55  *
  56  * @param fn file name to be opened
  57  * @return IO handle on success, NULL on error
  58  */
  59 struct GNUNET_BIO_ReadHandle *
  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);
  72
  73
  74 /**
  75  * Close an open handle.  Reports if any errors reading
  76  * from the file were encountered.
  77  *
  78  * @param h file handle
  79  * @param emsg set to the error message
  80  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  81  */
  82 int
  83 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
  84
  85
  86 /**
  87  * Read some contents into a buffer.
  88  *
  89  * @param h the IO handle to read from
  90  * @param what describes what is being read (for error message creation)
  91  * @param result the buffer to write the result to
  92  * @param len the number of bytes to read
  93  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  94  */
  95 int
  96 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h,
  97                  const char *what,
  98                  void *result,
  99                  size_t len);
 100
 101
 102 /**
 103  * Read 0-terminated string.
 104  *
 105  * @param h the IO handle to read from
 106  * @param what describes what is being read (for error message creation)
 107  * @param result where to store the pointer to the (allocated) string
 108  *        (note that *result could be set to NULL as well)
 109  * @param max_length maximum allowed length for the string
 110  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 111  */
 112 int
 113 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h,
 114                         const char *what,
 115                         char **result,
 116                         size_t max_length);
 117
 118
 119 /**
 120  * Read a metadata container.
 121  *
 122  * @param h handle to an open file
 123  * @param what describes what is being read (for error message creation)
 124  * @param result the buffer to store a pointer to the (allocated) metadata
 125  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 126  */
 127 int
 128 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h,
 129                            const char *what,
 130                            struct GNUNET_CONTAINER_MetaData **result);
 131
 132
 133 /**
 134  * Read a float.
 135  *
 136  * @param h the IO handle to read from
 137  * @param what describes what is being read (for error message creation)
 138  * @param f address of float to read
 139  */
 140 int
 141 GNUNET_BIO_read_float(struct GNUNET_BIO_ReadHandle *h,
 142                       const char *what,
 143                       float *f);
 144
 145
 146 /**
 147  * Read a double.
 148  *
 149  * @param h the IO handle to read from
 150  * @param what describes what is being read (for error message creation)
 151  * @param f address of double to read
 152  */
 153 int
 154 GNUNET_BIO_read_double(struct GNUNET_BIO_ReadHandle *h,
 155                        const char *what,
 156                        double *f);
 157
 158
 159
 160 /**
 161  * Read an (u)int32_t.
 162  *
 163  * @param h the IO handle to read from
 164  * @param what describes what is being read (for error message creation)
 165  * @param i where to store the data
 166  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 167  */
 168 int
 169 GNUNET_BIO_read_int32 (struct GNUNET_BIO_ReadHandle *h,
 170                        const char *what,
 171                        int32_t *i);
 172
 173
 174
 175 /**
 176  * Read an (u)int64_t.
 177  *
 178  * @param h the IO handle to read from
 179  * @param what describes what is being read (for error message creation)
 180  * @param i where to store the data
 181  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 182  */
 183 int
 184 GNUNET_BIO_read_int64 (struct GNUNET_BIO_ReadHandle *h,
 185                        const char *what,
 186                        int64_t *i);
 187
 188
 189
 190 /****************************** WRITING API *******************************/
 191
 192 /**
 193  * Handle for buffered writing.
 194  */
 195 struct GNUNET_BIO_WriteHandle;
 196
 197 /**
 198  * Open a file for writing.
 199  *
 200  * @param fn name of the file to be opened
 201  * @return IO handle on success, NULL on error
 202  */
 203 struct GNUNET_BIO_WriteHandle *
 204 GNUNET_BIO_write_open_file (const char *fn);
 205
 206
 207 /**
 208  * Create a handle backed by an in-memory buffer.
 209  *
 210  * @return IO handle on success, NULL on error
 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
 224  */
 225 int
 226 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
 227
 228
 229 /**
 230  * Get the IO handle's contents.
 231  * If the handle doesn't use an in-memory buffer, this function returns
 232  * #GNUNET_SYSERR.
 233  *
 234  * @param h the IO handle
 235  * @param emsg set to the (allocated) error message
 236  *        if the handle has an error message the return value is #GNUNET_SYSERR
 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
 240  */
 241 int
 242 GNUNET_BIO_get_buffer_contents (struct GNUNET_BIO_WriteHandle *h,
 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);
 259
 260
 261 /**
 262  * Write a buffer to a handle.
 263  *
 264  * @param h the IO handle to write to
 265  * @param what what is being written (for error message creation)
 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
 269  */
 270 int
 271 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h,
 272                   const char *what,
 273                   const void *buffer,
 274                   size_t n);
 275
 276
 277 /**
 278  * Write a 0-terminated string.
 279  *
 280  * @param h the IO handle to write to
 281  * @param what what is being written (for error message creation)
 282  * @param s string to write (can be NULL)
 283  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 284  */
 285 int
 286 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h,
 287                          const char *what,
 288                          const char *s);
 289
 290
 291 /**
 292  * Write a metadata container.
 293  *
 294  * @param h the IO handle to write to
 295  * @param what what is being written (for error message creation)
 296  * @param m metadata to write
 297  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 298  */
 299 int
 300 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
 301                             const char *what,
 302                             const struct GNUNET_CONTAINER_MetaData *m);
 303
 304
 305 /**
 306  * Write a float.
 307  *
 308  * @param h the IO handle to write to
 309  * @param what what is being written (for error message creation)
 310  * @param f float to write (must be a variable)
 311  */
 312 int
 313 GNUNET_BIO_write_float(struct GNUNET_BIO_WriteHandle *h,
 314                        const char *what,
 315                        float f);
 316
 317 /**
 318  * Write a double.
 319  *
 320  * @param h the IO handle to write to
 321  * @param what what is being written (for error message creation)
 322  * @param f double to write (must be a variable)
 323  */
 324 int
 325 GNUNET_BIO_write_double(struct GNUNET_BIO_WriteHandle *h,
 326                         const char *what,
 327                         double f);
 328
 329
 330 /**
 331  * Write an (u)int32_t.
 332  *
 333  * @param h the IO handle to write to
 334  * @param what what is being written (for error message creation)
 335  * @param i 32-bit integer to write
 336  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 337  */
 338 int
 339 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h,
 340                         const char *what,
 341                         int32_t i);
 342
 343
 344 /**
 345  * Write an (u)int64_t.
 346  *
 347  * @param h the IO handle to write to
 348  * @param what what is being written (for error message creation)
 349  * @param i 64-bit integer to write
 350  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 351  */
 352 int
 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);
 675
 676
 677 #if 0                           /* keep Emacsens' auto-indent happy */
 678 {
 679 #endif
 680 #ifdef __cplusplus
 681 }
 682 #endif
 683
 684 /* ifndef GNUNET_BIO_LIB_H */
 685 #endif
 686
 687 /** @} */  /* end of group bio */
 688
 689 /* end of gnunet_bio_lib.h */