gnunet_pq_lib.h

Go to the documentation of this file.

/*
   This file is part of GNUnet
   Copyright (C) 2016, 2017, 2020-2022 GNUnet e.V.
 
   GNUnet is free software: you can redistribute it and/or modify it
   under the terms of the GNU Affero General Public License as published
   by the Free Software Foundation, either version 3 of the License,
   or (at your option) any later version.
 
   GNUnet is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
#ifndef GNUNET_PQ_LIB_H
#define GNUNET_PQ_LIB_H
 
 
#include <libpq-fe.h>
#include <stdint.h>
#include "gnunet_common.h"
#include "gnunet_time_lib.h"
#include "gnunet_util_lib.h"
#include "gnunet_db_lib.h"
#include "postgres_ext.h"
 
struct GNUNET_PQ_Context;
 
/* ************************* pq_query_helper.c functions ************************ */
 
 
typedef 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);
 
typedef void
(*GNUNET_PQ_QueryConverter_Cleanup)(void *cls);
 
struct GNUNET_PQ_QueryParam
{
  GNUNET_PQ_QueryConverter conv;
 
  void *conv_cls;
 
  GNUNET_PQ_QueryConverter_Cleanup conv_cls_cleanup;
 
  const void *data;
 
  size_t size;
 
  unsigned int num_params;
 
};
 
void
GNUNET_PQ_cleanup_query_params_closures (
  const struct GNUNET_PQ_QueryParam *params);
 
#define GNUNET_PQ_query_param_end \
  {                               \
    .conv = NULL,                 \
    .conv_cls = NULL,             \
    .data = NULL,                 \
    .size = 0,                    \
    .num_params = 0               \
  }
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_null (void);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_fixed_size (const void *ptr,
                                  size_t ptr_size);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_string (const char *ptr);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_bool (bool b);
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_get_oid_by_name (
  struct GNUNET_PQ_Context *db,
  const char *name,
  Oid *oid);
 
 
struct GNUNET_PQ_ArrayHeader_P
{
  uint32_t ndim;     /* number of dimensions. we only support ndim = 1 */
  uint32_t has_null;
  uint32_t oid;      /* oid of the elements */
  uint32_t dim;      /* size of the array */
  uint32_t lbound;   /* index value of first element in the db (default: 1). */
} __attribute__((packed));
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_bool (
  unsigned int num,
  const bool *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_uint16 (
  unsigned int num,
  const uint16_t *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_uint32 (
  unsigned int num,
  const uint32_t *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_uint64 (
  unsigned int num,
  const uint64_t *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_bytes (
  unsigned int num,
  const void *elements,
  const size_t *sizes,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_bytes_same_size (
  unsigned int num,
  const void *elements,
  size_t same_size,
  struct GNUNET_PQ_Context *db);
 
#define GNUNET_PQ_query_param_array_auto_from_type(num, elements, db) \
  GNUNET_PQ_query_param_array_bytes_same_size ((num), \
                                               (elements), \
                                               sizeof(*(elements)), \
                                               (db))
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_ptrs_bytes_same_size (
  unsigned int num,
  const void *elements[static num],
  size_t same_size,
  struct GNUNET_PQ_Context *db);
 
 
#define GNUNET_PQ_query_param_array_ptrs_auto_from_type(num, elements, db) \
  GNUNET_PQ_query_param_array_ptrs_bytes_same_size ((num), \
                                                    (const void **) (elements), \
                                                    sizeof(*(elements[0])), \
                                                    (db))
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_string (
  unsigned int num,
  const char *elements,
  struct GNUNET_PQ_Context *db);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_ptrs_string (
  unsigned int num,
  const char *elements[static num],
  struct GNUNET_PQ_Context *db);
 
 
#define GNUNET_PQ_query_param_auto_from_type(x) \
  GNUNET_PQ_query_param_fixed_size ((x), sizeof(*(x)))
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_abs_time (
  unsigned int num,
  const struct GNUNET_TIME_Absolute *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_ptrs_abs_time (
  unsigned int num,
  const struct GNUNET_TIME_Absolute *elements[],
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_rel_time (
  unsigned int num,
  const struct GNUNET_TIME_Relative *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_ptrs_rel_time (
  unsigned int num,
  const struct GNUNET_TIME_Relative *elements[],
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_timestamp (
  unsigned int num,
  const struct GNUNET_TIME_Timestamp *elements,
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_array_ptrs_timestamp (
  unsigned int num,
  const struct GNUNET_TIME_Timestamp *elements[],
  struct GNUNET_PQ_Context *db);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_rsa_public_key (
  const struct GNUNET_CRYPTO_RsaPublicKey *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_rsa_signature (
  const struct GNUNET_CRYPTO_RsaSignature *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_relative_time (const struct GNUNET_TIME_Relative *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_timestamp (const struct GNUNET_TIME_Timestamp *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_absolute_time_nbo (
  const struct GNUNET_TIME_AbsoluteNBO *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_timestamp_nbo (
  const struct GNUNET_TIME_TimestampNBO *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_uint16 (const uint16_t *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_uint32 (const uint32_t *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_uint64 (const uint64_t *x);
 
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_int64 (const int64_t *x);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_blind_sign_pub (
  const struct GNUNET_CRYPTO_BlindSignPublicKey *pub);
 
struct GNUNET_PQ_QueryParam
GNUNET_PQ_query_param_blind_sign_priv (
  const struct GNUNET_CRYPTO_BlindSignPrivateKey *priv);
 
/* ************************* pq_result_helper.c functions ************************ */
 
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_PQ_ResultConverter)(void *cls,
                             PGresult *result,
                             int row,
                             const char *fname,
                             size_t *dst_size,
                             void *dst);
 
 
typedef void
(*GNUNET_PQ_ResultCleanup) (void *cls,
                            void *rd);
 
 
struct GNUNET_PQ_ResultSpec
{
  GNUNET_PQ_ResultConverter conv;
 
  GNUNET_PQ_ResultCleanup cleaner;
 
  void *cls;
 
  void *dst;
 
  size_t dst_size;
 
  const char *fname;
 
  size_t *result_size;
 
  bool is_nullable;
 
  bool *is_null;
 
};
 
 
#define GNUNET_PQ_result_spec_end         \
  {                                       \
    .conv = NULL,                         \
    .cleaner = NULL,                      \
    .cls = NULL,                          \
    .dst = NULL,                          \
    .dst_size = 0,                        \
    .fname = NULL,                        \
    .result_size = NULL,                  \
    .is_nullable = false,                 \
    .is_null = NULL                       \
  }
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_allow_null (struct GNUNET_PQ_ResultSpec rs,
                                  bool *is_null);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_variable_size (const char *name,
                                     void **dst,
                                     size_t *sptr);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_fixed_size (const char *name,
                                  void *dst,
                                  size_t dst_size);
 
 
#define GNUNET_PQ_result_spec_auto_from_type(name, dst) \
  GNUNET_PQ_result_spec_fixed_size (name, (dst), sizeof(*(dst)))
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_string (const char *name,
                              char **dst);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_bool (const char *name,
                            bool *dst);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_rsa_public_key (const char *name,
                                      struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_rsa_signature (const char *name,
                                     struct GNUNET_CRYPTO_RsaSignature **sig);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_absolute_time (const char *name,
                                     struct GNUNET_TIME_Absolute *at);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_timestamp (const char *name,
                                 struct GNUNET_TIME_Timestamp *t);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_relative_time (const char *name,
                                     struct GNUNET_TIME_Relative *rt);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_absolute_time_nbo (const char *name,
                                         struct GNUNET_TIME_AbsoluteNBO *at);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_timestamp_nbo (const char *name,
                                     struct GNUNET_TIME_TimestampNBO *tn);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_uint16 (const char *name,
                              uint16_t *u16);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_uint32 (const char *name,
                              uint32_t *u32);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_uint64 (const char *name,
                              uint64_t *u64);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_int64 (const char *name,
                             int64_t *i64);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_bool (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  bool **bools);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_uint16 (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  uint16_t **dst);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_uint32 (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  uint32_t **dst);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_uint64 (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  uint64_t **dst);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_abs_time (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  struct GNUNET_TIME_Absolute **dst);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_rel_time (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  struct GNUNET_TIME_Relative **dst);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_timestamp (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  struct GNUNET_TIME_Timestamp **dst);
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_variable_size (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  size_t **sizes,
  void **dst);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_fixed_size (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t size,
  size_t *num,
  void **dst);
 
 
#define GNUNET_PQ_result_spec_auto_array_from_type(db, name, num, dst) \
  GNUNET_PQ_result_spec_array_fixed_size ( \
    (db), \
    (name), \
    sizeof(*(dst)), \
    (num), \
    (void *) &(dst))
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_array_string (
  struct GNUNET_PQ_Context *db,
  const char *name,
  size_t *num,
  char **dst);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_blind_sign_pub (
  const char *name,
  struct GNUNET_CRYPTO_BlindSignPublicKey *public_key);
 
 
struct GNUNET_PQ_ResultSpec
GNUNET_PQ_result_spec_blind_sign_priv (
  const char *name,
  struct GNUNET_CRYPTO_BlindSignPrivateKey *private_key);
 
/* ************************* pq.c functions ************************ */
 
PGresult *
GNUNET_PQ_exec_prepared (struct GNUNET_PQ_Context *db,
                         const char *name,
                         const struct GNUNET_PQ_QueryParam *params);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_extract_result (PGresult *result,
                          struct GNUNET_PQ_ResultSpec *rs,
                          int row);
 
 
void
GNUNET_PQ_cleanup_result (struct GNUNET_PQ_ResultSpec *rs);
 
 
/* ******************** pq_eval.c functions ************** */
 
 
enum GNUNET_DB_QueryStatus
GNUNET_PQ_eval_result (struct GNUNET_PQ_Context *db,
                       const char *statement_name,
                       PGresult *result);
 
 
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);
 
 
typedef void
(*GNUNET_PQ_PostgresResultHandler) (void *cls,
                                    PGresult *result,
                                    unsigned int num_results);
 
 
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);
 
 
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);
 
 
/* ******************** pq_prepare.c functions ************** */
 
 
struct GNUNET_PQ_PreparedStatement
{
  const char *name;
 
  const char *sql;
 
};
 
 
#define GNUNET_PQ_PREPARED_STATEMENT_END \
  {                                      \
    NULL, NULL                           \
  }
 
 
struct GNUNET_PQ_PreparedStatement
GNUNET_PQ_make_prepare (const char *name,
                        const char *sql);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_prepare_statements (struct GNUNET_PQ_Context *db,
                              const struct GNUNET_PQ_PreparedStatement *ps);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_prepare_once (struct GNUNET_PQ_Context *db,
                        const struct GNUNET_PQ_PreparedStatement *ps);
 
 
/* ******************** pq_exec.c functions ************** */
 
 
struct GNUNET_PQ_ExecuteStatement
{
  const char *sql;
 
  int ignore_errors;
};
 
 
#define GNUNET_PQ_EXECUTE_STATEMENT_END \
  {                                     \
    NULL, GNUNET_SYSERR                 \
  }
 
 
struct GNUNET_PQ_ExecuteStatement
GNUNET_PQ_make_execute (const char *sql);
 
 
struct GNUNET_PQ_ExecuteStatement
GNUNET_PQ_make_try_execute (const char *sql);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_exec_statements (struct GNUNET_PQ_Context *db,
                           const struct GNUNET_PQ_ExecuteStatement *es);
 
 
/* ******************** pq_connect.c functions ************** */
 
 
enum GNUNET_PQ_Options
{
  GNUNET_PQ_FLAG_NONE = 0,
 
  GNUNET_PQ_FLAG_DROP = 1,
 
  GNUNET_PQ_FLAG_CHECK_CURRENT = 2
};
 
 
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);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_exec_sql (struct GNUNET_PQ_Context *db,
                    const char *buf);
 
 
struct GNUNET_PQ_Context *
GNUNET_PQ_connect2 (const char *config_str,
                    const char *load_path,
                    const char *auto_suffix,
                    const struct GNUNET_PQ_ExecuteStatement *es,
                    const struct GNUNET_PQ_PreparedStatement *ps,
                    enum GNUNET_PQ_Options flags);
 
 
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);
 
 
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);
 
 
void
GNUNET_PQ_reconnect_if_down (struct GNUNET_PQ_Context *db);
 
 
void
GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
 
 
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);
 
 
void
GNUNET_PQ_event_listen_cancel (struct GNUNET_DB_EventHandler *eh);
 
 
void
GNUNET_PQ_event_do_poll (struct GNUNET_PQ_Context *db);
 
 
void
GNUNET_PQ_event_notify (struct GNUNET_PQ_Context *db,
                        const struct GNUNET_DB_EventHeaderP *es,
                        const void *extra,
                        size_t extra_size);
 
 
char *
GNUNET_PQ_get_event_notify_channel (const struct GNUNET_DB_EventHeaderP *es);
 
 
enum GNUNET_GenericReturnValue
GNUNET_PQ_run_sql (struct GNUNET_PQ_Context *db,
                   const char *load_path);
 
 
void
GNUNET_PQ_disconnect (struct GNUNET_PQ_Context *db);
 
 
#endif /* GNUNET_PQ_LIB_H_ */
 
/* end of include/gnunet_pq_lib.h */