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