2 This file is part of GNUnet.
3 Copyright (C) 2009 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
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 Affero General Public License for more details.
17 * @author Christian Grothoff
22 * @defgroup bio BIO library
23 * Buffered binary disk IO (with endianess conversion)
27 #ifndef GNUNET_BIO_LIB_H
28 #define GNUNET_BIO_LIB_H
30 #include "gnunet_container_lib.h"
35 #if 0 /* keep Emacsens' auto-indent happy */
41 * Handle for buffered reading.
43 struct GNUNET_BIO_ReadHandle;
47 * Open a file for reading.
49 * @param fn file name to be opened
50 * @return IO handle on success, NULL on error
52 struct GNUNET_BIO_ReadHandle *
53 GNUNET_BIO_read_open (const char *fn);
57 * Close an open file. Reports if any errors reading
58 * from the file were encountered.
60 * @param h file handle
61 * @param emsg set to the error message
62 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
65 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
69 * Read the contents of a binary file into a buffer.
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
78 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
79 void *result, size_t len);
83 * Read the contents of a binary file into a buffer.
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
93 GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h,
94 const char *file, int line,
95 void *result, size_t len);
98 * Read 0-terminated string from a file.
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 max_length maximum allowed length for the string
105 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
108 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
109 char **result, size_t max_length);
113 * Read metadata container from a file.
115 * @param h handle to an open file
116 * @param what describes what is being read (for error message creation)
117 * @param result the buffer to store a pointer to the (allocated) metadata
118 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
121 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
122 struct GNUNET_CONTAINER_MetaData **result);
128 * @param h hande to open file
129 * @param f address of float to read
131 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float)))
138 * @param h hande to open file
139 * @param f address of double to read
141 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double)))
145 * Read an (u)int32_t.
147 * @param h hande to open file
148 * @param file name of the source file
149 * @param line line number in the code
150 * @param i address of 32-bit integer to read
151 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
154 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
155 int line, int32_t * i);
159 * Read an (u)int32_t.
161 * @param h hande to open file
162 * @param i address of 32-bit integer to read
164 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, __LINE__, (int32_t*) i)
168 * Read an (u)int64_t.
170 * @param h hande to open file
171 * @param file name of the source file
172 * @param line line number in the code
173 * @param i address of 64-bit integer to read
174 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
177 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
178 int line, int64_t * i);
182 * Read an (u)int64_t.
184 * @param h hande to open file
185 * @param i address of 64-bit integer to read
187 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i)
191 * Handle for buffered writing.
193 struct GNUNET_BIO_WriteHandle;
196 * Open a file for writing.
198 * @param fn file name to be opened
199 * @return IO handle on success, NULL on error
201 struct GNUNET_BIO_WriteHandle *
202 GNUNET_BIO_write_open (const char *fn);
206 * Close an open file for writing.
208 * @param h file handle
209 * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
212 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
216 * Write a buffer to a file.
218 * @param h handle to open file
219 * @param buffer the data to write
220 * @param n number of bytes to write
221 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
224 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
229 * Force a buffered writer to flush its buffer
231 * @param h the writer handle
232 * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned and
236 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
240 * Write a string to a file.
242 * @param h handle to open file
243 * @param s string to write (can be NULL)
244 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
247 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
251 * Write metadata container to a file.
253 * @param h handle to open file
254 * @param m metadata to write
255 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
258 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
259 const struct GNUNET_CONTAINER_MetaData *m);
266 * @param h hande to open file
267 * @param f float to write (must be a variable)
269 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
276 * @param h hande to open file
277 * @param f double to write (must be a variable)
279 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
283 * Write an (u)int32_t.
285 * @param h hande to open file
286 * @param i 32-bit integer to write
287 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
290 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
294 * Write an (u)int64_t.
296 * @param h hande to open file
297 * @param i 64-bit integer to write
298 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
301 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
304 #if 0 /* keep Emacsens' auto-indent happy */
311 /* ifndef GNUNET_BIO_LIB_H */
314 /** @} */ /* end of group bio */
316 /* end of gnunet_bio_lib.h */