GNUnet  0.10.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 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 (*GNUNET_PQ_QueryConverter) (void *cls,
50  const void *data,
51  size_t data_len,
52  void *param_values[],
53  int param_lengths[],
54  int param_formats[],
55  unsigned int param_length,
56  void *scratch[],
57  unsigned int scratch_length);
58 
59 
68 
72  void *conv_cls;
73 
77  const void *data;
78 
82  size_t size;
83 
87  unsigned int num_params;
88 };
89 
90 
94 #define GNUNET_PQ_query_param_end \
95  { \
96  NULL, NULL, NULL, 0, 0 \
97  }
98 
99 
108 GNUNET_PQ_query_param_fixed_size(const void *ptr, size_t ptr_size);
109 
110 
117 GNUNET_PQ_query_param_string(const char *ptr);
118 
119 
126 #define GNUNET_PQ_query_param_auto_from_type(x) \
127  GNUNET_PQ_query_param_fixed_size((x), sizeof(*(x)))
128 
129 
138  const struct GNUNET_CRYPTO_RsaPublicKey *x);
139 
140 
149  const struct GNUNET_CRYPTO_RsaSignature *x);
150 
151 
160 
161 
170  const struct GNUNET_TIME_AbsoluteNBO *x);
171 
172 
179 GNUNET_PQ_query_param_uint16(const uint16_t *x);
180 
181 
188 GNUNET_PQ_query_param_uint32(const uint32_t *x);
189 
190 
197 GNUNET_PQ_query_param_uint64(const uint64_t *x);
198 
199 
200 /* ************************* pq_result_helper.c functions ************************ */
201 
202 
216 typedef int (*GNUNET_PQ_ResultConverter) (void *cls,
217  PGresult *result,
218  int row,
219  const char *fname,
220  size_t *dst_size,
221  void *dst);
222 
223 
231 typedef void (*GNUNET_PQ_ResultCleanup) (void *cls, void *rd);
232 
233 
242 
248 
252  void *cls;
253 
257  void *dst;
258 
264  size_t dst_size;
265 
269  const char *fname;
270 
274  size_t *result_size;
275 };
276 
277 
283 #define GNUNET_PQ_result_spec_end \
284  { \
285  NULL, NULL, NULL, NULL, 0, NULL, NULL \
286  }
287 
288 
299  void **dst,
300  size_t *sptr);
301 
302 
312 GNUNET_PQ_result_spec_fixed_size(const char *name, void *dst, size_t dst_size);
313 
314 
322 #define GNUNET_PQ_result_spec_auto_from_type(name, dst) \
323  GNUNET_PQ_result_spec_fixed_size(name, (dst), sizeof(*(dst)))
324 
325 
334 GNUNET_PQ_result_spec_string(const char *name, char **dst);
335 
336 
346  struct GNUNET_CRYPTO_RsaPublicKey **rsa);
347 
348 
358  struct GNUNET_CRYPTO_RsaSignature **sig);
359 
360 
370  struct GNUNET_TIME_Absolute *at);
371 
372 
382  struct GNUNET_TIME_AbsoluteNBO *at);
383 
384 
393 GNUNET_PQ_result_spec_uint16(const char *name, uint16_t *u16);
394 
395 
404 GNUNET_PQ_result_spec_uint32(const char *name, uint32_t *u32);
405 
406 
415 GNUNET_PQ_result_spec_uint64(const char *name, uint64_t *u64);
416 
417 
418 /* ************************* pq.c functions ************************ */
419 
429 PGresult *
430 GNUNET_PQ_exec_prepared(PGconn *db_conn,
431  const char *name,
432  const struct GNUNET_PQ_QueryParam *params);
433 
434 
446 int
448  struct GNUNET_PQ_ResultSpec *rs,
449  int row);
450 
451 
458 void
460 
461 
462 /* ******************** pq_eval.c functions ************** */
463 
464 
479 GNUNET_PQ_eval_result(PGconn *connection,
480  const char *statement_name,
481  PGresult *result);
482 
483 
501 GNUNET_PQ_eval_prepared_non_select(PGconn *connection,
502  const char *statement_name,
503  const struct GNUNET_PQ_QueryParam *params);
504 
505 
514 typedef void (*GNUNET_PQ_PostgresResultHandler) (void *cls,
515  PGresult *result,
516  unsigned int num_results);
517 
518 
535 GNUNET_PQ_eval_prepared_multi_select(PGconn *connection,
536  const char *statement_name,
537  const struct GNUNET_PQ_QueryParam *params,
539  void *rh_cls);
540 
541 
559  PGconn *connection,
560  const char *statement_name,
561  const struct GNUNET_PQ_QueryParam *params,
562  struct GNUNET_PQ_ResultSpec *rs);
563 
564 
565 /* ******************** pq_prepare.c functions ************** */
566 
567 
576  const char *name;
577 
581  const char *sql;
582 
586  unsigned int num_arguments;
587 };
588 
589 
593 #define GNUNET_PQ_PREPARED_STATEMENT_END \
594  { \
595  NULL, NULL, 0 \
596  }
597 
598 
608 GNUNET_PQ_make_prepare(const char *name,
609  const char *sql,
610  unsigned int num_args);
611 
612 
622 int
623 GNUNET_PQ_prepare_statements(PGconn *connection,
624  const struct GNUNET_PQ_PreparedStatement *ps);
625 
626 
627 /* ******************** pq_exec.c functions ************** */
628 
629 
638  const char *sql;
639 
644 };
645 
646 
650 #define GNUNET_PQ_EXECUTE_STATEMENT_END \
651  { \
652  NULL, GNUNET_SYSERR \
653  }
654 
655 
663 GNUNET_PQ_make_execute(const char *sql);
664 
665 
674 GNUNET_PQ_make_try_execute(const char *sql);
675 
676 
686 int
687 GNUNET_PQ_exec_statements(PGconn *connection,
688  const struct GNUNET_PQ_ExecuteStatement *es);
689 
690 
691 /* ******************** pq_connect.c functions ************** */
692 
693 
702 PGconn *
703 GNUNET_PQ_connect(const char *config_str);
704 
705 
714 PGconn *
716  const char *section);
717 
718 
719 #endif /* GNUNET_PQ_LIB_H_ */
720 
721 /* end of include/gnunet_pq_lib.h */
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.
an RSA signature
Definition: crypto_rsa.c:61
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:49
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:37
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_string(const char *ptr)
Generate query parameter for a string.
GNUNET_PQ_QueryConverter conv
Function for how to handle this type of entry.
Definition: gnunet_pq_lib.h:67
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().
const char * fname
Field name of the desired result.
Description of a DB result cell.
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_absolute_time(const struct GNUNET_TIME_Absolute *x)
Generate query parameter for an absolute time value.
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_singleton_select(PGconn *connection, 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:241
int ignore_errors
Should we ignore errors?
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_non_select(PGconn *connection, const char *statement_name, const struct GNUNET_PQ_QueryParam *params)
Execute a named prepared statement that is NOT a SELECT statement in connnection using the given para...
Definition: pq_eval.c:151
const char * name
Name of the statement.
const void * data
Data or NULL.
Definition: gnunet_pq_lib.h:77
Time for absolute time used by GNUnet, in microseconds and in network byte order. ...
The public information of an RSA key pair.
Definition: crypto_rsa.c:50
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_result(PGconn *connection, const char *statement_name, PGresult *result)
Check the result&#39;s error code to see what happened.
Definition: pq_eval.c:60
static char * section
Name of the section.
Definition: gnunet-config.c:33
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.
int GNUNET_PQ_prepare_statements(PGconn *connection, const struct GNUNET_PQ_PreparedStatement *ps)
Request creation of prepared statements ps from Postgres.
Definition: pq_prepare.c:63
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.
shared defintions for transactional databases
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_absolute_time(const char *name, struct GNUNET_TIME_Absolute *at)
Absolute time expected.
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:72
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...
PGresult * GNUNET_PQ_exec_prepared(PGconn *db_conn, const char *name, const struct GNUNET_PQ_QueryParam *params)
Execute a prepared statement.
Definition: pq.c:41
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.
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:104
GNUNET_PQ_ResultCleanup cleaner
Function to clean up result data, NULL if cleanup is not necessary.
PGconn * GNUNET_PQ_connect_with_cfg(const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section)
Connect to a postgres database using the configuration option "CONFIG" in section.
Definition: pq_connect.c:112
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_rsa_signature(const struct GNUNET_CRYPTO_RsaSignature *x)
Generate query parameter for an RSA signature.
PGconn * GNUNET_PQ_connect(const char *config_str)
Create a connection to the Postgres database using config_str for the configuration.
Definition: pq_connect.c:73
const char * name
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:87
int GNUNET_PQ_exec_statements(PGconn *connection, const struct GNUNET_PQ_ExecuteStatement *es)
Request execution of an array of statements es from Postgres.
Definition: pq_exec.c:77
struct GNUNET_PQ_ResultSpec GNUNET_PQ_result_spec_uint16(const char *name, uint16_t *u16)
uint16_t expected.
configuration data
Definition: configuration.c:83
struct GNUNET_PQ_QueryParam GNUNET_PQ_query_param_uint64(const uint64_t *x)
Generate query parameter for an uint16_t in host byte order.
Description of a DB query parameter.
Definition: gnunet_pq_lib.h:63
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.
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:56
size_t size
Size of data.
Definition: gnunet_pq_lib.h:82
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?
uint32_t data
The data value.
enum GNUNET_DB_QueryStatus GNUNET_PQ_eval_prepared_multi_select(PGconn *connection, 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:194
const char * sql
Actual SQL statement.
int(* 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_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:39
int 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:144
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:121