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
50 (*GNUNET_PQ_QueryConverter) (void *cls,
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
252 (*GNUNET_PQ_ResultConverter)(void *cls,
253  PGresult *result,
254  int row,
255  const char *fname,
256  size_t *dst_size,
257  void *dst);
258 
259 
267 typedef void
268 (*GNUNET_PQ_ResultCleanup) (void *cls,
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 
474  uint16_t *u16);
475 
476 
486  uint32_t *u32);
487 
488 
498  uint64_t *u64);
499 
500 
501 /* ************************* pq.c functions ************************ */
502 
506 struct GNUNET_PQ_Context;
507 
508 
518 PGresult *
520  const char *name,
521  const struct GNUNET_PQ_QueryParam *params);
522 
523 
536  struct GNUNET_PQ_ResultSpec *rs,
537  int row);
538 
539 
546 void
548 
549 
550 /* ******************** pq_eval.c functions ************** */
551 
552 
568  const char *statement_name,
569  PGresult *result);
570 
571 
590  const char *statement_name,
591  const struct GNUNET_PQ_QueryParam *params);
592 
593 
602 typedef void
603 (*GNUNET_PQ_PostgresResultHandler) (void *cls,
604  PGresult *result,
605  unsigned int num_results);
606 
607 
625  const char *statement_name,
626  const struct GNUNET_PQ_QueryParam *params,
628  void *rh_cls);
629 
630 
648  struct GNUNET_PQ_Context *db,
649  const char *statement_name,
650  const struct GNUNET_PQ_QueryParam *params,
651  struct GNUNET_PQ_ResultSpec *rs);
652 
653 
654 /* ******************** pq_prepare.c functions ************** */
655 
656 
662 {
666  const char *name;
667 
671  const char *sql;
672 
676  unsigned int num_arguments;
677 
678 };
679 
680 
684 #define GNUNET_PQ_PREPARED_STATEMENT_END \
685  { \
686  NULL, NULL, 0 \
687  }
688 
689 
699 GNUNET_PQ_make_prepare (const char *name,
700  const char *sql,
701  unsigned int num_args);
702 
703 
713 int
715  const struct GNUNET_PQ_PreparedStatement *ps);
716 
717 
718 /* ******************** pq_exec.c functions ************** */
719 
720 
726 {
730  const char *sql;
731 
736 };
737 
738 
742 #define GNUNET_PQ_EXECUTE_STATEMENT_END \
743  { \
744  NULL, GNUNET_SYSERR \
745  }
746 
747 
755 GNUNET_PQ_make_execute (const char *sql);
756 
757 
766 GNUNET_PQ_make_try_execute (const char *sql);
767 
768 
780  const struct GNUNET_PQ_ExecuteStatement *es);
781 
782 
783 /* ******************** pq_connect.c functions ************** */
784 
785 
790 {
795 
801 
806 };
807 
808 
831 struct GNUNET_PQ_Context *
832 GNUNET_PQ_connect (const char *config_str,
833  const char *load_path,
834  const struct GNUNET_PQ_ExecuteStatement *es,
835  const struct GNUNET_PQ_PreparedStatement *ps);
836 
837 
861 struct GNUNET_PQ_Context *
862 GNUNET_PQ_connect2 (const char *config_str,
863  const char *load_path,
864  const struct GNUNET_PQ_ExecuteStatement *es,
865  const struct GNUNET_PQ_PreparedStatement *ps,
866  enum GNUNET_PQ_Options flags);
867 
868 
886 struct GNUNET_PQ_Context *
888  const char *section,
889  const char *load_path_suffix,
890  const struct GNUNET_PQ_ExecuteStatement *es,
891  const struct GNUNET_PQ_PreparedStatement *ps);
892 
893 
912 struct GNUNET_PQ_Context *
914  const char *section,
915  const char *load_path_suffix,
916  const struct GNUNET_PQ_ExecuteStatement *es,
917  const struct GNUNET_PQ_PreparedStatement *ps,
918  enum GNUNET_PQ_Options flags);
919 
920 
926 void
928 
929 
935 void
937 
938 
956 struct GNUNET_DB_EventHandler *
958  const struct GNUNET_DB_EventHeaderP *es,
961  void *cb_cls);
962 
963 
975 void
977 
978 
993 void
995  const struct GNUNET_DB_EventHeaderP *es,
996  const void *extra,
997  size_t extra_size);
998 
999 
1011  const char *load_path);
1012 
1013 
1020 void
1022 
1023 
1024 #endif /* GNUNET_PQ_LIB_H_ */
1025 
1026 /* end of include/gnunet_pq_lib.h */
static const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration we are using.
Definition: gnunet-abd.c:36
static struct GNUNET_TIME_Relative timeout
Desired timeout for the lookup (default is no timeout).
Definition: gnunet-abd.c:61
uint32_t data
The data value.
static int result
Global testing status.
static struct GNUNET_FS_DirectoryBuilder * db
Definition: gnunet-search.c:41
GNUNET_GenericReturnValue
Named constants for return values.
Definition: gnunet_common.h:92
shared definitions for transactional databases
void(* GNUNET_DB_EventCallback)(void *cls, const void *extra, size_t extra_size)
Function called on events received from Postgres.
Definition: gnunet_db_lib.h:79
GNUNET_DB_QueryStatus
Status code returned from functions running database commands.
Definition: gnunet_db_lib.h:36
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.
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.
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_reconnect(struct GNUNET_PQ_Context *db)
Reinitialize the database db.
Definition: pq_connect.c:312
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
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint32(const char *name, uint32_t *u32)
uint32_t expected.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_null(void)
Generate query parameter to create a NULL value.
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
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_notify(struct GNUNET_PQ_Context *db, const struct GNUNET_DB_EventHeaderP *es, const void *extra, size_t extra_size)
Notify all that listen on es of an event.
Definition: pq_event.c:485
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:201
struct GNUNET_DB_EventHandler * GNUNET_PQ_event_listen(struct GNUNET_PQ_Context *db, const struct GNUNET_DB_EventHeaderP *es, struct GNUNET_TIME_Relative timeout, GNUNET_DB_EventCallback cb, void *cb_cls)
Register callback to be invoked on events of type es.
Definition: pq_event.c:416
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_absolute_time(const struct GNUNET_TIME_Absolute *x)
Generate query parameter for an absolute time value.
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
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_relative_time(const struct GNUNET_TIME_Relative *x)
Generate query parameter for a relative time value.
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_fixed_size(const char *name, void *dst, size_t dst_size)
Fixed-size result expected.
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.
void(* GNUNET_PQ_ResultCleanup)(void *cls, void *rd)
Function called to clean up memory allocated by a GNUNET_PQ_ResultConverter.
enum GNUNET_GenericReturnValue 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
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_absolute_time_nbo(const char *name, struct GNUNET_TIME_AbsoluteNBO *at)
Absolute time expected.
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_QueryParam GNUNET_PQ_query_param_absolute_time_nbo(const struct GNUNET_TIME_AbsoluteNBO *x)
Generate query parameter for an absolute time value.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint64(const char *name, uint64_t *u64)
uint64_t expected.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_string(const char *name, char **dst)
0-terminated string expected.
void GNUNET_PQ_reconnect_if_down(struct GNUNET_PQ_Context *db)
Reinitialize the database db if the connection is down.
Definition: pq_connect.c:300
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_result(struct GNUNET_PQ_Context *db, const char *statement_name, PGresult *result)
Check the result's error code to see what happened.
Definition: pq_eval.c:59
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:508
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.
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
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_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.
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_absolute_time(const char *name, struct GNUNET_TIME_Absolute *at)
Absolute time expected.
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:449
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint16(const char *name, uint16_t *u16)
uint16_t expected.
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
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_uint32(const uint32_t *x)
Generate query parameter for an uint32_t in host byte order.
struct GNUNET_PQ_Context * GNUNET_PQ_connect2(const char *config_str, const char *load_path, const struct GNUNET_PQ_ExecuteStatement *es, const struct GNUNET_PQ_PreparedStatement *ps, enum GNUNET_PQ_Options flags)
Create a connection to the Postgres database using config_str for the configuration.
Definition: pq_connect.c:82
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_relative_time(const char *name, struct GNUNET_TIME_Relative *rt)
Relative time expected.
GNUNET_PQ_Options
Flags to control PQ operation.
@ GNUNET_PQ_FLAG_DROP
Dropping database.
@ GNUNET_PQ_FLAG_CHECK_CURRENT
Check database version is current.
@ GNUNET_PQ_FLAG_NONE
Traditional default.
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_rsa_public_key(const char *name, struct GNUNET_CRYPTO_RsaPublicKey **rsa)
RSA public key expected.
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
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
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
void GNUNET_PQ_event_listen_cancel(struct GNUNET_DB_EventHandler *eh)
Stop notifications.
Definition: pq_event.c:453
struct GNUNET_PQ_Context * GNUNET_PQ_connect_with_cfg2(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, enum GNUNET_PQ_Options flags)
Connect to a postgres database using the configuration option "CONFIG" in section.
Definition: pq_connect.c:465
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_rsa_signature(const char *name, struct GNUNET_CRYPTO_RsaSignature **sig)
RSA signature expected.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_string(const char *ptr)
Generate query parameter for a string.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_rsa_signature(const struct GNUNET_CRYPTO_RsaSignature *x)
Generate query parameter for an RSA signature.
const char * name
The public information of an RSA key pair.
Definition: crypto_rsa.c:52
an RSA signature
Definition: crypto_rsa.c:64
Handle for an active LISTENer to the database.
Definition: pq_event.c:34
void * cb_cls
Closure for cb.
Definition: pq_event.c:48
GNUNET_DB_EventCallback cb
Function to call on events.
Definition: pq_event.c:43
Header of a structure that describes an event channel we may subscribe to or notify on.
Definition: gnunet_db_lib.h:91
Handle to Postgres database.
Definition: pq.h:36
struct GNUNET_PQ_ExecuteStatement * es
Statements to execute upon connection.
Definition: pq.h:45
enum GNUNET_PQ_Options flags
Flags controlling the connection.
Definition: pq.h:80
char * load_path
Path to load SQL files from.
Definition: pq.h:60
struct GNUNET_PQ_PreparedStatement * ps
Prepared statements.
Definition: pq.h:50
char * config_str
Configuration to use to connect to the DB.
Definition: pq.h:55
Information needed to run a list of SQL statements using GNUNET_PQ_exec_statements().
const char * sql
Actual SQL statement.
int ignore_errors
Should we ignore errors?
Information needed to prepare a list of SQL statements using GNUNET_PQ_prepare_statements().
unsigned int num_arguments
Number of arguments included in sql.
const char * name
Name of the statement.
const char * sql
Actual SQL statement.
Description of a DB query parameter.
Definition: gnunet_pq_lib.h:65
void * conv_cls
Closure for conv.
Definition: gnunet_pq_lib.h:74
const void * data
Data or NULL.
Definition: gnunet_pq_lib.h:79
GNUNET_PQ_QueryConverter conv
Function for how to handle this type of entry.
Definition: gnunet_pq_lib.h:69
unsigned int num_params
Number of parameters eaten by this operation.
Definition: gnunet_pq_lib.h:89
size_t size
Size of data.
Definition: gnunet_pq_lib.h:84
Description of a DB result cell.
const char * fname
Field name of the desired result.
bool * is_null
Points to a location where we should store "true" if the result found is NULL, and otherwise "false".
void * dst
Destination for the data.
bool is_nullable
True if NULL is allowed for a value in the database.
void * cls
Closure for conv and cleaner.
GNUNET_PQ_ResultConverter conv
What is the format of the result?
size_t * result_size
Where to store actual size of the result.
GNUNET_PQ_ResultCleanup cleaner
Function to clean up result data, NULL if cleanup is not necessary.
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...
Time for absolute time used by GNUnet, in microseconds and in network byte order.
Time for absolute times used by GNUnet, in microseconds.
Time for relative time used by GNUnet, in microseconds.