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