src/include/gnunet_sq_lib.h

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 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 /**
  19  * @file include/gnunet_sq_lib.h
  20  * @brief helper functions for Sqlite3 DB interactions
  21  * @author Christian Grothoff
  22  */
  23 #ifndef GNUNET_SQ_LIB_H
  24 #define GNUNET_SQ_LIB_H
  25
  26 #include <sqlite3.h>
  27 #include "gnunet_util_lib.h"
  28
  29
  30 /**
  31  * Function called to convert input argument into SQL parameters.
  32  *
  33  * @param cls closure
  34  * @param data pointer to input argument
  35  * @param data_len number of bytes in @a data (if applicable)
  36  * @param stmt sqlite statement to bind parameters for
  37  * @param off offset of the argument to bind in @a stmt, numbered from 1,
  38  *            so immediately suitable for passing to `sqlite3_bind`-functions.
  39  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
  40  */
  41 typedef int
  42 (*GNUNET_SQ_QueryConverter)(void *cls,
  43                             const void *data,
  44                             size_t data_len,
  45                             sqlite3_stmt *stmt,
  46                             unsigned int off);
  47
  48
  49 /**
  50  * @brief Description of a DB query parameter.
  51  */
  52 struct GNUNET_SQ_QueryParam
  53 {
  54
  55   /**
  56    * Function for how to handle this type of entry.
  57    */
  58   GNUNET_SQ_QueryConverter conv;
  59
  60   /**
  61    * Closure for @e conv.
  62    */
  63   void *conv_cls;
  64
  65   /**
  66    * Data or NULL.
  67    */
  68   const void *data;
  69
  70   /**
  71    * Size of @e data
  72    */
  73   size_t size;
  74
  75   /**
  76    * Number of parameters eaten by this operation.
  77    */
  78   unsigned int num_params;
  79 };
  80
  81
  82 /**
  83  * End of query parameter specification.
  84  */
  85 #define GNUNET_SQ_query_param_end { NULL, NULL, NULL, 0, 0 }
  86
  87
  88 /**
  89  * Generate query parameter for a buffer @a ptr of
  90  * @a ptr_size bytes.
  91  *
  92  * @param ptr pointer to the query parameter to pass
  93  * @oaran ptr_size number of bytes in @a ptr
  94  */
  95 struct GNUNET_SQ_QueryParam
  96 GNUNET_SQ_query_param_fixed_size (const void *ptr,
  97                                   size_t ptr_size);
  98
  99
 100
 101 /**
 102  * Generate query parameter for a string.
 103  *
 104  * @param ptr pointer to the string query parameter to pass
 105  */
 106 struct GNUNET_SQ_QueryParam
 107 GNUNET_SQ_query_param_string (const char *ptr);
 108
 109
 110 /**
 111  * Generate fixed-size query parameter with size determined
 112  * by variable type.
 113  *
 114  * @param x pointer to the query parameter to pass.
 115  */
 116 #define GNUNET_SQ_query_param_auto_from_type(x) GNUNET_SQ_query_param_fixed_size ((x), sizeof (*(x)))
 117
 118
 119 /**
 120  * Generate query parameter for an RSA public key.  The
 121  * database must contain a BLOB type in the respective position.
 122  *
 123  * @param x the query parameter to pass.
 124  */
 125 struct GNUNET_SQ_QueryParam
 126 GNUNET_SQ_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
 127
 128
 129 /**
 130  * Generate query parameter for an RSA signature.  The
 131  * database must contain a BLOB type in the respective position.
 132  *
 133  * @param x the query parameter to pass
 134  */
 135 struct GNUNET_SQ_QueryParam
 136 GNUNET_SQ_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
 137
 138
 139 /**
 140  * Generate query parameter for an absolute time value.
 141  * The database must store a 64-bit integer.
 142  *
 143  * @param x pointer to the query parameter to pass
 144  */
 145 struct GNUNET_SQ_QueryParam
 146 GNUNET_SQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 147
 148
 149 /**
 150  * Generate query parameter for an absolute time value.
 151  * The database must store a 64-bit integer.
 152  *
 153  * @param x pointer to the query parameter to pass
 154  */
 155 struct GNUNET_SQ_QueryParam
 156 GNUNET_SQ_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
 157
 158
 159 /**
 160  * Generate query parameter for an uint16_t in host byte order.
 161  *
 162  * @param x pointer to the query parameter to pass
 163  */
 164 struct GNUNET_SQ_QueryParam
 165 GNUNET_SQ_query_param_uint16 (const uint16_t *x);
 166
 167
 168 /**
 169  * Generate query parameter for an uint32_t in host byte order.
 170  *
 171  * @param x pointer to the query parameter to pass
 172  */
 173 struct GNUNET_SQ_QueryParam
 174 GNUNET_SQ_query_param_uint32 (const uint32_t *x);
 175
 176
 177 /**
 178  * Generate query parameter for an uint16_t in host byte order.
 179  *
 180  * @param x pointer to the query parameter to pass
 181  */
 182 struct GNUNET_SQ_QueryParam
 183 GNUNET_SQ_query_param_uint64 (const uint64_t *x);
 184
 185
 186 /**
 187  * Execute binding operations for a prepared statement.
 188  *
 189  * @param db_conn database connection
 190  * @param params parameters to the statement
 191  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 192  */
 193 int
 194 GNUNET_SQ_bind (sqlite3_stmt *stmt,
 195                 const struct GNUNET_SQ_QueryParam *params);
 196
 197
 198 /**
 199  * Reset @a stmt and log error.
 200  *
 201  * @param dbh database handle
 202  * @param stmt statement to reset
 203  */
 204 void
 205 GNUNET_SQ_reset (sqlite3 *dbh,
 206                  sqlite3_stmt *stmt);
 207
 208
 209 /**
 210  * Extract data from a Postgres database @a result at row @a row.
 211  *
 212  * @param cls closure
 213  * @param result where to extract data from
 214  * @param column column to extract data from
 215  * @param[in,out] dst_size where to store size of result, may be NULL
 216  * @param[out] dst where to store the result
 217  * @return
 218  *   #GNUNET_YES if all results could be extracted
 219  *   #GNUNET_SYSERR if a result was invalid (non-existing field or NULL)
 220  */
 221 typedef int
 222 (*GNUNET_SQ_ResultConverter)(void *cls,
 223                              sqlite3_stmt *result,
 224                              unsigned int column,
 225                              size_t *dst_size,
 226                              void *dst);
 227
 228
 229 /**
 230  * @brief Description of a DB result cell.
 231  */
 232 struct GNUNET_SQ_ResultSpec;
 233
 234
 235 /**
 236  * Function called to clean up memory allocated
 237  * by a #GNUNET_SQ_ResultConverter.
 238  *
 239  * @param cls closure
 240  */
 241 typedef void
 242 (*GNUNET_SQ_ResultCleanup)(void *cls);
 243
 244
 245 /**
 246  * @brief Description of a DB result cell.
 247  */
 248 struct GNUNET_SQ_ResultSpec
 249 {
 250
 251   /**
 252    * What is the format of the result?
 253    */
 254   GNUNET_SQ_ResultConverter conv;
 255
 256   /**
 257    * Function to clean up result data, NULL if cleanup is
 258    * not necessary.
 259    */
 260   GNUNET_SQ_ResultCleanup cleaner;
 261
 262   /**
 263    * Closure for @e conv and @e cleaner.
 264    */
 265   void *cls;
 266
 267   /**
 268    * Destination for the data.
 269    */
 270   void *dst;
 271
 272   /**
 273    * Allowed size for the data, 0 for variable-size
 274    * (in this case, the type of @e dst is a `void **`
 275    * and we need to allocate a buffer of the right size).
 276    */
 277   size_t dst_size;
 278
 279   /**
 280    * Where to store actual size of the result.  If left at
 281    * NULL, will be made to point to @e dst_size before
 282    * @a conv is called.
 283    */
 284   size_t *result_size;
 285
 286   /**
 287    * Number of parameters (columns) eaten by this operation.
 288    */
 289   unsigned int num_params;
 290
 291 };
 292
 293
 294 /**
 295  * End of result parameter specification.
 296  *
 297  * @return array last entry for the result specification to use
 298  */
 299 #define GNUNET_SQ_result_spec_end { NULL, NULL, NULL, NULL, 0, NULL, 0 }
 300
 301
 302 /**
 303  * Variable-size result expected.
 304  *
 305  * @param[out] dst where to store the result, allocated
 306  * @param[out] sptr where to store the size of @a dst
 307  * @return array entry for the result specification to use
 308  */
 309 struct GNUNET_SQ_ResultSpec
 310 GNUNET_SQ_result_spec_variable_size (void **dst,
 311                                      size_t *sptr);
 312
 313
 314 /**
 315  * Fixed-size result expected.
 316  *
 317  * @param[out] dst where to store the result
 318  * @param dst_size number of bytes in @a dst
 319  * @return array entry for the result specification to use
 320  */
 321 struct GNUNET_SQ_ResultSpec
 322 GNUNET_SQ_result_spec_fixed_size (void *dst,
 323                                   size_t dst_size);
 324
 325
 326 /**
 327  * We expect a fixed-size result, with size determined by the type of `* dst`
 328  *
 329  * @param dst point to where to store the result, type fits expected result size
 330  * @return array entry for the result specification to use
 331  */
 332 #define GNUNET_SQ_result_spec_auto_from_type(dst) GNUNET_SQ_result_spec_fixed_size ((dst), sizeof (*(dst)))
 333
 334
 335 /**
 336  * Variable-size result expected.
 337  *
 338  * @param[out] dst where to store the result, allocated
 339  * @param[out] sptr where to store the size of @a dst
 340  * @return array entry for the result specification to use
 341  */
 342 struct GNUNET_SQ_ResultSpec
 343 GNUNET_SQ_result_spec_variable_size (void **dst,
 344                                      size_t *sptr);
 345
 346
 347 /**
 348  * 0-terminated string expected.
 349  *
 350  * @param[out] dst where to store the result, allocated
 351  * @return array entry for the result specification to use
 352  */
 353 struct GNUNET_SQ_ResultSpec
 354 GNUNET_SQ_result_spec_string (char **dst);
 355
 356
 357 /**
 358  * RSA public key expected.
 359  *
 360  * @param[out] rsa where to store the result
 361  * @return array entry for the result specification to use
 362  */
 363 struct GNUNET_SQ_ResultSpec
 364 GNUNET_SQ_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 365
 366
 367 /**
 368  * RSA signature expected.
 369  *
 370  * @param[out] sig where to store the result;
 371  * @return array entry for the result specification to use
 372  */
 373 struct GNUNET_SQ_ResultSpec
 374 GNUNET_SQ_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
 375
 376
 377 /**
 378  * Absolute time expected.
 379  *
 380  * @param[out] at where to store the result
 381  * @return array entry for the result specification to use
 382  */
 383 struct GNUNET_SQ_ResultSpec
 384 GNUNET_SQ_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
 385
 386
 387 /**
 388  * Absolute time expected.
 389  *
 390  * @param[out] at where to store the result
 391  * @return array entry for the result specification to use
 392  */
 393 struct GNUNET_SQ_ResultSpec
 394 GNUNET_SQ_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
 395
 396
 397 /**
 398  * uint16_t expected.
 399  *
 400  * @param[out] u16 where to store the result
 401  * @return array entry for the result specification to use
 402  */
 403 struct GNUNET_SQ_ResultSpec
 404 GNUNET_SQ_result_spec_uint16 (uint16_t *u16);
 405
 406
 407 /**
 408  * uint32_t expected.
 409  *
 410  * @param[out] u32 where to store the result
 411  * @return array entry for the result specification to use
 412  */
 413 struct GNUNET_SQ_ResultSpec
 414 GNUNET_SQ_result_spec_uint32 (uint32_t *u32);
 415
 416
 417 /**
 418  * uint64_t expected.
 419  *
 420  * @param[out] u64 where to store the result
 421  * @return array entry for the result specification to use
 422  */
 423 struct GNUNET_SQ_ResultSpec
 424 GNUNET_SQ_result_spec_uint64 (uint64_t *u64);
 425
 426
 427 /**
 428  * Extract results from a query result according to the given specification.
 429  *
 430  * @param result result to process
 431  * @param[in,out] rs result specification to extract for
 432  * @return
 433  *   #GNUNET_OK if all results could be extracted
 434  *   #GNUNET_SYSERR if a result was invalid (non-existing field)
 435  */
 436 int
 437 GNUNET_SQ_extract_result (sqlite3_stmt *result,
 438                           struct GNUNET_SQ_ResultSpec *rs);
 439
 440
 441 /**
 442  * Free all memory that was allocated in @a rs during
 443  * #GNUNET_SQ_extract_result().
 444  *
 445  * @param rs reult specification to clean up
 446  */
 447 void
 448 GNUNET_SQ_cleanup_result (struct GNUNET_SQ_ResultSpec *rs);
 449
 450
 451
 452 /* ******************** sq_prepare.c functions ************** */
 453
 454
 455 /**
 456  * Information needed to run a list of SQL statements using
 457  * #GNUNET_SQ_exec_statements().
 458  */
 459 struct GNUNET_SQ_PrepareStatement {
 460
 461   /**
 462    * Actual SQL statement.
 463    */
 464   const char *sql;
 465
 466   /**
 467    * Where to store handle?
 468    */
 469   sqlite3_stmt **pstmt;
 470
 471 };
 472
 473
 474 /**
 475  * Terminator for executable statement list.
 476  */
 477 #define GNUNET_SQ_PREPARE_END { NULL, NULL }
 478
 479
 480 /**
 481  * Create a `struct GNUNET_SQ_PrepareStatement`
 482  *
 483  * @param sql actual SQL statement
 484  * @param pstmt where to store the handle
 485  * @return initialized struct
 486  */
 487 struct GNUNET_SQ_PrepareStatement
 488 GNUNET_SQ_make_prepare (const char *sql,
 489                         sqlite3_stmt **pstmt);
 490
 491
 492
 493 /**
 494  * Prepare all statements given in the (NULL,NULL)-terminated
 495  * array at @a ps
 496  *
 497  * @param dbh database handle
 498  * @param ps array of statements to prepare
 499  * @return #GNUNET_OK on success
 500  */
 501 int
 502 GNUNET_SQ_prepare (sqlite3 *dbh,
 503                    const struct GNUNET_SQ_PrepareStatement *ps);
 504
 505
 506 /* ******************** sq_exec.c functions ************** */
 507
 508
 509 /**
 510  * Information needed to run a list of SQL statements using
 511  * #GNUNET_SQ_exec_statements().
 512  */
 513 struct GNUNET_SQ_ExecuteStatement {
 514
 515   /**
 516    * Actual SQL statement.
 517    */
 518   const char *sql;
 519
 520   /**
 521    * Should we ignore errors?
 522    */
 523   int ignore_errors;
 524
 525 };
 526
 527
 528 /**
 529  * Terminator for executable statement list.
 530  */
 531 #define GNUNET_SQ_EXECUTE_STATEMENT_END { NULL, GNUNET_SYSERR }
 532
 533
 534 /**
 535  * Create a `struct GNUNET_SQ_ExecuteStatement` where errors are fatal.
 536  *
 537  * @param sql actual SQL statement
 538  * @return initialized struct
 539  */
 540 struct GNUNET_SQ_ExecuteStatement
 541 GNUNET_SQ_make_execute (const char *sql);
 542
 543
 544 /**
 545  * Create a `struct GNUNET_SQ_ExecuteStatement` where errors should
 546  * be tolerated.
 547  *
 548  * @param sql actual SQL statement
 549  * @return initialized struct
 550  */
 551 struct GNUNET_SQ_ExecuteStatement
 552 GNUNET_SQ_make_try_execute (const char *sql);
 553
 554
 555 /**
 556  * Request execution of an array of statements @a es from Postgres.
 557  *
 558  * @param dbh database to execute the statements over
 559  * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared
 560  *            statements.
 561  * @return #GNUNET_OK on success (modulo statements where errors can be ignored)
 562  *         #GNUNET_SYSERR on error
 563  */
 564 int
 565 GNUNET_SQ_exec_statements (sqlite3 *dbh,
 566                            const struct GNUNET_SQ_ExecuteStatement *es);
 567
 568
 569
 570 #endif  /* GNUNET_SQ_LIB_H_ */
 571
 572 /* end of include/gnunet_sq_lib.h */