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
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
21 * @author Christian Grothoff
22 * @author Christophe Genevey
25 * Helper library to access a MySQL database
27 * @defgroup mysql MySQL library
28 * Helper library to access a MySQL database.
31 #ifndef GNUNET_MY_LIB_H
32 #define GNUNET_MY_LIB_H
34 #include "gnunet_util_lib.h"
35 #include "gnunet_mysql_lib.h"
36 #include <mysql/mysql.h>
41 #if 0 /* keep Emacsens' auto-indent happy */
49 * Information we pass to #GNUNET_MY_exec_prepared() to
50 * initialize the arguments of the prepared statement.
52 struct GNUNET_MY_QueryParam;
56 * Function called to convert input argument into SQL parameters.
59 * @param pq data about the query
60 * @param qbind array of parameters to initialize
64 (*GNUNET_MY_QueryConverter)(void *cls,
65 const struct GNUNET_MY_QueryParam *qp,
70 * Function called to cleanup result data.
73 * @param rs spec to clean up
76 (*GNUNET_MY_QueryCleanup)(void *cls,
79 * Information we pass to #GNUNET_MY_exec_prepared() to
80 * initialize the arguments of the prepared statement.
84 struct GNUNET_MY_QueryParam
88 * Function to call for the type conversion.
90 GNUNET_MY_QueryConverter conv;
93 * Function to call for cleaning up the query. Can be NULL.
95 GNUNET_MY_QueryCleanup cleaner;
98 * Closure for @e conv.
103 * Number of arguments the @a conv converter expects to initialize.
105 unsigned int num_params;
108 * Information to pass to @e conv.
113 * Information to pass to @e conv. Size of @a data.
115 unsigned long data_len;
120 * End of query parameter specification.
122 * @return array last entry for the result specification to use
124 #define GNUNET_MY_query_param_end { NULL, NULL, NULL, 0, NULL, 0 }
128 * Generate query parameter for a buffer @a ptr of
129 * @a ptr_size bytes.FG
131 * @param ptr pointer to the query parameter to pass
132 * @oaran ptr_size number of bytes in @a ptr
134 struct GNUNET_MY_QueryParam
135 GNUNET_MY_query_param_fixed_size (const void *ptr,
140 * Run a prepared SELECT statement.
142 * @param mc mysql context
143 * @param sh handle to SELECT statment
144 * @param params parameters to the statement
148 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
149 struct GNUNET_MYSQL_StatementHandle *sh,
150 struct GNUNET_MY_QueryParam *params);
154 * Information we pass to #GNUNET_MY_extract_result() to
155 * initialize the arguments of the prepared statement.
157 struct GNUNET_MY_ResultParam;
160 * Information we pass to #GNUNET_MY_extract_result() to
161 * initialize the arguments of the prepared statement.
163 struct GNUNET_MY_ResultSpec;
166 * Function called to convert input argument into SQL parameters.
170 * @param stmt the mysql statement that is being run
171 * @param column the column that is being processed
172 * @param[out] results
173 * @return -1 on error
176 (*GNUNET_MY_ResultConverter)(void *cls,
177 struct GNUNET_MY_ResultSpec *rs,
180 MYSQL_BIND *results);
183 * Function called to cleanup result data.
186 * @param rs spec to clean up
189 (*GNUNET_MY_ResultCleanup)(void *cls,
190 struct GNUNET_MY_ResultSpec *rs);
194 * Information we pass to #GNUNET_MY_extract_result() to
195 * initialize the arguments of the prepared statement.
197 struct GNUNET_MY_ResultSpec
201 * Function to call to initialize the MYSQL_BIND array.
203 GNUNET_MY_ResultConverter pre_conv;
206 * Function to call for converting the result. Can be NULL.
208 GNUNET_MY_ResultConverter post_conv;
211 * Function to call for cleaning up the result. Can be NULL.
213 GNUNET_MY_ResultCleanup cleaner;
216 * Closure for @e conv.
221 * Destination for the data.
226 * Allowed size for the data, 0 for variable-size
227 * (in this case, the type of @e dst is a `void **`
228 * and we need to allocate a buffer of the right size).
233 * Where to store actual size of the result.
238 * How many fields does this result specification occupy
239 * in the result returned by MySQL.
241 unsigned int num_fields;
244 * Location where we temporarily store the output buffer
245 * length from MySQL. Internal to libgnunetmy.
247 unsigned long mysql_bind_output_length;
250 * Memory for MySQL to notify us about NULL values.
258 * End of result speceter specification.
260 * @return array last entry for the result specification to use
262 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0, 0 }
267 * Obtain fixed size result of @a ptr_size bytes from
268 * MySQL, store in already allocated buffer at @a ptr.
270 * @spec ptr where to write the result
271 * @oaran ptr_size number of bytes available at @a ptr
273 struct GNUNET_MY_ResultSpec
274 GNUNET_MY_result_spec_fixed_size (void *ptr,
278 * Generate query parameter for a string
280 *@param ptr pointer to the string query parameter to pass
282 struct GNUNET_MY_QueryParam
283 GNUNET_MY_query_param_string (const char *ptr);
286 * Generate fixed-size query parameter with size determined
289 * @param x pointer to the query parameter to pass
291 #define GNUNET_MY_query_param_auto_from_type(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
294 * Generate query parameter for an RSA public key. The
295 * database must contain a BLOB type in the respective position.
297 * @param x the query parameter to pass
298 * @return array entry for the query parameters to use
300 struct GNUNET_MY_QueryParam
301 GNUNET_MY_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
304 * Generate query parameter for an RSA signature. The
305 * database must contain a BLOB type in the respective position
307 *@param x the query parameter to pass
308 *@return array entry for the query parameters to use
310 struct GNUNET_MY_QueryParam
311 GNUNET_MY_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
314 * Generate query parameter for an absolute time value.
315 * The database must store a 64-bit integer.
317 *@param x pointer to the query parameter to pass
318 *@return array entry for the query parameters to use
320 struct GNUNET_MY_QueryParam
321 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
325 * Generate query parameter for an absolute time value.
326 * The database must store a 64-bit integer.
328 *@param x pointer to the query parameter to pass
330 struct GNUNET_MY_QueryParam
331 GNUNET_MY_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
334 * Generate query parameter for an uint16_t in host byte order.
336 * @param x pointer to the query parameter to pass
338 struct GNUNET_MY_QueryParam
339 GNUNET_MY_query_param_uint16 (const uint16_t *x);
342 * Generate query parameter for an uint32_t in host byte order
344 *@param x pointer to the query parameter to pass
346 struct GNUNET_MY_QueryParam
347 GNUNET_MY_query_param_uint32 (const uint32_t *x);
350 * Generate query parameter for an uint64_t in host byte order
352 *@param x pointer to the query parameter to pass
354 struct GNUNET_MY_QueryParam
355 GNUNET_MY_query_param_uint64 (const uint64_t *x);
358 * We expect a fixed-size result, with size determined by the type of `* dst`
360 * @spec name name of the field in the table
361 * @spec dst point to where to store the result, type fits expected result size
362 * @return array entry for the result specification to use
364 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
368 * Variable-size result expected
370 * @param[out] dst where to store the result, allocated
371 * @param[out] sptr where to store the size of @a dst
372 * @return array entru for the result specification to use
374 struct GNUNET_MY_ResultSpec
375 GNUNET_MY_result_spec_variable_size (void **dst,
379 * RSA public key expected
381 * @param name name of the field in the table
382 * @param[out] rsa where to store the result
383 * @return array entry for the result specification to use
385 struct GNUNET_MY_ResultSpec
386 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
390 * RSA signature expected.
392 * @param[out] sig where to store the result;
393 * @return array entry for the result specification to use
395 struct GNUNET_MY_ResultSpec
396 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
399 * 0- terminated string exprected.
401 * @param[out] dst where to store the result, allocated
402 * @return array entry for the result specification to use
404 struct GNUNET_MY_ResultSpec
405 GNUNET_MY_result_spec_string (char **dst);
408 * Absolute time expected
410 * @param name name of the field in the table
411 * @param[out] at where to store the result
412 * @return array entry for the result specification to use
414 struct GNUNET_MY_ResultSpec
415 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
418 * Absolute time in network byte order expected
420 * @param[out] at where to store the result
421 * @return array entry for the result specification to use
423 struct GNUNET_MY_ResultSpec
424 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
429 * @param[out] u16 where to store the result
430 * @return array entry for the result specification to use
432 struct GNUNET_MY_ResultSpec
433 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
438 * @param[out] u32 where to store the result
439 * @return array entry for the result specification to use
441 struct GNUNET_MY_ResultSpec
442 GNUNET_MY_result_spec_uint32 (uint32_t *u32);
447 * @param[out] u64 where to store the result
448 * @return array entry for the result specification to use
450 struct GNUNET_MY_ResultSpec
451 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
455 * Extract results from a query result according to the given
456 * specification. Always fetches the next row.
458 * @param sh statement that returned results
459 * @param rs specification to extract for
461 * #GNUNET_YES if all results could be extracted
462 * #GNUNET_NO if there is no more data in the result set
463 * #GNUNET_SYSERR if a result was invalid
466 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
467 struct GNUNET_MY_ResultSpec *specs);
471 * Free all memory that was allocated in @a qp during
472 * #GNUNET_MY_exect_prepared().
474 * @param qp query specification to clean up
475 * @param qbind mysql query
478 GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp,
483 * Free all memory that was allocated in @a rs during
484 * #GNUNET_MY_extract_result().
486 * @param rs reult specification to clean up
489 GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
492 #if 0 /* keep Emacsens' auto-indent happy */
501 /** @} */ /* end of group */