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