aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_my_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_my_lib.h')
-rw-r--r--src/include/gnunet_my_lib.h511
1 files changed, 0 insertions, 511 deletions
diff --git a/src/include/gnunet_my_lib.h b/src/include/gnunet_my_lib.h
deleted file mode 100644
index 283b2f7e6..000000000
--- a/src/include/gnunet_my_lib.h
+++ /dev/null
@@ -1,511 +0,0 @@
1/*
2 This file is part of GNUnet
3 Copyright (C) 2016 GNUnet e.V.
4
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.
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 Affero General Public License for more details.
14
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/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20/**
21 * @addtogroup lib_extra
22 * @{
23 *
24 * @author Christian Grothoff
25 * @author Christophe Genevey
26 * @author Martin Schanzenbach
27 *
28 * @file
29 * Helper library to access a MySQL database
30 *
31 * @defgroup mysql MySQL library
32 * Helper library to access a MySQL database.
33 * @{
34 */
35#ifndef GNUNET_MY_LIB_H
36#define GNUNET_MY_LIB_H
37
38
39#include "gnunet_util_lib.h"
40#include "gnunet_mysql_lib.h"
41#include <mysql/mysql.h>
42
43#ifndef MYSQL_BOOL
44#error "You need to define MYSQL_BOOL. See (or include) gnunet_mysql_compat.h"
45#endif
46
47#ifdef __cplusplus
48extern "C"
49{
50#if 0 /* keep Emacsens' auto-indent happy */
51}
52#endif
53#endif
54
55
56/**
57 * Information we pass to #GNUNET_MY_exec_prepared() to
58 * initialize the arguments of the prepared statement.
59 */
60struct GNUNET_MY_QueryParam;
61
62
63/**
64 * Function called to convert input argument into SQL parameters.
65 *
66 * @param cls closure
67 * @param pq data about the query
68 * @param qbind array of parameters to initialize
69 * @return -1 on error
70 */
71typedef int
72(*GNUNET_MY_QueryConverter)(void *cls,
73 const struct GNUNET_MY_QueryParam *qp,
74 MYSQL_BIND *qbind);
75
76
77/**
78 * Function called to cleanup result data.
79 *
80 * @param cls closure
81 * @param rs spec to clean up
82 */
83typedef void
84(*GNUNET_MY_QueryCleanup)(void *cls,
85 MYSQL_BIND *qbind);
86/**
87 * Information we pass to #GNUNET_MY_exec_prepared() to
88 * initialize the arguments of the prepared statement.
89 */
90
91
92struct GNUNET_MY_QueryParam
93{
94 /**
95 * Function to call for the type conversion.
96 */
97 GNUNET_MY_QueryConverter conv;
98
99 /**
100 * Function to call for cleaning up the query. Can be NULL.
101 */
102 GNUNET_MY_QueryCleanup cleaner;
103
104 /**
105 * Closure for @e conv.
106 */
107 void *conv_cls;
108
109 /**
110 * Number of arguments the @a conv converter expects to initialize.
111 */
112 unsigned int num_params;
113
114 /**
115 * Information to pass to @e conv.
116 */
117 const void *data;
118
119 /**
120 * Information to pass to @e conv. Size of @a data.
121 */
122 unsigned long data_len;
123};
124
125/**
126 * End of query parameter specification.
127 *
128 * @return array last entry for the result specification to use
129 */
130#define GNUNET_MY_query_param_end { NULL, NULL, NULL, 0, NULL, 0 }
131
132
133/**
134 * Generate query parameter for a buffer @a ptr of
135 * @a ptr_size bytes.FG
136 *
137 * @param ptr pointer to the query parameter to pass
138 * @param ptr_size number of bytes in @a ptr
139 */
140struct GNUNET_MY_QueryParam
141GNUNET_MY_query_param_fixed_size (const void *ptr,
142 size_t ptr_size);
143
144
145/**
146 * Run a prepared SELECT statement.
147 *
148 * @param mc mysql context
149 * @param sh handle to SELECT statement
150 * @param params parameters to the statement
151 * @return TBD
152 */
153int
154GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
155 struct GNUNET_MYSQL_StatementHandle *sh,
156 struct GNUNET_MY_QueryParam *params);
157
158
159/**
160 * Information we pass to #GNUNET_MY_extract_result() to
161 * initialize the arguments of the prepared statement.
162 */
163struct GNUNET_MY_ResultParam;
164
165/**
166 * Information we pass to #GNUNET_MY_extract_result() to
167 * initialize the arguments of the prepared statement.
168 */
169struct GNUNET_MY_ResultSpec;
170
171/**
172 * Function called to convert input argument into SQL parameters.
173 *
174 * @param cls closure
175 * @param[in,out] rs
176 * @param stmt the mysql statement that is being run
177 * @param column the column that is being processed
178 * @param[out] results
179 * @return -1 on error
180 */
181typedef int
182(*GNUNET_MY_ResultConverter)(void *cls,
183 struct GNUNET_MY_ResultSpec *rs,
184 MYSQL_STMT *stmt,
185 unsigned int column,
186 MYSQL_BIND *results);
187
188/**
189 * Function called to cleanup result data.
190 *
191 * @param cls closure
192 * @param rs spec to clean up
193 */
194typedef void
195(*GNUNET_MY_ResultCleanup)(void *cls,
196 struct GNUNET_MY_ResultSpec *rs);
197
198
199/**
200 * Information we pass to #GNUNET_MY_extract_result() to
201 * initialize the arguments of the prepared statement.
202 */
203struct GNUNET_MY_ResultSpec
204{
205 /**
206 * Function to call to initialize the MYSQL_BIND array.
207 */
208 GNUNET_MY_ResultConverter pre_conv;
209
210 /**
211 * Function to call for converting the result. Can be NULL.
212 */
213 GNUNET_MY_ResultConverter post_conv;
214
215 /**
216 * Function to call for cleaning up the result. Can be NULL.
217 */
218 GNUNET_MY_ResultCleanup cleaner;
219
220 /**
221 * Closure for @e conv.
222 */
223 void *conv_cls;
224
225 /**
226 * Destination for the data.
227 */
228 void *dst;
229
230 /**
231 * Allowed size for the data, 0 for variable-size
232 * (in this case, the type of @e dst is a `void **`
233 * and we need to allocate a buffer of the right size).
234 */
235 size_t dst_size;
236
237 /**
238 * Where to store actual size of the result.
239 */
240 size_t *result_size;
241
242 /**
243 * How many fields does this result specification occupy
244 * in the result returned by MySQL.
245 */
246 unsigned int num_fields;
247
248 /**
249 * Location where we temporarily store the output buffer
250 * length from MySQL. Internal to libgnunetmy.
251 */
252 unsigned long mysql_bind_output_length;
253
254 /**
255 * Memory for MySQL to notify us about NULL values.
256 */
257 MYSQL_BOOL is_null;
258};
259
260
261/**
262 * End of result speceter specification.
263 *
264 * @return array last entry for the result specification to use
265 */
266#define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0, 0 }
267
268
269/**
270 * Obtain fixed size result of @a ptr_size bytes from
271 * MySQL, store in already allocated buffer at @a ptr.
272 *
273 * @spec ptr where to write the result
274 * @param ptr_size number of bytes available at @a ptr
275 */
276struct GNUNET_MY_ResultSpec
277GNUNET_MY_result_spec_fixed_size (void *ptr,
278 size_t ptr_size);
279
280/**
281 * Generate query parameter for a string
282 *
283 * @param ptr pointer to the string query parameter to pass
284 */
285struct GNUNET_MY_QueryParam
286GNUNET_MY_query_param_string (const char *ptr);
287
288/**
289 * Generate fixed-size query parameter with size determined
290 * by variable type.
291 *
292 * @param x pointer to the query parameter to pass
293 */
294#define GNUNET_MY_query_param_auto_from_type( \
295 x) GNUNET_MY_query_param_fixed_size ((x), sizeof(*(x)))
296
297/**
298 * Generate query parameter for an RSA public key. The
299 * database must contain a BLOB type in the respective position.
300 *
301 * @param x the query parameter to pass
302 * @return array entry for the query parameters to use
303 */
304struct GNUNET_MY_QueryParam
305GNUNET_MY_query_param_rsa_public_key (const struct
306 GNUNET_CRYPTO_RsaPublicKey *x);
307
308/**
309 * Generate query parameter for an RSA signature. The
310 * database must contain a BLOB type in the respective position
311 *
312 *@param x the query parameter to pass
313 *@return array entry for the query parameters to use
314 */
315struct GNUNET_MY_QueryParam
316GNUNET_MY_query_param_rsa_signature (const struct
317 GNUNET_CRYPTO_RsaSignature *x);
318
319/**
320 * Generate query parameter for an absolute time value.
321 * The database must store a 64-bit integer.
322 *
323 *@param x pointer to the query parameter to pass
324 *@return array entry for the query parameters to use
325 */
326struct GNUNET_MY_QueryParam
327GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
328
329
330/**
331 * Generate query parameter for an absolute time value.
332 * The database must store a 64-bit integer.
333 *
334 *@param x pointer to the query parameter to pass
335 */
336struct GNUNET_MY_QueryParam
337GNUNET_MY_query_param_absolute_time_nbo (const struct
338 GNUNET_TIME_AbsoluteNBO *x);
339
340/**
341 * Generate query parameter for an uint16_t in host byte order.
342 *
343 * @param x pointer to the query parameter to pass
344 */
345struct GNUNET_MY_QueryParam
346GNUNET_MY_query_param_uint16 (const uint16_t *x);
347
348/**
349 * Generate query parameter for an uint32_t in host byte order
350 *
351 * @param x pointer to the query parameter to pass
352 */
353struct GNUNET_MY_QueryParam
354GNUNET_MY_query_param_uint32 (const uint32_t *x);
355
356/**
357 * Generate query parameter for an uint64_t in host byte order
358 *
359 * @param x pointer to the query parameter to pass
360 */
361struct GNUNET_MY_QueryParam
362GNUNET_MY_query_param_uint64 (const uint64_t *x);
363
364/**
365 * We expect a fixed-size result, with size determined by the type of `* dst`
366 *
367 * @spec name name of the field in the table
368 * @spec dst point to where to store the result, type fits expected result size
369 * @return array entry for the result specification to use
370 */
371#define GNUNET_MY_result_spec_auto_from_type( \
372 dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof(*(dst)))
373
374
375/**
376 * Variable-size result expected
377 *
378 * @param[out] dst where to store the result, allocated
379 * @param[out] ptr_size where to store the size of @a dst
380 * @return array entry for the result specification to use
381 */
382struct GNUNET_MY_ResultSpec
383GNUNET_MY_result_spec_variable_size (void **dst,
384 size_t *ptr_size);
385
386/**
387 * RSA public key expected
388 *
389 * @param name name of the field in the table
390 * @param[out] rsa where to store the result
391 * @return array entry for the result specification to use
392 */
393struct GNUNET_MY_ResultSpec
394GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
395
396
397/**
398 * RSA signature expected.
399 *
400 * @param[out] sig where to store the result;
401 * @return array entry for the result specification to use
402 */
403struct GNUNET_MY_ResultSpec
404GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
405
406/**
407 * 0- terminated string exprected.
408 *
409 * @param[out] dst where to store the result, allocated
410 * @return array entry for the result specification to use
411 */
412struct GNUNET_MY_ResultSpec
413GNUNET_MY_result_spec_string (char **dst);
414
415/**
416 * Absolute time expected
417 *
418 * @param name name of the field in the table
419 * @param[out] at where to store the result
420 * @return array entry for the result specification to use
421 */
422struct GNUNET_MY_ResultSpec
423GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
424
425/**
426 * Absolute time in network byte order expected
427 *
428 * @param[out] at where to store the result
429 * @return array entry for the result specification to use
430 */
431struct GNUNET_MY_ResultSpec
432GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
433
434/**
435 * uint16_t expected
436 *
437 * @param[out] u16 where to store the result
438 * @return array entry for the result specification to use
439 */
440struct GNUNET_MY_ResultSpec
441GNUNET_MY_result_spec_uint16 (uint16_t *u16);
442
443/**
444 * uint32_t expected
445 *
446 * @param[out] u32 where to store the result
447 * @return array entry for the result specification to use
448 */
449struct GNUNET_MY_ResultSpec
450GNUNET_MY_result_spec_uint32 (uint32_t *u32);
451
452/**
453 * uint64_t expected.
454 *
455 * @param[out] u64 where to store the result
456 * @return array entry for the result specification to use
457 */
458struct GNUNET_MY_ResultSpec
459GNUNET_MY_result_spec_uint64 (uint64_t *u64);
460
461
462/**
463 * Extract results from a query result according to the given
464 * specification. Always fetches the next row.
465 *
466 * @param sh statement that returned results
467 * @param rs specification to extract for
468 * @return
469 * #GNUNET_YES if all results could be extracted
470 * #GNUNET_NO if there is no more data in the result set
471 * #GNUNET_SYSERR if a result was invalid
472 */
473int
474GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
475 struct GNUNET_MY_ResultSpec *specs);
476
477
478/**
479 * Free all memory that was allocated in @a qp during
480 * #GNUNET_MY_exect_prepared().
481 *
482 * @param qp query specification to clean up
483 * @param qbind mysql query
484 */
485void
486GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp,
487 MYSQL_BIND *qbind);
488
489
490/**
491 * Free all memory that was allocated in @a rs during
492 * #GNUNET_MY_extract_result().
493 *
494 * @param rs reult specification to clean up
495 */
496void
497GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
498
499
500#if 0 /* keep Emacsens' auto-indent happy */
501{
502#endif
503#ifdef __cplusplus
504}
505#endif
506
507#endif
508
509/** @} */ /* end of group */
510
511/** @} */ /* end of group addition to lib_extra */