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