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