GNUnet  0.11.x
gnunet_pq_lib.h
Go to the documentation of this file.
1 /*
2  This file is part of GNUnet
3  Copyright (C) 2016, 2017, 2020, 2021 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  */
25 #ifndef GNUNET_PQ_LIB_H
26 #define GNUNET_PQ_LIB_H
27 
28 #include <libpq-fe.h>
29 #include "gnunet_util_lib.h"
30 #include "gnunet_db_lib.h"
31 
32 /* ************************* pq_query_helper.c functions ************************ */
33 
34 
49 typedef int
51  const void *data,
52  size_t data_len,
53  void *param_values[],
54  int param_lengths[],
55  int param_formats[],
56  unsigned int param_length,
57  void *scratch[],
58  unsigned int scratch_length);
59 
60 
65 {
70 
74  void *conv_cls;
75 
79  const void *data;
80 
84  size_t size;
85 
89  unsigned int num_params;
90 
91 };
92 
93 
97 #define GNUNET_PQ_query_param_end \
98  { \
99  NULL, NULL, NULL, 0, 0 \
100  }
101 
102 
110 
111 
121 GNUNET_PQ_query_param_fixed_size (const void *ptr,
122  size_t ptr_size);
123 
124 
132 GNUNET_PQ_query_param_string (const char *ptr);
133 
134 
142 #define GNUNET_PQ_query_param_auto_from_type(x) \
143  GNUNET_PQ_query_param_fixed_size ((x), sizeof(*(x)))
144 
145 
155  const struct GNUNET_CRYPTO_RsaPublicKey *x);
156 
157 
167  const struct GNUNET_CRYPTO_RsaSignature *x);
168 
169 
179 
180 
190 
191 
201  const struct GNUNET_TIME_AbsoluteNBO *x);
202 
203 
211 GNUNET_PQ_query_param_uint16 (const uint16_t *x);
212 
213 
221 GNUNET_PQ_query_param_uint32 (const uint32_t *x);
222 
223 
231 GNUNET_PQ_query_param_uint64 (const uint64_t *x);
232 
233 
234 /* ************************* pq_result_helper.c functions ************************ */
235 
236 
251 typedef enum GNUNET_GenericReturnValue
253  PGresult *result,
254  int row,
255  const char *fname,
256  size_t *dst_size,
257  void *dst);
258 
259 
267 typedef void
269  void *rd);
270 
271 
276 {
281 
287 
291  void *cls;
292 
296  void *dst;
297 
303  size_t dst_size;
304 
308  const char *fname;
309 
313  size_t *result_size;
314 
319 
326  bool *is_null;
327 
328 };
329 
330 
336 #define GNUNET_PQ_result_spec_end \
337  { \
338  NULL, NULL, NULL, NULL, 0, NULL, NULL \
339  }
340 
341 
354  bool *is_null);
355 
356 
367  void **dst,
368  size_t *sptr);
369 
370 
380 GNUNET_PQ_result_spec_fixed_size (const char *name, void *dst, size_t dst_size);
381 
382 
390 #define GNUNET_PQ_result_spec_auto_from_type(name, dst) \
391  GNUNET_PQ_result_spec_fixed_size (name, (dst), sizeof(*(dst)))
392 
393 
402 GNUNET_PQ_result_spec_string (const char *name, char **dst);
403 
404 
414  struct GNUNET_CRYPTO_RsaPublicKey **rsa);
415 
416 
426  struct GNUNET_CRYPTO_RsaSignature **sig);
427 
428 
438  struct GNUNET_TIME_Absolute *at);
439 
440 
450  struct GNUNET_TIME_Relative *rt);
451 
452 
462  struct GNUNET_TIME_AbsoluteNBO *at);
463 
464 
473 GNUNET_PQ_result_spec_uint16 (const char *name, uint16_t *u16);
474 
475 
484 GNUNET_PQ_result_spec_uint32 (const char *name, uint32_t *u32);
485 
486 
495 GNUNET_PQ_result_spec_uint64 (const char *name, uint64_t *u64);
496 
497 
498 /* ************************* pq.c functions ************************ */
499 
503 struct GNUNET_PQ_Context;
504 
505 
515 PGresult *
517  const char *name,
518  const struct GNUNET_PQ_QueryParam *params);
519 
520 
532 GNUNET_PQ_extract_result (PGresult *result,
533  struct GNUNET_PQ_ResultSpec *rs,
534  int row);
535 
536 
543 void
545 
546 
547 /* ******************** pq_eval.c functions ************** */
548 
549 
565  const char *statement_name,
566  PGresult *result);
567 
568 
587  const char *statement_name,
588  const struct GNUNET_PQ_QueryParam *params);
589 
590 
599 typedef void
601  PGresult *result,
602  unsigned int num_results);
603 
604 
622  const char *statement_name,
623  const struct GNUNET_PQ_QueryParam *params,
625  void *rh_cls);
626 
627 
645  const char *statement_name,
646  const struct
647  GNUNET_PQ_QueryParam *params,
648  struct GNUNET_PQ_ResultSpec *rs);
649 
650 
651 /* ******************** pq_prepare.c functions ************** */
652 
653 
659 {
663  const char *name;
664 
668  const char *sql;
669 
673  unsigned int num_arguments;
674 
675 };
676 
677 
681 #define GNUNET_PQ_PREPARED_STATEMENT_END \
682  { \
683  NULL, NULL, 0 \
684  }
685 
686 
696 GNUNET_PQ_make_prepare (const char *name,
697  const char *sql,
698  unsigned int num_args);
699 
700 
710 int
712  const struct GNUNET_PQ_PreparedStatement *ps);
713 
714 
715 /* ******************** pq_exec.c functions ************** */
716 
717 
723 {
727  const char *sql;
728 
733 };
734 
735 
739 #define GNUNET_PQ_EXECUTE_STATEMENT_END \
740  { \
741  NULL, GNUNET_SYSERR \
742  }
743 
744 
752 GNUNET_PQ_make_execute (const char *sql);
753 
754 
763 GNUNET_PQ_make_try_execute (const char *sql);
764 
765 
775 int
777  const struct GNUNET_PQ_ExecuteStatement *es);
778 
779 
780 /* ******************** pq_connect.c functions ************** */
781 
782 
805 struct GNUNET_PQ_Context *
806 GNUNET_PQ_connect (const char *config_str,
807  const char *load_path,
808  const struct GNUNET_PQ_ExecuteStatement *es,
809  const struct GNUNET_PQ_PreparedStatement *ps);
810 
811 
829 struct GNUNET_PQ_Context *
831  const char *section,
832  const char *load_path_suffix,
833  const struct GNUNET_PQ_ExecuteStatement *es,
834  const struct GNUNET_PQ_PreparedStatement *ps);
835 
836 
842 void
844 
845 
851 void
853 
854 
862 typedef void
864  int fd);
865 
866 
876 void
879  void *sc_cls);
880 
881 
891 void
893 
894 
900 void
902 
903 
909 void
911 
912 
917 
925 typedef void
927  const void *extra,
928  size_t extra_size);
929 
931 
932 
938 {
943  uint16_t size GNUNET_PACKED;
944 
948  uint16_t type GNUNET_PACKED;
949 
950 };
951 
953 
954 
959 
976 struct GNUNET_PQ_EventHandler *
978  const struct GNUNET_PQ_EventHeaderP *es,
980  void *cb_cls);
981 
982 
994 void
996 
997 
1012 void
1014  const struct GNUNET_PQ_EventHeaderP *es,
1015  const void *extra,
1016  size_t extra_size);
1017 
1018 
1030  const char *load_path);
1031 
1032 
1039 void
1041 
1042 
1043 #endif /* GNUNET_PQ_LIB_H_ */
1044 
1045 /* end of include/gnunet_pq_lib.h */
void(* GNUNET_PQ_SocketCallback)(void *cls, int fd)
Function called whenever the socket needed for notifications from postgres changes.
GNUNET_PQ_EventCallback cb
Function to call on events.
Definition: pq_event.c:43
void GNUNET_PQ_disconnect(struct GNUNET_PQ_Context *db)
Disconnect from the database, destroying the prepared statements and releasing other associated resou...
Definition: pq_connect.c:469
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_result(struct GNUNET_PQ_Context *db, const char *statement_name, PGresult *result)
Check the result&#39;s error code to see what happened.
Definition: pq_eval.c:59
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_absolute_time_nbo(const struct GNUNET_TIME_AbsoluteNBO *x)
Generate query parameter for an absolute time value.
static const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration we are using.
Definition: gnunet-abd.c:36
an RSA signature
Definition: crypto_rsa.c:63
struct GNUNET_PQ_PreparedStatement * ps
Prepared statements.
Definition: pq.h:49
int(* GNUNET_PQ_QueryConverter)(void *cls, const void *data, size_t data_len, void *param_values[], int param_lengths[], int param_formats[], unsigned int param_length, void *scratch[], unsigned int scratch_length)
Function called to convert input argument into SQL parameters.
Definition: gnunet_pq_lib.h:50
struct GNUNET_PQ_ExecuteStatement GNUNET_PQ_make_execute(const char *sql)
Create a struct GNUNET_PQ_ExecuteStatement where errors are fatal.
Definition: pq_exec.c:36
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_string(const char *ptr)
Generate query parameter for a string.
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_multi_select(struct GNUNET_PQ_Context *db, const char *statement_name, const struct GNUNET_PQ_QueryParam *params, GNUNET_PQ_PostgresResultHandler rh, void *rh_cls)
Execute a named prepared statement that is a SELECT statement which may return multiple results in co...
Definition: pq_eval.c:209
GNUNET_PQ_QueryConverter conv
Function for how to handle this type of entry.
Definition: gnunet_pq_lib.h:69
char * load_path
Path to load SQL files from.
Definition: pq.h:59
Information needed to run a list of SQL statements using GNUNET_PQ_exec_statements().
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_uint16(const uint16_t *x)
Generate query parameter for an uint16_t in host byte order.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_rsa_public_key(const char *name, struct GNUNET_CRYPTO_RsaPublicKey **rsa)
RSA public key expected.
Information needed to prepare a list of SQL statements using GNUNET_PQ_prepare_statements().
struct GNUNET_PQ_ExecuteStatement * es
Statements to execute upon connection.
Definition: pq.h:44
void GNUNET_PQ_reconnect(struct GNUNET_PQ_Context *db)
Reinitialize the database db.
Definition: pq_connect.c:295
const char * fname
Field name of the desired result.
Description of a DB result cell.
GNUNET_GenericReturnValue
Named constants for return values.
Definition: gnunet_common.h:83
int GNUNET_PQ_prepare_statements(struct GNUNET_PQ_Context *db, const struct GNUNET_PQ_PreparedStatement *ps)
Request creation of prepared statements ps from Postgres.
Definition: pq_prepare.c:62
PGresult * GNUNET_PQ_exec_prepared(struct GNUNET_PQ_Context *db, const char *name, const struct GNUNET_PQ_QueryParam *params)
Execute a prepared statement.
Definition: pq.c:32
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_absolute_time(const struct GNUNET_TIME_Absolute *x)
Generate query parameter for an absolute time value.
int ignore_errors
Should we ignore errors?
bool is_nullable
True if NULL is allowed for a value in the database.
const char * name
Name of the statement.
void GNUNET_PQ_event_listen_cancel(struct GNUNET_PQ_EventHandler *eh)
Stop notifications.
Definition: pq_event.c:446
const void * data
Data or NULL.
Definition: gnunet_pq_lib.h:79
void(* GNUNET_PQ_EventCallback)(void *cls, const void *extra, size_t extra_size)
Function called on events received from Postgres.
Time for absolute time used by GNUnet, in microseconds and in network byte order. ...
enum GNUNET_GenericReturnValue(* GNUNET_PQ_ResultConverter)(void *cls, PGresult *result, int row, const char *fname, size_t *dst_size, void *dst)
Extract data from a Postgres database result at row row.
The public information of an RSA key pair.
Definition: crypto_rsa.c:51
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_relative_time(const struct GNUNET_TIME_Relative *x)
Generate query parameter for a relative time value.
#define GNUNET_NETWORK_STRUCT_BEGIN
Define as empty, GNUNET_PACKED should suffice, but this won&#39;t work on W32.
static char * section
Name of the section.
Definition: gnunet-config.c:33
struct GNUNET_PQ_Context * GNUNET_PQ_connect(const char *config_str, const char *load_path, const struct GNUNET_PQ_ExecuteStatement *es, const struct GNUNET_PQ_PreparedStatement *ps)
Create a connection to the Postgres database using config_str for the configuration.
Definition: pq_connect.c:68
void * cls
Closure for conv and cleaner.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_string(const char *name, char **dst)
0-terminated string expected.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_variable_size(const char *name, void **dst, size_t *sptr)
Variable-size result expected.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint32(const char *name, uint32_t *u32)
uint32_t expected.
void * cb_cls
Closure for cb.
Definition: pq_event.c:48
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_singleton_select(struct GNUNET_PQ_Context *db, const char *statement_name, const struct GNUNET_PQ_QueryParam *params, struct GNUNET_PQ_ResultSpec *rs)
Execute a named prepared statement that is a SELECT statement which must return a single result in co...
Definition: pq_eval.c:258
shared definitions for transactional databases
int GNUNET_PQ_exec_statements(struct GNUNET_PQ_Context *db, const struct GNUNET_PQ_ExecuteStatement *es)
Request execution of an array of statements es from Postgres.
Definition: pq_exec.c:76
char * config_str
Configuration to use to connect to the DB.
Definition: pq.h:54
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_absolute_time(const char *name, struct GNUNET_TIME_Absolute *at)
Absolute time expected.
Header of a structure that describes an event channel we may subscribe to or notify on...
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_fixed_size(const char *name, void *dst, size_t dst_size)
Fixed-size result expected.
void * conv_cls
Closure for conv.
Definition: gnunet_pq_lib.h:74
static int result
Global testing status.
size_t dst_size
Allowed size for the data, 0 for variable-size (in this case, the type of dst is a void ** and we nee...
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_uint32(const uint32_t *x)
Generate query parameter for an uint32_t in host byte order.
const char * sql
Actual SQL statement.
void * sc_cls
Closure for sc.
Definition: pq.h:69
enum GNUNET_GenericReturnValue GNUNET_PQ_extract_result(PGresult *result, struct GNUNET_PQ_ResultSpec *rs, int row)
Extract results from a query result according to the given specification.
Definition: pq.c:127
struct GNUNET_PQ_Context * GNUNET_PQ_connect_with_cfg(const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, const char *load_path_suffix, const struct GNUNET_PQ_ExecuteStatement *es, const struct GNUNET_PQ_PreparedStatement *ps)
Connect to a postgres database using the configuration option "CONFIG" in section.
Definition: pq_connect.c:428
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_relative_time(const char *name, struct GNUNET_TIME_Relative *rt)
Relative time expected.
bool * is_null
Points to a location where we should store "true" if the result found is NULL, and otherwise "false"...
GNUNET_PQ_ResultCleanup cleaner
Function to clean up result data, NULL if cleanup is not necessary.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_rsa_signature(const struct GNUNET_CRYPTO_RsaSignature *x)
Generate query parameter for an RSA signature.
static struct GNUNET_FS_SearchContext * sc
Definition: gnunet-search.c:37
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_rsa_signature(const char *name, struct GNUNET_CRYPTO_RsaSignature **sig)
RSA signature expected.
unsigned int num_params
Number of parameters eaten by this operation.
Definition: gnunet_pq_lib.h:89
void GNUNET_PQ_reconnect_if_down(struct GNUNET_PQ_Context *db)
Reinitialize the database db if the connection is down.
Definition: pq_connect.c:283
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint16(const char *name, uint16_t *u16)
uint16_t expected.
void GNUNET_PQ_event_scheduler_stop(struct GNUNET_PQ_Context *db)
Stop running poll event loop using the GNUnet scheduler.
Definition: pq_event.c:321
void GNUNET_PQ_event_notify(struct GNUNET_PQ_Context *db, const struct GNUNET_PQ_EventHeaderP *es, const void *extra, size_t extra_size)
Notify all that listen on es of an event.
Definition: pq_event.c:473
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_non_select(struct GNUNET_PQ_Context *db, const char *statement_name, const struct GNUNET_PQ_QueryParam *params)
Execute a named prepared statement that is NOT a SELECT statement in connection using the given param...
Definition: pq_eval.c:164
#define GNUNET_NETWORK_STRUCT_END
Define as empty, GNUNET_PACKED should suffice, but this won&#39;t work on W32;.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_allow_null(struct GNUNET_PQ_ResultSpec rs, bool *is_null)
Allow NULL value to be found in the database for the given value.
static struct GNUNET_FS_DirectoryBuilder * db
Definition: gnunet-search.c:41
#define GNUNET_PACKED
gcc-ism to get packed structs.
configuration data
Definition: configuration.c:84
Handle for an active LISTENer to the database.
Definition: pq_event.c:33
const char * name
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_uint64(const uint64_t *x)
Generate query parameter for an uint16_t in host byte order.
void GNUNET_PQ_event_scheduler_start(struct GNUNET_PQ_Context *db)
Run poll event loop using the GNUnet scheduler.
Definition: pq_event.c:305
Description of a DB query parameter.
Definition: gnunet_pq_lib.h:64
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_fixed_size(const void *ptr, size_t ptr_size)
Generate query parameter for a buffer ptr of ptr_size bytes.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_absolute_time_nbo(const char *name, struct GNUNET_TIME_AbsoluteNBO *at)
Absolute time expected.
unsigned int num_arguments
Number of arguments included in sql.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_null(void)
Generate query parameter to create a NULL value.
enum GNUNET_TESTBED_UnderlayLinkModelType type
the type of this model
void(* GNUNET_PQ_PostgresResultHandler)(void *cls, PGresult *result, unsigned int num_results)
Function to be called with the results of a SELECT statement that has returned num_results results...
Time for absolute times used by GNUnet, in microseconds.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_rsa_public_key(const struct GNUNET_CRYPTO_RsaPublicKey *x)
Generate query parameter for an RSA public key.
GNUNET_DB_QueryStatus
Status code returned from functions running database commands.
Definition: gnunet_db_lib.h:34
void * dst
Destination for the data.
struct GNUNET_PQ_ExecuteStatement GNUNET_PQ_make_try_execute(const char *sql)
Create a struct GNUNET_PQ_ExecuteStatement where errors should be tolerated.
Definition: pq_exec.c:55
size_t size
Size of data.
Definition: gnunet_pq_lib.h:84
void(* GNUNET_PQ_ResultCleanup)(void *cls, void *rd)
Function called to clean up memory allocated by a GNUNET_PQ_ResultConverter.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint64(const char *name, uint64_t *u64)
uint64_t expected.
size_t * result_size
Where to store actual size of the result.
GNUNET_PQ_ResultConverter conv
What is the format of the result?
enum GNUNET_GenericReturnValue GNUNET_PQ_run_sql(struct GNUNET_PQ_Context *db, const char *load_path)
Within the db context, run all the SQL files from the load_path from 0000-9999.sql (as long as the fi...
Definition: pq_connect.c:188
uint32_t data
The data value.
struct GNUNET_PQ_EventHandler * GNUNET_PQ_event_listen(struct GNUNET_PQ_Context *db, const struct GNUNET_PQ_EventHeaderP *es, GNUNET_PQ_EventCallback cb, void *cb_cls)
Register callback to be invoked on events of type es.
Definition: pq_event.c:405
const char * sql
Actual SQL statement.
Handle to Postgres database.
Definition: pq.h:34
struct GNUNET_PQ_PreparedStatement GNUNET_PQ_make_prepare(const char *name, const char *sql, unsigned int num_args)
Create a struct GNUNET_PQ_PreparedStatement.
Definition: pq_prepare.c:38
void GNUNET_PQ_event_set_socket_callback(struct GNUNET_PQ_Context *db, GNUNET_PQ_SocketCallback sc, void *sc_cls)
Obtain the file descriptor to poll on for notifications.
Definition: pq_event.c:168
Time for relative time used by GNUnet, in microseconds.
void GNUNET_PQ_cleanup_result(struct GNUNET_PQ_ResultSpec *rs)
Free all memory that was allocated in rs during GNUNET_PQ_extract_result().
Definition: pq.c:117
void GNUNET_PQ_event_do_poll(struct GNUNET_PQ_Context *db)
Poll for database events now.
Definition: pq_event.c:191