2 This file is part of GNUnet
3 Copyright (C) 2016 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.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
19 * @author Christian Grothoff
20 * @author Christophe Genevey
23 * Helper library to access a MySQL database
25 * @defgroup mysql MySQL library
26 * Helper library to access a MySQL database.
29 #ifndef GNUNET_MY_LIB_H
30 #define GNUNET_MY_LIB_H
32 #include "gnunet_util_lib.h"
33 #include "gnunet_mysql_lib.h"
34 #include <mysql/mysql.h>
39 #if 0 /* keep Emacsens' auto-indent happy */
47 * Information we pass to #GNUNET_MY_exec_prepared() to
48 * initialize the arguments of the prepared statement.
50 struct GNUNET_MY_QueryParam;
54 * Function called to convert input argument into SQL parameters.
57 * @param pq data about the query
58 * @param qbind array of parameters to initialize
62 (*GNUNET_MY_QueryConverter)(void *cls,
63 const struct GNUNET_MY_QueryParam *qp,
68 * Function called to cleanup result data.
71 * @param rs spec to clean up
74 (*GNUNET_MY_QueryCleanup)(void *cls,
77 * Information we pass to #GNUNET_MY_exec_prepared() to
78 * initialize the arguments of the prepared statement.
82 struct GNUNET_MY_QueryParam
86 * Function to call for the type conversion.
88 GNUNET_MY_QueryConverter conv;
91 * Function to call for cleaning up the query. Can be NULL.
93 GNUNET_MY_QueryCleanup cleaner;
96 * Closure for @e conv.
101 * Number of arguments the @a conv converter expects to initialize.
103 unsigned int num_params;
106 * Information to pass to @e conv.
111 * Information to pass to @e conv. Size of @a data.
113 unsigned long data_len;
118 * End of query parameter specification.
120 * @return array last entry for the result specification to use
122 #define GNUNET_MY_query_param_end { NULL, NULL, NULL, 0, NULL, 0 }
126 * Generate query parameter for a buffer @a ptr of
127 * @a ptr_size bytes.FG
129 * @param ptr pointer to the query parameter to pass
130 * @oaran ptr_size number of bytes in @a ptr
132 struct GNUNET_MY_QueryParam
133 GNUNET_MY_query_param_fixed_size (const void *ptr,
138 * Run a prepared SELECT statement.
140 * @param mc mysql context
141 * @param sh handle to SELECT statment
142 * @param params parameters to the statement
146 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
147 struct GNUNET_MYSQL_StatementHandle *sh,
148 struct GNUNET_MY_QueryParam *params);
152 * Information we pass to #GNUNET_MY_extract_result() to
153 * initialize the arguments of the prepared statement.
155 struct GNUNET_MY_ResultParam;
158 * Information we pass to #GNUNET_MY_extract_result() to
159 * initialize the arguments of the prepared statement.
161 struct GNUNET_MY_ResultSpec;
164 * Function called to convert input argument into SQL parameters.
168 * @param stmt the mysql statement that is being run
169 * @param column the column that is being processed
170 * @param[out] results
171 * @return -1 on error
174 (*GNUNET_MY_ResultConverter)(void *cls,
175 struct GNUNET_MY_ResultSpec *rs,
178 MYSQL_BIND *results);
181 * Function called to cleanup result data.
184 * @param rs spec to clean up
187 (*GNUNET_MY_ResultCleanup)(void *cls,
188 struct GNUNET_MY_ResultSpec *rs);
192 * Information we pass to #GNUNET_MY_extract_result() to
193 * initialize the arguments of the prepared statement.
195 struct GNUNET_MY_ResultSpec
199 * Function to call to initialize the MYSQL_BIND array.
201 GNUNET_MY_ResultConverter pre_conv;
204 * Function to call for converting the result. Can be NULL.
206 GNUNET_MY_ResultConverter post_conv;
209 * Function to call for cleaning up the result. Can be NULL.
211 GNUNET_MY_ResultCleanup cleaner;
214 * Closure for @e conv.
219 * Destination for the data.
224 * Allowed size for the data, 0 for variable-size
225 * (in this case, the type of @e dst is a `void **`
226 * and we need to allocate a buffer of the right size).
231 * Where to store actual size of the result.
236 * How many fields does this result specification occupy
237 * in the result returned by MySQL.
239 unsigned int num_fields;
242 * Location where we temporarily store the output buffer
243 * length from MySQL. Internal to libgnunetmy.
245 unsigned long mysql_bind_output_length;
248 * Memory for MySQL to notify us about NULL values.
256 * End of result speceter specification.
258 * @return array last entry for the result specification to use
260 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0, 0 }
265 * Obtain fixed size result of @a ptr_size bytes from
266 * MySQL, store in already allocated buffer at @a ptr.
268 * @spec ptr where to write the result
269 * @oaran ptr_size number of bytes available at @a ptr
271 struct GNUNET_MY_ResultSpec
272 GNUNET_MY_result_spec_fixed_size (void *ptr,
276 * Generate query parameter for a string
278 *@param ptr pointer to the string query parameter to pass
280 struct GNUNET_MY_QueryParam
281 GNUNET_MY_query_param_string (const char *ptr);
284 * Generate fixed-size query parameter with size determined
287 * @param x pointer to the query parameter to pass
289 #define GNUNET_MY_query_param_auto_from_type(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
292 * Generate query parameter for an RSA public key. The
293 * database must contain a BLOB type in the respective position.
295 * @param x the query parameter to pass
296 * @return array entry for the query parameters to use
298 struct GNUNET_MY_QueryParam
299 GNUNET_MY_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
302 * Generate query parameter for an RSA signature. The
303 * database must contain a BLOB type in the respective position
305 *@param x the query parameter to pass
306 *@return array entry for the query parameters to use
308 struct GNUNET_MY_QueryParam
309 GNUNET_MY_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
312 * Generate query parameter for an absolute time value.
313 * The database must store a 64-bit integer.
315 *@param x pointer to the query parameter to pass
316 *@return array entry for the query parameters to use
318 struct GNUNET_MY_QueryParam
319 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
323 * Generate query parameter for an absolute time value.
324 * The database must store a 64-bit integer.
326 *@param x pointer to the query parameter to pass
328 struct GNUNET_MY_QueryParam
329 GNUNET_MY_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
332 * Generate query parameter for an uint16_t in host byte order.
334 * @param x pointer to the query parameter to pass
336 struct GNUNET_MY_QueryParam
337 GNUNET_MY_query_param_uint16 (const uint16_t *x);
340 * Generate query parameter for an uint32_t in host byte order
342 *@param x pointer to the query parameter to pass
344 struct GNUNET_MY_QueryParam
345 GNUNET_MY_query_param_uint32 (const uint32_t *x);
348 * Generate query parameter for an uint64_t in host byte order
350 *@param x pointer to the query parameter to pass
352 struct GNUNET_MY_QueryParam
353 GNUNET_MY_query_param_uint64 (const uint64_t *x);
356 * We expect a fixed-size result, with size determined by the type of `* dst`
358 * @spec name name of the field in the table
359 * @spec dst point to where to store the result, type fits expected result size
360 * @return array entry for the result specification to use
362 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
366 * Variable-size result expected
368 * @param[out] dst where to store the result, allocated
369 * @param[out] sptr where to store the size of @a dst
370 * @return array entru for the result specification to use
372 struct GNUNET_MY_ResultSpec
373 GNUNET_MY_result_spec_variable_size (void **dst,
377 * RSA public key expected
379 * @param name name of the field in the table
380 * @param[out] rsa where to store the result
381 * @return array entry for the result specification to use
383 struct GNUNET_MY_ResultSpec
384 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
388 * RSA signature expected.
390 * @param[out] sig where to store the result;
391 * @return array entry for the result specification to use
393 struct GNUNET_MY_ResultSpec
394 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
397 * 0- terminated string exprected.
399 * @param[out] dst where to store the result, allocated
400 * @return array entry for the result specification to use
402 struct GNUNET_MY_ResultSpec
403 GNUNET_MY_result_spec_string (char **dst);
406 * Absolute time expected
408 * @param name name of the field in the table
409 * @param[out] at where to store the result
410 * @return array entry for the result specification to use
412 struct GNUNET_MY_ResultSpec
413 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
416 * Absolute time in network byte order expected
418 * @param[out] at where to store the result
419 * @return array entry for the result specification to use
421 struct GNUNET_MY_ResultSpec
422 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
427 * @param[out] u16 where to store the result
428 * @return array entry for the result specification to use
430 struct GNUNET_MY_ResultSpec
431 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
436 * @param[out] u32 where to store the result
437 * @return array entry for the result specification to use
439 struct GNUNET_MY_ResultSpec
440 GNUNET_MY_result_spec_uint32 (uint32_t *u32);
445 * @param[out] u64 where to store the result
446 * @return array entry for the result specification to use
448 struct GNUNET_MY_ResultSpec
449 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
453 * Extract results from a query result according to the given
454 * specification. Always fetches the next row.
456 * @param sh statement that returned results
457 * @param rs specification to extract for
459 * #GNUNET_YES if all results could be extracted
460 * #GNUNET_NO if there is no more data in the result set
461 * #GNUNET_SYSERR if a result was invalid
464 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
465 struct GNUNET_MY_ResultSpec *specs);
469 * Free all memory that was allocated in @a qp during
470 * #GNUNET_MY_exect_prepared().
472 * @param qp query specification to clean up
473 * @param qbind mysql query
476 GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp,
481 * Free all memory that was allocated in @a rs during
482 * #GNUNET_MY_extract_result().
484 * @param rs reult specification to clean up
487 GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
490 #if 0 /* keep Emacsens' auto-indent happy */
499 /** @} */ /* end of group */