src/include/gnunet_bio_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  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 /**
  46  * @ingroup bio
  47  * Handle for buffered reading.
  48  */
  49 struct GNUNET_BIO_ReadHandle;
  50
  51
  52 /**
  53  * Open a file for reading.
  54  *
  55  * @param fn file name to be opened
  56  * @return IO handle on success, NULL on error
  57  */
  58 struct GNUNET_BIO_ReadHandle *
  59 GNUNET_BIO_read_open (const char *fn);
  60
  61
  62 /**
  63  * Close an open file.  Reports if any errors reading
  64  * from the file were encountered.
  65  *
  66  * @param h file handle
  67  * @param emsg set to the error message
  68  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  69  */
  70 int
  71 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
  72
  73
  74 /**
  75  * Read the contents of a binary file into a buffer.
  76  *
  77  * @param h handle to an open file
  78  * @param what describes what is being read (for error message creation)
  79  * @param result the buffer to write the result to
  80  * @param len the number of bytes to read
  81  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  82  */
  83 int
  84 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
  85                  void *result, size_t len);
  86
  87
  88 /**
  89  * Read the contents of a binary file into a buffer.
  90  *
  91  * @param h handle to an open file
  92  * @param file name of the source file
  93  * @param line line number in the source file
  94  * @param result the buffer to write the result to
  95  * @param len the number of bytes to read
  96  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  97  */
  98 int
  99 GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h,
 100                     const char *file, int line,
 101                     void *result, size_t len);
 102
 103 /**
 104  * Read 0-terminated string from a file.
 105  *
 106  * @param h handle to an open file
 107  * @param what describes what is being read (for error message creation)
 108  * @param result the buffer to store a pointer to the (allocated) string to
 109  *        (note that *result could be set to NULL as well)
 110  * @param max_length maximum allowed length for the string
 111  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 112  */
 113 int
 114 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
 115                         char **result, size_t max_length);
 116
 117
 118 /**
 119  * Read metadata container from a file.
 120  *
 121  * @param h handle to an open file
 122  * @param what describes what is being read (for error message creation)
 123  * @param result the buffer to store a pointer to the (allocated) metadata
 124  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 125  */
 126 int
 127 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
 128                            struct GNUNET_CONTAINER_MetaData **result);
 129
 130
 131 /**
 132  * Read a float.
 133  *
 134  * @param h hande to open file
 135  * @param f address of float to read
 136  */
 137 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float)))
 138
 139
 140
 141 /**
 142  * Read a double.
 143  *
 144  * @param h hande to open file
 145  * @param f address of double to read
 146  */
 147 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double)))
 148
 149
 150 /**
 151  * Read an (u)int32_t.
 152  *
 153  * @param h hande to open file
 154  * @param file name of the source file
 155  * @param line line number in the code
 156  * @param i address of 32-bit integer to read
 157  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 158  */
 159 int
 160 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 161                          int line, int32_t * i);
 162
 163
 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__, __LINE__, (int32_t*) i)
 171
 172
 173 /**
 174  * Read an (u)int64_t.
 175  *
 176  * @param h hande to open file
 177  * @param file name of the source file
 178  * @param line line number in the code
 179  * @param i address of 64-bit integer to read
 180  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 181  */
 182 int
 183 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 184                          int line, int64_t * i);
 185
 186
 187 /**
 188  * Read an (u)int64_t.
 189  *
 190  * @param h hande to open file
 191  * @param i address of 64-bit integer to read
 192  */
 193 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i)
 194
 195
 196 /**
 197  * Handle for buffered writing.
 198  */
 199 struct GNUNET_BIO_WriteHandle;
 200
 201 /**
 202  * Open a file for writing.
 203  *
 204  * @param fn file name to be opened
 205  * @return IO handle on success, NULL on error
 206  */
 207 struct GNUNET_BIO_WriteHandle *
 208 GNUNET_BIO_write_open (const char *fn);
 209
 210
 211 /**
 212  * Close an open file for writing.
 213  *
 214  * @param h file handle
 215  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
 216  */
 217 int
 218 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
 219
 220
 221 /**
 222  * Write a buffer to a file.
 223  *
 224  * @param h handle to open file
 225  * @param buffer the data to write
 226  * @param n number of bytes to write
 227  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 228  */
 229 int
 230 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
 231                   size_t n);
 232
 233
 234 /**
 235  * Force a buffered writer to flush its buffer
 236  *
 237  * @param h the writer handle
 238  * @return #GNUNET_OK upon success.  Upon failure #GNUNET_SYSERR is returned and
 239  *           the file is closed
 240  */
 241 int
 242 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
 243
 244
 245 /**
 246  * Write a string to a file.
 247  *
 248  * @param h handle to open file
 249  * @param s string to write (can be NULL)
 250  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 251  */
 252 int
 253 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
 254
 255
 256 /**
 257  * Write metadata container to a file.
 258  *
 259  * @param h handle to open file
 260  * @param m metadata to write
 261  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 262  */
 263 int
 264 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
 265                             const struct GNUNET_CONTAINER_MetaData *m);
 266
 267
 268
 269 /**
 270  * Write a float.
 271  *
 272  * @param h hande to open file
 273  * @param f float to write (must be a variable)
 274  */
 275 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
 276
 277
 278
 279 /**
 280  * Write a double.
 281  *
 282  * @param h hande to open file
 283  * @param f double to write (must be a variable)
 284  */
 285 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
 286
 287
 288 /**
 289  * Write an (u)int32_t.
 290  *
 291  * @param h hande to open file
 292  * @param i 32-bit integer to write
 293  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 294  */
 295 int
 296 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
 297
 298
 299 /**
 300  * Write an (u)int64_t.
 301  *
 302  * @param h hande to open file
 303  * @param i 64-bit integer to write
 304  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 305  */
 306 int
 307 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
 308
 309
 310 #if 0                           /* keep Emacsens' auto-indent happy */
 311 {
 312 #endif
 313 #ifdef __cplusplus
 314 }
 315 #endif
 316
 317 /** @} */ /* end of group bio */
 318
 319 /* ifndef GNUNET_BIO_LIB_H */
 320 #endif
 321 /* end of gnunet_bio_lib.h */