2 This file is part of GNUnet
3 Copyright (C) 2012 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
24 * Helper library to access a MySQL database
26 * @defgroup mysql MySQL library
27 * Helper library to access a MySQL database.
30 #ifndef GNUNET_MY_LIB_H
31 #define GNUNET_MY_LIB_H
33 #include "gnunet_util_lib.h"
34 #include "gnunet_mysql_lib.h"
35 #include <mysql/mysql.h>
40 #if 0 /* keep Emacsens' auto-indent happy */
48 * Information we pass to #GNUNET_MY_exec_prepared() to
49 * initialize the arguments of the prepared statement.
51 struct GNUNET_MY_QueryParam;
55 * Function called to convert input argument into SQL parameters.
58 * @param pq data about the query
59 * @param qbind array of parameters to initialize
63 (*GNUNET_MY_QueryConverter)(void *cls,
64 const struct GNUNET_MY_QueryParam *qp,
69 * Information we pass to #GNUNET_MY_exec_prepared() to
70 * initialize the arguments of the prepared statement.
72 struct GNUNET_MY_QueryParam
76 * Function to call for the type conversion.
78 GNUNET_MY_QueryConverter conv;
81 * Closure for @e conv.
86 * Number of arguments the @a conv converter expects to initialize.
88 unsigned int num_params;
91 * Information to pass to @e conv.
96 * Information to pass to @e conv. Size of @a data.
98 unsigned long data_len ;
103 * End of query parameter specification.
105 * @return array last entry for the result specification to use
107 #define GNUNET_MY_query_param_end { NULL, NULL, 0, NULL, 0 }
112 * Generate query parameter for a buffer @a ptr of
113 * @a ptr_size bytes.FG
115 * @param ptr pointer to the query parameter to pass
116 * @oaran ptr_size number of bytes in @a ptr
118 struct GNUNET_MY_QueryParam
119 GNUNET_MY_query_param_fixed_size (const void *ptr,
123 * Run a prepared SELECT statement.
125 * @param mc mysql context
126 * @param sh handle to SELECT statment
127 * @param params parameters to the statement
131 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
132 struct GNUNET_MYSQL_StatementHandle *sh,
133 const struct GNUNET_MY_QueryParam *params);
137 * Information we pass to #GNUNET_MY_extract_result() to
138 * initialize the arguments of the prepared statement.
140 struct GNUNET_MY_ResultParam;
143 * Information we pass to #GNUNET_MY_extract_result() to
144 * initialize the arguments of the prepared statement.
146 struct GNUNET_MY_ResultSpec;
149 * Function called to convert input argument into SQL parameters.
152 * @param pq data about the query
153 * @return -1 on error
156 (*GNUNET_MY_ResultConverter)(void *cls,
157 struct GNUNET_MY_ResultSpec *rs,
158 MYSQL_BIND *results);
161 * Information we pass to #GNUNET_MY_extract_result() to
162 * initialize the arguments of the prepared statement.
164 struct GNUNET_MY_ResultSpec
168 * Function to call for the type conversion.
170 GNUNET_MY_ResultConverter conv;
173 * Closure for @e conv.
178 * Destination for the data.
183 * Allowed size for the data, 0 for variable-size
184 * (in this case, the type of @e dst is a `void **`
185 * and we need to allocate a buffer of the right size).
190 * Where to store actual size of the result.
198 * End of result speceter specification.
200 * @return array last entry for the result specification to use
202 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL }
207 * Obtain fixed size result of @a ptr_size bytes from
208 * MySQL, store in already allocated buffer at @a ptr.
210 * @spec ptr where to write the result
211 * @oaran ptr_size number of bytes available at @a ptr
213 struct GNUNET_MY_ResultSpec
214 GNUNET_MY_result_spec_fixed_size (void *ptr,
218 * Generate query parameter for a string
220 *@param ptr pointer to the string query parameter to pass
222 struct GNUNET_MY_QueryParam
223 GNUNET_MY_query_param_string (const char *ptr);
226 * Generate fixed-size query parameter with size determined
229 * @param x pointer to the query parameter to pass
231 #define GNUNET_MY_query_param_auto_from_type(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
234 * Generate query parameter for an RSA public key. The
235 * database must contain a BLOB type in the respective position.
237 * @param x the query parameter to pass
238 * @return array entry for the query parameters to use
240 struct GNUNET_MY_QueryParam
241 GNUNET_MY_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
244 * Generate query parameter for an RSA signature. The
245 * database must contain a BLOB type in the respective position
247 *@param x the query parameter to pass
248 *@return array entry for the query parameters to use
250 struct GNUNET_MY_QueryParam
251 GNUNET_MY_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
254 * Generate query parameter for an absolute time value.
255 * The database must store a 64-bit integer.
257 *@param x pointer to the query parameter to pass
258 *@return array entry for the query parameters to use
260 struct GNUNET_MY_QueryParam
261 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
264 * Generate query parameter for an absolute time value.
265 * The database must store a 64-bit integer.
267 *@param x pointer to the query parameter to pass
269 struct GNUNET_MY_QueryParam
270 GNUNET_MY_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
273 * Generate query parameter for an uint16_t in host byte order.
275 * @param x pointer to the query parameter to pass
277 struct GNUNET_MY_QueryParam
278 GNUNET_MY_query_param_uint16 (const uint16_t *x);
281 * Generate query parameter for an uint32_t in host byte order
283 *@param x pointer to the query parameter to pass
285 struct GNUNET_MY_QueryParam
286 GNUNET_MY_query_param_uint32 (const uint32_t *x);
289 * Generate query parameter for an uint64_t in host byte order
291 *@param x pointer to the query parameter to pass
293 struct GNUNET_MY_QueryParam
294 GNUNET_MY_query_param_uint64 (const uint64_t *x);
297 * We expect a fixed-size result, with size determined by the type of `* dst`
299 * @spec name name of the field in the table
300 * @spec dst point to where to store the result, type fits expected result size
301 * @return array entry for the result specification to use
303 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
312 * Variable-size result expected
314 * @param[out] dst where to store the result, allocated
315 * @param[out] sptr where to store the size of @a dst
316 * @return array entru for the result specification to use
318 struct GNUNET_MY_ResultSpec
319 GNUNET_MY_result_spec_variable_size (void **dst,
322 * RSA public key expected
324 * @param name name of the field in the table
325 * @param[out] rsa where to store the result
326 * @return array entry for the result specification to use
328 struct GNUNET_MY_ResultSpec
329 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
332 * RSA signature expected.
334 * @param[out] sig where to store the result;
335 * @return array entry for the result specification to use
337 struct GNUNET_MY_ResultSpec
338 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
341 * 0- terminated string exprected.
343 * @param[out] dst where to store the result, allocated
344 * @return array entry for the result specification to use
346 struct GNUNET_MY_ResultSpec
347 GNUNET_MY_result_spec_string (char **dst);
350 * Absolute time expected
352 * @param name name of the field in the table
353 * @param[out] at where to store the result
354 * @return array entry for the result specification to use
356 struct GNUNET_MY_ResultSpec
357 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
360 * Absolute time in network byte order expected
362 * @param[out] at where to store the result
363 * @return array entry for the result specification to use
365 struct GNUNET_MY_ResultSpec
366 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
371 * @param[out] u16 where to store the result
372 * @return array entry for the result specification to use
374 struct GNUNET_MY_ResultSpec
375 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
380 * @param[out] u32 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_uint32 (uint32_t *u32);
389 * @param[out] u64 where to store the result
390 * @return array entry for the result specification to use
392 struct GNUNET_MY_ResultSpec
393 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
396 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
397 struct GNUNET_MY_QueryParam *qp,
398 struct GNUNET_MY_ResultSpec *specs,
401 #if 0 /* keep Emacsens' auto-indent happy */
410 /** @} */ /* end of group */