aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_pq_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_pq_lib.h')
-rw-r--r--src/include/gnunet_pq_lib.h719
1 files changed, 679 insertions, 40 deletions
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h
index 6a374f7e2..b5d39ed41 100644
--- a/src/include/gnunet_pq_lib.h
+++ b/src/include/gnunet_pq_lib.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 Copyright (C) 2016, 2017, 2020, 2021 GNUnet e.V. 3 Copyright (C) 2016, 2017, 2020-2022 GNUnet e.V.
4 4
5 GNUnet is free software: you can redistribute it and/or modify it 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 6 under the terms of the GNU Affero General Public License as published
@@ -25,9 +25,19 @@
25#ifndef GNUNET_PQ_LIB_H 25#ifndef GNUNET_PQ_LIB_H
26#define GNUNET_PQ_LIB_H 26#define GNUNET_PQ_LIB_H
27 27
28
28#include <libpq-fe.h> 29#include <libpq-fe.h>
30#include <stdint.h>
31#include "gnunet_common.h"
32#include "gnunet_time_lib.h"
29#include "gnunet_util_lib.h" 33#include "gnunet_util_lib.h"
30#include "gnunet_db_lib.h" 34#include "gnunet_db_lib.h"
35#include "postgres_ext.h"
36
37/**
38 * Postgres context.
39 */
40struct GNUNET_PQ_Context;
31 41
32/* ************************* pq_query_helper.c functions ************************ */ 42/* ************************* pq_query_helper.c functions ************************ */
33 43
@@ -57,6 +67,14 @@ typedef int
57 void *scratch[], 67 void *scratch[],
58 unsigned int scratch_length); 68 unsigned int scratch_length);
59 69
70/**
71 * Function called to cleanup the closure of SQL parameters converter. Will be
72 * called with GNUNET_PQ_query_params_cleanup
73 *
74 * @param cls closure
75 */
76typedef void
77(*GNUNET_PQ_QueryConverter_Cleanup)(void *cls);
60 78
61/** 79/**
62 * @brief Description of a DB query parameter. 80 * @brief Description of a DB query parameter.
@@ -70,10 +88,20 @@ struct GNUNET_PQ_QueryParam
70 88
71 /** 89 /**
72 * Closure for @e conv. 90 * Closure for @e conv.
91 * The function @conv_cls_cleanup can be set to cleanup the closure.
92 * The cleanup of the closure MUST be triggered manually by a call to
93 * GNUNET_PQ_query_params_cleanup.
73 */ 94 */
74 void *conv_cls; 95 void *conv_cls;
75 96
76 /** 97 /**
98 * Function to cleanup the closure @a conv_cls, may be NULL.
99 * The cleanup of the closure MUST be triggered manually by a call to
100 * GNUNET_PQ_query_params_cleanup.
101 */
102 GNUNET_PQ_QueryConverter_Cleanup conv_cls_cleanup;
103
104 /**
77 * Data or NULL. 105 * Data or NULL.
78 */ 106 */
79 const void *data; 107 const void *data;
@@ -90,13 +118,26 @@ struct GNUNET_PQ_QueryParam
90 118
91}; 119};
92 120
121/**
122 * Must be called to cleanup memory from closures after the query parameters
123 * have been used as much as needed.
124 *
125 * @param params Array of GNUNET_PQ_QueryParam which must terminate with a GNUNET_PQ_query_param_end
126 */
127void
128GNUNET_PQ_cleanup_query_params_closures (
129 const struct GNUNET_PQ_QueryParam *params);
93 130
94/** 131/**
95 * End of query parameter specification. 132 * End of query parameter specification.
96 */ 133 */
97#define GNUNET_PQ_query_param_end \ 134#define GNUNET_PQ_query_param_end \
98 { \ 135 { \
99 NULL, NULL, NULL, 0, 0 \ 136 .conv = NULL, \
137 .conv_cls = NULL, \
138 .data = NULL, \
139 .size = 0, \
140 .num_params = 0 \
100 } 141 }
101 142
102 143
@@ -114,7 +155,7 @@ GNUNET_PQ_query_param_null (void);
114 * @a ptr_size bytes. 155 * @a ptr_size bytes.
115 * 156 *
116 * @param ptr pointer to the query parameter to pass 157 * @param ptr pointer to the query parameter to pass
117 * @oaran ptr_size number of bytes in @a ptr 158 * @param ptr_size number of bytes in @a ptr
118 * @return query parameter to use 159 * @return query parameter to use
119 */ 160 */
120struct GNUNET_PQ_QueryParam 161struct GNUNET_PQ_QueryParam
@@ -133,6 +174,220 @@ GNUNET_PQ_query_param_string (const char *ptr);
133 174
134 175
135/** 176/**
177 * Pass a boolean into a query.
178 *
179 * @param b boolean bit to pass
180 * @return query parameter to use
181 */
182struct GNUNET_PQ_QueryParam
183GNUNET_PQ_query_param_bool (bool b);
184
185/**
186 * Returns the oid for a given datatype by name.
187 *
188 * @param db The db-connection
189 * @param name The name of the datatype
190 * @param[out] oid The OID of the datatype.
191 * @return GNUNET_OK when the datatype was found, GNUNET_SYSERR otherwise
192 */
193enum GNUNET_GenericReturnValue
194GNUNET_PQ_get_oid_by_name (
195 struct GNUNET_PQ_Context *db,
196 const char *name,
197 Oid *oid);
198
199
200/**
201 * The header for a postgresql array in binary format. note that this a
202 * simplified special case of the general structure (which contains pointers),
203 * as we only support one-dimensional arrays.
204 *
205 * Note that all values must be in network-byte-order.
206 */
207struct GNUNET_PQ_ArrayHeader_P
208{
209 uint32_t ndim; /* number of dimensions. we only support ndim = 1 */
210 uint32_t has_null;
211 uint32_t oid; /* oid of the elements */
212 uint32_t dim; /* size of the array */
213 uint32_t lbound; /* index value of first element in the db (default: 1). */
214} __attribute__((packed));
215
216
217/**
218 * Generate query parameter for an array of bool in host byte order.
219 *
220 * @param num Number of elements in @a elements
221 * @param elements Continuous array of @a num boolean elements
222 * @param db Database context, needed for database-depending encoding of @a elements
223 * @return query parameter to use
224 */
225struct GNUNET_PQ_QueryParam
226GNUNET_PQ_query_param_array_bool (
227 unsigned int num,
228 const bool *elements,
229 struct GNUNET_PQ_Context *db);
230
231/**
232 * Generate query parameter for an array of uint16_t in host byte order.
233 * Note that the (unsigend) elements are not checked to wrap over INT2_MAX
234 *
235 * @param num Number of elements in @a elements
236 * @param elements Continuous array of @a num uint16 elements
237 * @param db Database context, needed for database-depending encoding of @a elements
238 * @return query parameter to use
239 */
240struct GNUNET_PQ_QueryParam
241GNUNET_PQ_query_param_array_uint16 (
242 unsigned int num,
243 const uint16_t *elements,
244 struct GNUNET_PQ_Context *db);
245
246/**
247 * Generate query parameter for an array of uint32_t in host byte order.
248 * Note that the (unsigend) elements are not checked to wrap over INT4_MAX
249 *
250 * @param num Number of elements in @a elements
251 * @param elements Continuous Array of @a num uint32_t elements
252 * @param db Database context, needed for database-depending encoding of @a elements
253 * @return query parameter to use
254 */
255struct GNUNET_PQ_QueryParam
256GNUNET_PQ_query_param_array_uint32 (
257 unsigned int num,
258 const uint32_t *elements,
259 struct GNUNET_PQ_Context *db);
260
261/**
262 * Generate query parameter for an array of uint64 in host byte order.
263 * Note that the (unsigend) elements are not checked to wrap over INT8_MAX
264 *
265 * @param num Number of elements in @a elements
266 * @param elements Continuous array of @a num uint64_t elements
267 * @param db Database context, needed for database-depending encoding of @a elements
268 * @return query parameter to use
269 */
270struct GNUNET_PQ_QueryParam
271GNUNET_PQ_query_param_array_uint64 (
272 unsigned int num,
273 const uint64_t *elements,
274 struct GNUNET_PQ_Context *db);
275
276/**
277 * Generate query parameter for an array of buffers @a elements, each of
278 * corresponding size given in @a sizes.
279 *
280 * @param num Number of elements in @a elements
281 * @param elements Continous array of @a num buffers, each of corresponding size given in @a sizes.
282 * @param sizes Pointer to sizes in bytes of each element in @a elements
283 * @param db Database context, needed for database-depending encoding of @a elements
284 * @return query parameter to use
285 */
286struct GNUNET_PQ_QueryParam
287GNUNET_PQ_query_param_array_bytes (
288 unsigned int num,
289 const void *elements,
290 const size_t *sizes,
291 struct GNUNET_PQ_Context *db);
292
293/**
294 * Generate query parameter for an array of buffers @a elements,
295 * each of the same size @a size.
296 *
297 * @param num Number of elements in @a elements
298 * @param elements Continous array of @a num buffers, each with the same size @a same_size
299 * @param same_size Size in bytes of each element in @a elements
300 * @param db Database context, needed for database-depending encoding of @a elements
301 * @return query parameter to use
302 */
303struct GNUNET_PQ_QueryParam
304GNUNET_PQ_query_param_array_bytes_same_size (
305 unsigned int num,
306 const void *elements,
307 size_t same_size,
308 struct GNUNET_PQ_Context *db);
309
310/**
311 * Generate array of equal-sized query parameter with size determined
312 * by variable type from a pointer to an continuous array.
313 *
314 * @param num Number of elements in @a elements
315 * @param elements Continuous array of the query parameter to pass.
316 * @param db Database context, needed for database-depending encoding of @a elements
317 * @return query parameter to use
318 */
319#define GNUNET_PQ_query_param_array_auto_from_type(num, elements, db) \
320 GNUNET_PQ_query_param_array_bytes_same_size ((num), \
321 (elements), \
322 sizeof(*(elements)), \
323 (db))
324
325/**
326 * Generate query parameter for an array of pointers to buffers @a elements,
327 * each of the same size @a size.
328 *
329 * @param num Number of elements in @a elements
330 * @param elements Array of @a num pointers to buffers, each with the same size @a same_size
331 * @param same_size Size in bytes of each element in @a elements
332 * @param db Database context, needed for database-depending encoding of @a elements
333 * @return query parameter to use
334 */
335struct GNUNET_PQ_QueryParam
336GNUNET_PQ_query_param_array_ptrs_bytes_same_size (
337 unsigned int num,
338 const void *elements[static num],
339 size_t same_size,
340 struct GNUNET_PQ_Context *db);
341
342
343/**
344 * Generate array of equal-sized query parameter with size determined by
345 * variable type from a pointer to an array of pointers to objects of the same
346 * type.
347 *
348 * @param num Number of elements in @a elements
349 * @param elements Continuous array of the query parameter to pass.
350 * @param db Database context, needed for database-depending encoding of @a elements
351 * @return query parameter to use
352 */
353#define GNUNET_PQ_query_param_array_ptrs_auto_from_type(num, elements, db) \
354 GNUNET_PQ_query_param_array_ptrs_bytes_same_size ((num), \
355 (const void **) (elements), \
356 sizeof(*(elements[0])), \
357 (db))
358
359
360/**
361 * Generate query parameter for an array of strings (continuous)
362 *
363 * @param num Number of elements in @a elements
364 * @param elements Array of @a num continuous strings (zero-terminated each)
365 * @param db Database context, needed for database-depending encoding of @a elements
366 * @return query parameter to use
367 */
368struct GNUNET_PQ_QueryParam
369GNUNET_PQ_query_param_array_string (
370 unsigned int num,
371 const char *elements,
372 struct GNUNET_PQ_Context *db);
373
374
375/**
376 * Generate query parameter for an array of strings (pointers)
377 *
378 * @param num Number of elements in @a elements
379 * @param elements Array of @a num pointer to strings
380 * @param db Database context, needed for database-depending encoding of @a elements
381 * @return query parameter to use
382 */
383struct GNUNET_PQ_QueryParam
384GNUNET_PQ_query_param_array_ptrs_string (
385 unsigned int num,
386 const char *elements[static num],
387 struct GNUNET_PQ_Context *db);
388
389
390/**
136 * Generate fixed-size query parameter with size determined 391 * Generate fixed-size query parameter with size determined
137 * by variable type. 392 * by variable type.
138 * 393 *
@@ -142,6 +397,83 @@ GNUNET_PQ_query_param_string (const char *ptr);
142#define GNUNET_PQ_query_param_auto_from_type(x) \ 397#define GNUNET_PQ_query_param_auto_from_type(x) \
143 GNUNET_PQ_query_param_fixed_size ((x), sizeof(*(x))) 398 GNUNET_PQ_query_param_fixed_size ((x), sizeof(*(x)))
144 399
400/**
401 * Generate query parameter for an array of absolute time stamps (continuous)
402 *
403 * @param num Number of elements in @a elements
404 * @param elements Array of @a num absolute timestamps
405 * @return query parameter to use
406 */
407struct GNUNET_PQ_QueryParam
408GNUNET_PQ_query_param_array_abs_time (
409 unsigned int num,
410 const struct GNUNET_TIME_Absolute *elements,
411 struct GNUNET_PQ_Context *db);
412
413/**
414 * Generate query parameter for an array of absolute time stamps (pointers)
415 *
416 * @param num Number of elements in @a elements
417 * @param elements Array of @a num pointers to absolute timestamps
418 * @return query parameter to use
419 */
420struct GNUNET_PQ_QueryParam
421GNUNET_PQ_query_param_array_ptrs_abs_time (
422 unsigned int num,
423 const struct GNUNET_TIME_Absolute *elements[],
424 struct GNUNET_PQ_Context *db);
425
426/**
427 * Generate query parameter for an array of relative time stamps (continuous)
428 *
429 * @param num Number of elements in @a elements
430 * @param elements Array of @a num relative timestamps
431 * @return query parameter to use
432 */
433struct GNUNET_PQ_QueryParam
434GNUNET_PQ_query_param_array_rel_time (
435 unsigned int num,
436 const struct GNUNET_TIME_Relative *elements,
437 struct GNUNET_PQ_Context *db);
438
439/**
440 * Generate query parameter for an array of relative time stamps (pointers)
441 *
442 * @param num Number of elements in @a elements
443 * @param elements Array of @a num pointers to relative timestamps
444 * @return query parameter to use
445 */
446struct GNUNET_PQ_QueryParam
447GNUNET_PQ_query_param_array_ptrs_rel_time (
448 unsigned int num,
449 const struct GNUNET_TIME_Relative *elements[],
450 struct GNUNET_PQ_Context *db);
451
452/**
453 * Generate query parameter for an array of time stamps (continuous)
454 *
455 * @param num Number of elements in @a elements
456 * @param elements Array of @a num timestamps
457 * @return query parameter to use
458 */
459struct GNUNET_PQ_QueryParam
460GNUNET_PQ_query_param_array_timestamp (
461 unsigned int num,
462 const struct GNUNET_TIME_Timestamp *elements,
463 struct GNUNET_PQ_Context *db);
464
465/**
466 * Generate query parameter for an array of time stamps (pointers)
467 *
468 * @param num Number of elements in @a elements
469 * @param elements Array of @a num pointers to relative timestamps
470 * @return query parameter to use
471 */
472struct GNUNET_PQ_QueryParam
473GNUNET_PQ_query_param_array_ptrs_timestamp (
474 unsigned int num,
475 const struct GNUNET_TIME_Timestamp *elements[],
476 struct GNUNET_PQ_Context *db);
145 477
146/** 478/**
147 * Generate query parameter for an RSA public key. The 479 * Generate query parameter for an RSA public key. The
@@ -190,6 +522,17 @@ GNUNET_PQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
190 522
191 523
192/** 524/**
525 * Generate query parameter for a timestamp.
526 * The database must store a 64-bit integer.
527 *
528 * @param x pointer to the query parameter to pass
529 * @return query parameter to use
530 */
531struct GNUNET_PQ_QueryParam
532GNUNET_PQ_query_param_timestamp (const struct GNUNET_TIME_Timestamp *x);
533
534
535/**
193 * Generate query parameter for an absolute time value. 536 * Generate query parameter for an absolute time value.
194 * The database must store a 64-bit integer. 537 * The database must store a 64-bit integer.
195 * 538 *
@@ -202,6 +545,18 @@ GNUNET_PQ_query_param_absolute_time_nbo (
202 545
203 546
204/** 547/**
548 * Generate query parameter for a timestamp in NBO.
549 * The database must store a 64-bit integer.
550 *
551 * @param x pointer to the query parameter to pass
552 * @return query parameter to use
553 */
554struct GNUNET_PQ_QueryParam
555GNUNET_PQ_query_param_timestamp_nbo (
556 const struct GNUNET_TIME_TimestampNBO *x);
557
558
559/**
205 * Generate query parameter for an uint16_t in host byte order. 560 * Generate query parameter for an uint16_t in host byte order.
206 * 561 *
207 * @param x pointer to the query parameter to pass 562 * @param x pointer to the query parameter to pass
@@ -222,7 +577,7 @@ GNUNET_PQ_query_param_uint32 (const uint32_t *x);
222 577
223 578
224/** 579/**
225 * Generate query parameter for an uint16_t in host byte order. 580 * Generate query parameter for an uint64_t in host byte order.
226 * 581 *
227 * @param x pointer to the query parameter to pass 582 * @param x pointer to the query parameter to pass
228 * @return query parameter to use 583 * @return query parameter to use
@@ -231,6 +586,16 @@ struct GNUNET_PQ_QueryParam
231GNUNET_PQ_query_param_uint64 (const uint64_t *x); 586GNUNET_PQ_query_param_uint64 (const uint64_t *x);
232 587
233 588
589/**
590 * Generate query parameter for an int64_t in host byte order.
591 *
592 * @param x pointer to the query parameter to pass
593 * @return query parameter to use
594 */
595struct GNUNET_PQ_QueryParam
596GNUNET_PQ_query_param_int64 (const int64_t *x);
597
598
234/* ************************* pq_result_helper.c functions ************************ */ 599/* ************************* pq_result_helper.c functions ************************ */
235 600
236 601
@@ -280,8 +645,7 @@ struct GNUNET_PQ_ResultSpec
280 GNUNET_PQ_ResultConverter conv; 645 GNUNET_PQ_ResultConverter conv;
281 646
282 /** 647 /**
283 * Function to clean up result data, NULL if cleanup is 648 * Function to clean up result data, NULL if cleanup is not necessary.
284 * not necessary.
285 */ 649 */
286 GNUNET_PQ_ResultCleanup cleaner; 650 GNUNET_PQ_ResultCleanup cleaner;
287 651
@@ -296,9 +660,9 @@ struct GNUNET_PQ_ResultSpec
296 void *dst; 660 void *dst;
297 661
298 /** 662 /**
299 * Allowed size for the data, 0 for variable-size 663 * Allowed size for the data, 0 for variable-size (in this case, the type of
300 * (in this case, the type of @e dst is a `void **` 664 * @e dst is a `void **` and we need to allocate a buffer of the right
301 * and we need to allocate a buffer of the right size). 665 * size).
302 */ 666 */
303 size_t dst_size; 667 size_t dst_size;
304 668
@@ -318,10 +682,8 @@ struct GNUNET_PQ_ResultSpec
318 bool is_nullable; 682 bool is_nullable;
319 683
320 /** 684 /**
321 * Points to a location where we should store 685 * Points to a location where we should store "true" if the result found is
322 * "true" if the result found is NULL, and 686 * NULL, and otherwise "false". Only used if @e is_nullable is true.
323 * otherwise "false". Only used if @e is_nullable
324 * is true.
325 */ 687 */
326 bool *is_null; 688 bool *is_null;
327 689
@@ -348,8 +710,7 @@ struct GNUNET_PQ_ResultSpec
348 710
349 711
350/** 712/**
351 * Allow NULL value to be found in the database 713 * Allow NULL value to be found in the database for the given value.
352 * for the given value.
353 * 714 *
354 * @param rs result spec entry to modify 715 * @param rs result spec entry to modify
355 * @param[out] is_null location set to 'true' if the 716 * @param[out] is_null location set to 'true' if the
@@ -414,6 +775,18 @@ GNUNET_PQ_result_spec_string (const char *name,
414 775
415 776
416/** 777/**
778 * boolean expected.
779 *
780 * @param name name of the field in the table
781 * @param[out] dst where to store the result
782 * @return array entry for the result specification to use
783 */
784struct GNUNET_PQ_ResultSpec
785GNUNET_PQ_result_spec_bool (const char *name,
786 bool *dst);
787
788
789/**
417 * RSA public key expected. 790 * RSA public key expected.
418 * 791 *
419 * @param name name of the field in the table 792 * @param name name of the field in the table
@@ -450,6 +823,18 @@ GNUNET_PQ_result_spec_absolute_time (const char *name,
450 823
451 824
452/** 825/**
826 * Timestamp expected.
827 *
828 * @param name name of the field in the table
829 * @param[out] t where to store the result
830 * @return array entry for the result specification to use
831 */
832struct GNUNET_PQ_ResultSpec
833GNUNET_PQ_result_spec_timestamp (const char *name,
834 struct GNUNET_TIME_Timestamp *t);
835
836
837/**
453 * Relative time expected. 838 * Relative time expected.
454 * 839 *
455 * @param name name of the field in the table 840 * @param name name of the field in the table
@@ -474,6 +859,18 @@ GNUNET_PQ_result_spec_absolute_time_nbo (const char *name,
474 859
475 860
476/** 861/**
862 * Timestamp expected.
863 *
864 * @param name name of the field in the table
865 * @param[out] tn where to store the result
866 * @return array entry for the result specification to use
867 */
868struct GNUNET_PQ_ResultSpec
869GNUNET_PQ_result_spec_timestamp_nbo (const char *name,
870 struct GNUNET_TIME_TimestampNBO *tn);
871
872
873/**
477 * uint16_t expected. 874 * uint16_t expected.
478 * 875 *
479 * @param name name of the field in the table 876 * @param name name of the field in the table
@@ -509,15 +906,207 @@ GNUNET_PQ_result_spec_uint64 (const char *name,
509 uint64_t *u64); 906 uint64_t *u64);
510 907
511 908
512/* ************************* pq.c functions ************************ */ 909/**
910 * int64_t expected.
911 *
912 * @param name name of the field in the table
913 * @param[out] i64 where to store the result
914 * @return array entry for the result specification to use
915 */
916struct GNUNET_PQ_ResultSpec
917GNUNET_PQ_result_spec_int64 (const char *name,
918 int64_t *i64);
919
513 920
514/** 921/**
515 * Postgres context. 922 * array of bool expected.
923 *
924 * @param db Database context, needed for OID lookup for the correct type
925 * @param name name of the field in the table
926 * @param[out] num where to store the number of elements in the array @a bools.
927 * @param[out] bools pointer to where to store the result, an array of @a num bool's. Allocated by the function, MUST be freed with GNUNET_free.
928 * @return array entry for the result specification to use
516 */ 929 */
517struct GNUNET_PQ_Context; 930struct GNUNET_PQ_ResultSpec
931GNUNET_PQ_result_spec_array_bool (
932 struct GNUNET_PQ_Context *db,
933 const char *name,
934 size_t *num,
935 bool **bools);
936
937/**
938 * array of uint16_t expected.
939 *
940 * @param db Database context, needed for OID lookup for the correct type
941 * @param name name of the field in the table
942 * @param[out] num where to store the number of elements in the array @a u16s.
943 * @param[out] dst pointer to where to store the an array of @a num uint16_t's. Allocated by the function, MUST be freed with GNUNET_free.
944 * @return array entry for the result specification to use
945 */
946struct GNUNET_PQ_ResultSpec
947GNUNET_PQ_result_spec_array_uint16 (
948 struct GNUNET_PQ_Context *db,
949 const char *name,
950 size_t *num,
951 uint16_t **dst);
952
953/**
954 * array of uint32_t expected.
955 *
956 * @param db Database context, needed for OID lookup for the correct type
957 * @param name name of the field in the table
958 * @param[out] num where to store the number of elements in the array @a u32s.
959 * @param[out] dst pointer to where to store the array of @a num uint32_t's. Allocated by the function, MUST be freed with GNUNET_free.
960 * @return array entry for the result specification to use
961 */
962struct GNUNET_PQ_ResultSpec
963GNUNET_PQ_result_spec_array_uint32 (
964 struct GNUNET_PQ_Context *db,
965 const char *name,
966 size_t *num,
967 uint32_t **dst);
968
969/**
970 * array of uint64_t expected.
971 *
972 * @param db Database context, needed for OID lookup for the correct type
973 * @param name name of the field in the table
974 * @param[out] num where to store the number of elements in the array @a u64s.
975 * @param[out] dst pointer to where to store the array of @a num uint64_t's. Allocated by the function, MUST be freed with GNUNET_free.
976 * @return array entry for the result specification to use
977 */
978struct GNUNET_PQ_ResultSpec
979GNUNET_PQ_result_spec_array_uint64 (
980 struct GNUNET_PQ_Context *db,
981 const char *name,
982 size_t *num,
983 uint64_t **dst);
518 984
519 985
520/** 986/**
987 * array of absolute time expected.
988 *
989 * @param db Database context, needed for OID lookup for the correct type
990 * @param name name of the field in the table
991 * @param[out] num where to store the number of elements in the array @a u64s.
992 * @param[out] dst pointer to where to store the array of @a num absolute time. Allocated by the function, MUST be freed with GNUNET_free.
993 * @return array entry for the result specification to use
994 */
995struct GNUNET_PQ_ResultSpec
996GNUNET_PQ_result_spec_array_abs_time (
997 struct GNUNET_PQ_Context *db,
998 const char *name,
999 size_t *num,
1000 struct GNUNET_TIME_Absolute **dst);
1001
1002/**
1003 * array of relative time expected.
1004 *
1005 * @param db Database context, needed for OID lookup for the correct type
1006 * @param name name of the field in the table
1007 * @param[out] num where to store the number of elements in the array @a u64s.
1008 * @param[out] dst pointer to where to store the array of @a num relate time. Allocated by the function, MUST be freed with GNUNET_free.
1009 * @return array entry for the result specification to use
1010 */
1011struct GNUNET_PQ_ResultSpec
1012GNUNET_PQ_result_spec_array_rel_time (
1013 struct GNUNET_PQ_Context *db,
1014 const char *name,
1015 size_t *num,
1016 struct GNUNET_TIME_Relative **dst);
1017
1018/**
1019 * array of relative time expected.
1020 *
1021 * @param db Database context, needed for OID lookup for the correct type
1022 * @param name name of the field in the table
1023 * @param[out] num where to store the number of elements in the array @a u64s.
1024 * @param[out] dst pointer to where to store the array of @a num timestamps. Allocated by the function, MUST be freed with GNUNET_free.
1025 * @return array entry for the result specification to use
1026 */
1027
1028struct GNUNET_PQ_ResultSpec
1029GNUNET_PQ_result_spec_array_timestamp (
1030 struct GNUNET_PQ_Context *db,
1031 const char *name,
1032 size_t *num,
1033 struct GNUNET_TIME_Timestamp **dst);
1034
1035/**
1036 * Array of variable-size result expected.
1037 *
1038 * @param db Database context, needed for OID lookup for the correct type
1039 * @param name name of the field in the table
1040 * @param[out] num where to store the number of elements
1041 * @param[out] sizes where to store the @a num size's of byte-buffers in @a dst
1042 * @param[out] dst where to store the continuous array of @a num byte-buffers , allocated
1043 * @return array entry for the result specification to use
1044 */
1045struct GNUNET_PQ_ResultSpec
1046GNUNET_PQ_result_spec_array_variable_size (
1047 struct GNUNET_PQ_Context *db,
1048 const char *name,
1049 size_t *num,
1050 size_t **sizes,
1051 void **dst);
1052
1053
1054/**
1055 * Array of fixed-size result expected.
1056 *
1057 * @param db Database context, needed for OID lookup for the correct type
1058 * @param name name of the field in the table
1059 * @param size number of bytes expected in each element of @a dst
1060 * @param[out] num where to store the number of elements
1061 * @param[out] dst where to store the results, an continuous array of fixed-size elements
1062 * @return array entry for the result specification to use
1063 */
1064struct GNUNET_PQ_ResultSpec
1065GNUNET_PQ_result_spec_array_fixed_size (
1066 struct GNUNET_PQ_Context *db,
1067 const char *name,
1068 size_t size,
1069 size_t *num,
1070 void **dst);
1071
1072
1073/**
1074 * We expect a fixed-size result, with size determined by the type of `* dst`
1075 *
1076 * @param db Database context, needed for OID lookup for the correct type
1077 * @param name name of the field in the table
1078 * @param num pointer to where to store the number of elements
1079 * @param dst pointer to where to store the results, type fits expected result size
1080 * @return array entry for the result specification to use
1081 */
1082#define GNUNET_PQ_result_spec_auto_array_from_type(db, name, num, dst) \
1083 GNUNET_PQ_result_spec_array_fixed_size ( \
1084 (db), \
1085 (name), \
1086 sizeof(*(dst)), \
1087 (num), \
1088 (void *) &(dst))
1089
1090
1091/**
1092 * Array of 0-terminated strings expected.
1093 *
1094 * @param db Database context, needed for OID lookup for the correct type
1095 * @param name name of the field in the table
1096 * @param[out] num where to store the number of elements
1097 * @param[out] dst where to store the allocated continous array of @a num 0-terminated strings
1098 * @return array entry for the result specification to use
1099 */
1100struct GNUNET_PQ_ResultSpec
1101GNUNET_PQ_result_spec_array_string (
1102 struct GNUNET_PQ_Context *db,
1103 const char *name,
1104 size_t *num,
1105 char **dst);
1106
1107/* ************************* pq.c functions ************************ */
1108
1109/**
521 * Execute a prepared statement. 1110 * Execute a prepared statement.
522 * 1111 *
523 * @param db database context 1112 * @param db database context
@@ -681,11 +1270,6 @@ struct GNUNET_PQ_PreparedStatement
681 */ 1270 */
682 const char *sql; 1271 const char *sql;
683 1272
684 /**
685 * Number of arguments included in @e sql.
686 */
687 unsigned int num_arguments;
688
689}; 1273};
690 1274
691 1275
@@ -694,7 +1278,7 @@ struct GNUNET_PQ_PreparedStatement
694 */ 1278 */
695#define GNUNET_PQ_PREPARED_STATEMENT_END \ 1279#define GNUNET_PQ_PREPARED_STATEMENT_END \
696 { \ 1280 { \
697 NULL, NULL, 0 \ 1281 NULL, NULL \
698 } 1282 }
699 1283
700 1284
@@ -703,13 +1287,11 @@ struct GNUNET_PQ_PreparedStatement
703 * 1287 *
704 * @param name name of the statement 1288 * @param name name of the statement
705 * @param sql actual SQL statement 1289 * @param sql actual SQL statement
706 * @param num_args number of arguments in the statement
707 * @return initialized struct 1290 * @return initialized struct
708 */ 1291 */
709struct GNUNET_PQ_PreparedStatement 1292struct GNUNET_PQ_PreparedStatement
710GNUNET_PQ_make_prepare (const char *name, 1293GNUNET_PQ_make_prepare (const char *name,
711 const char *sql, 1294 const char *sql);
712 unsigned int num_args);
713 1295
714 1296
715/** 1297/**
@@ -726,6 +1308,22 @@ GNUNET_PQ_prepare_statements (struct GNUNET_PQ_Context *db,
726 const struct GNUNET_PQ_PreparedStatement *ps); 1308 const struct GNUNET_PQ_PreparedStatement *ps);
727 1309
728 1310
1311/**
1312 * Request creation of prepared statements @a ps from Postgres, but do not
1313 * automatically re-prepare the statement if we are disconnected from the
1314 * database.
1315 *
1316 * @param db database to prepare the statements for
1317 * @param ps #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared
1318 * statements.
1319 * @return #GNUNET_OK on success,
1320 * #GNUNET_SYSERR on error
1321 */
1322enum GNUNET_GenericReturnValue
1323GNUNET_PQ_prepare_once (struct GNUNET_PQ_Context *db,
1324 const struct GNUNET_PQ_PreparedStatement *ps);
1325
1326
729/* ******************** pq_exec.c functions ************** */ 1327/* ******************** pq_exec.c functions ************** */
730 1328
731 1329
@@ -780,7 +1378,7 @@ GNUNET_PQ_make_try_execute (const char *sql);
780/** 1378/**
781 * Request execution of an array of statements @a es from Postgres. 1379 * Request execution of an array of statements @a es from Postgres.
782 * 1380 *
783 * @param pq database to execute the statements in 1381 * @param db database to execute the statements in
784 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared 1382 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared
785 * statements. 1383 * statements.
786 * @return #GNUNET_OK on success (modulo statements where errors can be ignored) 1384 * @return #GNUNET_OK on success (modulo statements where errors can be ignored)
@@ -822,14 +1420,14 @@ enum GNUNET_PQ_Options
822 * configuration. Initialize logging via GNUnet's log routines and disable 1420 * configuration. Initialize logging via GNUnet's log routines and disable
823 * Postgres's logger. Also ensures that the statements in @a load_path and @a 1421 * Postgres's logger. Also ensures that the statements in @a load_path and @a
824 * es are executed whenever we (re)connect to the database, and that the 1422 * es are executed whenever we (re)connect to the database, and that the
825 * prepared statements in @a ps are "ready". If statements in @es fail that 1423 * prepared statements in @a ps are "ready". If statements in @a es fail that
826 * were created with #GNUNET_PQ_make_execute(), then the entire operation 1424 * were created with #GNUNET_PQ_make_execute(), then the entire operation
827 * fails. 1425 * fails.
828 * 1426 *
829 * In @a load_path, a list of "$XXXX.sql" files is expected where $XXXX 1427 * In @a load_path, a list of "$XXXX.sql" files is expected where $XXXX
830 * must be a sequence of contiguous integer values starting at 0000. 1428 * must be a sequence of contiguous integer values starting at 0000.
831 * These files are then loaded in sequence using "psql $config_str" before 1429 * These files are then loaded in sequence using "psql $config_str" before
832 * running statements from @e es. The directory is inspected again on 1430 * running statements from @a es. The directory is inspected again on
833 * reconnect. 1431 * reconnect.
834 * 1432 *
835 * @param config_str configuration to use 1433 * @param config_str configuration to use
@@ -847,11 +1445,26 @@ GNUNET_PQ_connect (const char *config_str,
847 1445
848 1446
849/** 1447/**
1448 * Execute SQL statements from @a buf against @a db.
1449 * The given filename infix in @a buf is prefixed with
1450 * the "load_path" and ".sql" is appended to construct
1451 * the full filename.
1452 *
1453 * @param db database context to use
1454 * @param buf filename infix (!) with the SQL code to run
1455 * @return #GNUNET_OK on success, #GNUNET_NO if patch @a buf does not exist, #GNUNET_SYSERR on error
1456 */
1457enum GNUNET_GenericReturnValue
1458GNUNET_PQ_exec_sql (struct GNUNET_PQ_Context *db,
1459 const char *buf);
1460
1461
1462/**
850 * Create a connection to the Postgres database using @a config_str for the 1463 * Create a connection to the Postgres database using @a config_str for the
851 * configuration. Initialize logging via GNUnet's log routines and disable 1464 * configuration. Initialize logging via GNUnet's log routines and disable
852 * Postgres's logger. Also ensures that the statements in @a load_path and @a 1465 * Postgres's logger. Also ensures that the statements in @a load_path and @a
853 * es are executed whenever we (re)connect to the database, and that the 1466 * es are executed whenever we (re)connect to the database, and that the
854 * prepared statements in @a ps are "ready". If statements in @es fail that 1467 * prepared statements in @a ps are "ready". If statements in @a es fail that
855 * were created with #GNUNET_PQ_make_execute(), then the entire operation 1468 * were created with #GNUNET_PQ_make_execute(), then the entire operation
856 * fails. 1469 * fails.
857 * 1470 *
@@ -863,6 +1476,7 @@ GNUNET_PQ_connect (const char *config_str,
863 * 1476 *
864 * @param config_str configuration to use 1477 * @param config_str configuration to use
865 * @param load_path path to directory with SQL transactions to run, can be NULL 1478 * @param load_path path to directory with SQL transactions to run, can be NULL
1479 * @param auto_suffix infix of SQL series to run on every reconnect; runs multiple (!) files, of the form auto_suffix-XXXX where XXXX is from 0 to 9999 (consequtive).
866 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated 1480 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated
867 * array of statements to execute upon EACH connection, can be NULL 1481 * array of statements to execute upon EACH connection, can be NULL
868 * @param ps array of prepared statements to prepare, can be NULL 1482 * @param ps array of prepared statements to prepare, can be NULL
@@ -872,16 +1486,17 @@ GNUNET_PQ_connect (const char *config_str,
872struct GNUNET_PQ_Context * 1486struct GNUNET_PQ_Context *
873GNUNET_PQ_connect2 (const char *config_str, 1487GNUNET_PQ_connect2 (const char *config_str,
874 const char *load_path, 1488 const char *load_path,
1489 const char *auto_suffix,
875 const struct GNUNET_PQ_ExecuteStatement *es, 1490 const struct GNUNET_PQ_ExecuteStatement *es,
876 const struct GNUNET_PQ_PreparedStatement *ps, 1491 const struct GNUNET_PQ_PreparedStatement *ps,
877 enum GNUNET_PQ_Options flags); 1492 enum GNUNET_PQ_Options flags);
878 1493
879 1494
880/** 1495/**
881 * Connect to a postgres database using the configuration 1496 * Connect to a postgres database using the configuration option "CONFIG" in
882 * option "CONFIG" in @a section. Also ensures that the 1497 * @a section. Also ensures that the statements in @a es are executed
883 * statements in @a es are executed whenever we (re)connect to the 1498 * whenever we (re)connect to the database, and that the prepared statements
884 * database, and that the prepared statements in @a ps are "ready". 1499 * in @a ps are "ready".
885 * 1500 *
886 * The caller does not have to ensure that @a es and @a ps remain allocated 1501 * The caller does not have to ensure that @a es and @a ps remain allocated
887 * and initialized in memory until #GNUNET_PQ_disconnect() is called, as a copy will be made. 1502 * and initialized in memory until #GNUNET_PQ_disconnect() is called, as a copy will be made.
@@ -909,7 +1524,8 @@ GNUNET_PQ_connect_with_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg,
909 * database, and that the prepared statements in @a ps are "ready". 1524 * database, and that the prepared statements in @a ps are "ready".
910 * 1525 *
911 * The caller does not have to ensure that @a es and @a ps remain allocated 1526 * The caller does not have to ensure that @a es and @a ps remain allocated
912 * and initialized in memory until #GNUNET_PQ_disconnect() is called, as a copy will be made. 1527 * and initialized in memory until #GNUNET_PQ_disconnect() is called, as a
1528 * copy will be made.
913 * 1529 *
914 * @param cfg configuration 1530 * @param cfg configuration
915 * @param section configuration section to use to get Postgres configuration options 1531 * @param section configuration section to use to get Postgres configuration options
@@ -988,12 +1604,24 @@ GNUNET_PQ_event_listen_cancel (struct GNUNET_DB_EventHandler *eh);
988 1604
989 1605
990/** 1606/**
1607 * Poll for events right now. Useful if we may have
1608 * triggered an event for ourselves. Not needed when
1609 * using GNUNET_PQ_event_notify(), but useful when
1610 * stored procedures may have triggered events.
1611 * Does nothing if there are no events.
1612 *
1613 * @param[in,out] db database to check for events
1614 */
1615void
1616GNUNET_PQ_event_do_poll (struct GNUNET_PQ_Context *db);
1617
1618
1619/**
991 * Notify all that listen on @a es of an event. 1620 * Notify all that listen on @a es of an event.
992 * 1621 *
993 * Unlike many other calls, this function is thread-safe 1622 * Unlike many other calls, this function is thread-safe and may be called
994 * and may be called from threads that are different 1623 * from threads that are different from the one that setup @a db. However, the
995 * from the one that setup @a db. However, the @a cb 1624 * @a cb will always be called from the thread that runs
996 * will always be called from the thread that runs
997 * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler. 1625 * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
998 * 1626 *
999 * @param db database context to use 1627 * @param db database context to use
@@ -1009,6 +1637,17 @@ GNUNET_PQ_event_notify (struct GNUNET_PQ_Context *db,
1009 1637
1010 1638
1011/** 1639/**
1640 * Compute the channel that one should notify upon for the given event
1641 * specification.
1642 *
1643 * @param es event specification
1644 * @return channel to notify upon
1645 */
1646char *
1647GNUNET_PQ_get_event_notify_channel (const struct GNUNET_DB_EventHeaderP *es);
1648
1649
1650/**
1012 * Within the @a db context, run all the SQL files 1651 * Within the @a db context, run all the SQL files
1013 * from the @a load_path from 0000-9999.sql (as long 1652 * from the @a load_path from 0000-9999.sql (as long
1014 * as the files exist contiguously). 1653 * as the files exist contiguously).