src/include/gnunet_bio_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_bio_lib.h
  23  * @brief buffered IO API
  24  * @author Christian Grothoff
  25  * @defgroup bio Buffered binary disk IO (with endianess conversion)
  26  * @{
  27  */
  28
  29 #ifndef GNUNET_BIO_LIB_H
  30 #define GNUNET_BIO_LIB_H
  31
  32 #include "gnunet_container_lib.h"
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #if 0                           /* keep Emacsens' auto-indent happy */
  38 }
  39 #endif
  40 #endif
  41
  42 /**
  43  * @ingroup bio
  44  * Handle for buffered reading.
  45  */
  46 struct GNUNET_BIO_ReadHandle;
  47
  48
  49 /**
  50  * Open a file for reading.
  51  *
  52  * @param fn file name to be opened
  53  * @return IO handle on success, NULL on error
  54  */
  55 struct GNUNET_BIO_ReadHandle *
  56 GNUNET_BIO_read_open (const char *fn);
  57
  58
  59 /**
  60  * Close an open file.  Reports if any errors reading
  61  * from the file were encountered.
  62  *
  63  * @param h file handle
  64  * @param emsg set to the error message
  65  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  66  */
  67 int
  68 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
  69
  70
  71 /**
  72  * Read the contents of a binary file into a buffer.
  73  *
  74  * @param h handle to an open file
  75  * @param what describes what is being read (for error message creation)
  76  * @param result the buffer to write the result to
  77  * @param len the number of bytes to read
  78  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  79  */
  80 int
  81 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
  82                  void *result, size_t len);
  83
  84
  85 /**
  86  * Read the contents of a binary file into a buffer.
  87  *
  88  * @param h handle to an open file
  89  * @param file name of the source file
  90  * @param line line number in the source file
  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_fn (struct GNUNET_BIO_ReadHandle *h,
  97                     const char *file, int line,
  98                     void *result, size_t len);
  99
 100 /**
 101  * Read 0-terminated string from a file.
 102  *
 103  * @param h handle to an open file
 104  * @param what describes what is being read (for error message creation)
 105  * @param result the buffer to store a pointer to the (allocated) string to
 106  *        (note that *result could be set to NULL as well)
 107  * @param max_length maximum allowed length for the string
 108  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 109  */
 110 int
 111 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
 112                         char **result, size_t max_length);
 113
 114
 115 /**
 116  * Read metadata container from a file.
 117  *
 118  * @param h handle to an open file
 119  * @param what describes what is being read (for error message creation)
 120  * @param result the buffer to store a pointer to the (allocated) metadata
 121  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 122  */
 123 int
 124 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
 125                            struct GNUNET_CONTAINER_MetaData **result);
 126
 127
 128 /**
 129  * Read a float.
 130  *
 131  * @param h hande to open file
 132  * @param f address of float to read
 133  */
 134 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float)))
 135
 136
 137
 138 /**
 139  * Read a double.
 140  *
 141  * @param h hande to open file
 142  * @param f address of double to read
 143  */
 144 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double)))
 145
 146
 147 /**
 148  * Read an (u)int32_t.
 149  *
 150  * @param h hande to open file
 151  * @param file name of the source file
 152  * @param line line number in the code
 153  * @param i address of 32-bit integer to read
 154  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 155  */
 156 int
 157 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 158                          int line, int32_t * i);
 159
 160
 161 /**
 162  * Read an (u)int32_t.
 163  *
 164  * @param h hande to open file
 165  * @param i address of 32-bit integer to read
 166  */
 167 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, __LINE__, (int32_t*) i)
 168
 169
 170 /**
 171  * Read an (u)int64_t.
 172  *
 173  * @param h hande to open file
 174  * @param file name of the source file
 175  * @param line line number in the code
 176  * @param i address of 64-bit integer to read
 177  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 178  */
 179 int
 180 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 181                          int line, int64_t * i);
 182
 183
 184 /**
 185  * Read an (u)int64_t.
 186  *
 187  * @param h hande to open file
 188  * @param i address of 64-bit integer to read
 189  */
 190 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i)
 191
 192
 193 /**
 194  * Handle for buffered writing.
 195  */
 196 struct GNUNET_BIO_WriteHandle;
 197
 198 /**
 199  * Open a file for writing.
 200  *
 201  * @param fn file name to be opened
 202  * @return IO handle on success, NULL on error
 203  */
 204 struct GNUNET_BIO_WriteHandle *
 205 GNUNET_BIO_write_open (const char *fn);
 206
 207
 208 /**
 209  * Close an open file for writing.
 210  *
 211  * @param h file handle
 212  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
 213  */
 214 int
 215 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
 216
 217
 218 /**
 219  * Write a buffer to a file.
 220  *
 221  * @param h handle to open file
 222  * @param buffer the data to write
 223  * @param n number of bytes to write
 224  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 225  */
 226 int
 227 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
 228                   size_t n);
 229
 230
 231 /**
 232  * Force a buffered writer to flush its buffer
 233  *
 234  * @param h the writer handle
 235  * @return #GNUNET_OK upon success.  Upon failure #GNUNET_SYSERR is returned and
 236  *           the file is closed
 237  */
 238 int
 239 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
 240
 241
 242 /**
 243  * Write a string to a file.
 244  *
 245  * @param h handle to open file
 246  * @param s string to write (can be NULL)
 247  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 248  */
 249 int
 250 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
 251
 252
 253 /**
 254  * Write metadata container to a file.
 255  *
 256  * @param h handle to open file
 257  * @param m metadata to write
 258  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 259  */
 260 int
 261 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
 262                             const struct GNUNET_CONTAINER_MetaData *m);
 263
 264
 265
 266 /**
 267  * Write a float.
 268  *
 269  * @param h hande to open file
 270  * @param f float to write (must be a variable)
 271  */
 272 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
 273
 274
 275
 276 /**
 277  * Write a double.
 278  *
 279  * @param h hande to open file
 280  * @param f double to write (must be a variable)
 281  */
 282 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
 283
 284
 285 /**
 286  * Write an (u)int32_t.
 287  *
 288  * @param h hande to open file
 289  * @param i 32-bit integer to write
 290  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 291  */
 292 int
 293 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
 294
 295
 296 /**
 297  * Write an (u)int64_t.
 298  *
 299  * @param h hande to open file
 300  * @param i 64-bit integer to write
 301  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 302  */
 303 int
 304 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
 305
 306
 307 #if 0                           /* keep Emacsens' auto-indent happy */
 308 {
 309 #endif
 310 #ifdef __cplusplus
 311 }
 312 #endif
 313
 314 /** @} */ /* end of group bio */
 315
 316 /* ifndef GNUNET_BIO_LIB_H */
 317 #endif
 318 /* end of gnunet_bio_lib.h */