src/include/gnunet_my_lib.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2016 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  */
  20 /**
  21  * @author Christian Grothoff
  22  * @author Christophe Genevey
  23  *
  24  * @file
  25  * Helper library to access a MySQL database
  26  *
  27  * @defgroup mysql  MySQL library
  28  * Helper library to access a MySQL database.
  29  * @{
  30  */
  31 #ifndef GNUNET_MY_LIB_H
  32 #define GNUNET_MY_LIB_H
  33
  34 #include "gnunet_util_lib.h"
  35 #include "gnunet_mysql_lib.h"
  36 #include <mysql/mysql.h>
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46
  47
  48 /**
  49  * Information we pass to #GNUNET_MY_exec_prepared() to
  50  * initialize the arguments of the prepared statement.
  51  */
  52 struct GNUNET_MY_QueryParam;
  53
  54
  55 /**
  56  * Function called to convert input argument into SQL parameters.
  57  *
  58  * @param cls closure
  59  * @param pq data about the query
  60  * @param qbind array of parameters to initialize
  61  * @return -1 on error
  62  */
  63 typedef int
  64 (*GNUNET_MY_QueryConverter)(void *cls,
  65                             const struct GNUNET_MY_QueryParam *qp,
  66                             MYSQL_BIND *qbind);
  67
  68
  69 /**
  70  * Function called to cleanup result data.
  71  *
  72  * @param cls closure
  73  * @param rs spec to clean up
  74  */
  75 typedef void
  76 (*GNUNET_MY_QueryCleanup)(void *cls,
  77                           MYSQL_BIND *qbind);
  78 /**
  79  * Information we pass to #GNUNET_MY_exec_prepared() to
  80  * initialize the arguments of the prepared statement.
  81  */
  82
  83
  84 struct GNUNET_MY_QueryParam
  85 {
  86   /**
  87    * Function to call for the type conversion.
  88    */
  89   GNUNET_MY_QueryConverter conv;
  90
  91   /**
  92    * Function to call for cleaning up the query. Can be NULL.
  93    */
  94   GNUNET_MY_QueryCleanup cleaner;
  95
  96   /**
  97    * Closure for @e conv.
  98    */
  99   void *conv_cls;
 100
 101   /**
 102    * Number of arguments the @a conv converter expects to initialize.
 103    */
 104   unsigned int num_params;
 105
 106   /**
 107    * Information to pass to @e conv.
 108    */
 109   const void *data;
 110
 111   /**
 112    * Information to pass to @e conv.  Size of @a data.
 113    */
 114   unsigned long data_len;
 115 };
 116
 117 /**
 118  * End of query parameter specification.
 119  *
 120  * @return array last entry for the result specification to use
 121  */
 122 #define GNUNET_MY_query_param_end { NULL, NULL, NULL, 0, NULL, 0 }
 123
 124
 125 /**
 126  * Generate query parameter for a buffer @a ptr of
 127  * @a ptr_size bytes.FG
 128  *
 129  * @param ptr pointer to the query parameter to pass
 130  * @oaran ptr_size number of bytes in @a ptr
 131  */
 132 struct GNUNET_MY_QueryParam
 133 GNUNET_MY_query_param_fixed_size (const void *ptr,
 134                                   size_t ptr_size);
 135
 136
 137 /**
 138  * Run a prepared SELECT statement.
 139  *
 140  * @param mc mysql context
 141  * @param sh handle to SELECT statment
 142  * @param params parameters to the statement
 143  * @return TBD
 144  */
 145 int
 146 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
 147                          struct GNUNET_MYSQL_StatementHandle *sh,
 148                          struct GNUNET_MY_QueryParam *params);
 149
 150
 151 /**
 152  * Information we pass to #GNUNET_MY_extract_result() to
 153  * initialize the arguments of the prepared statement.
 154  */
 155 struct GNUNET_MY_ResultParam;
 156
 157 /**
 158  * Information we pass to #GNUNET_MY_extract_result() to
 159  * initialize the arguments of the prepared statement.
 160  */
 161 struct GNUNET_MY_ResultSpec;
 162
 163 /**
 164  * Function called to convert input argument into SQL parameters.
 165  *
 166  * @param cls closure
 167  * @param[in,out] rs
 168  * @param stmt the mysql statement that is being run
 169  * @param column the column that is being processed
 170  * @param[out] results
 171  * @return -1 on error
 172  */
 173 typedef int
 174 (*GNUNET_MY_ResultConverter)(void *cls,
 175                              struct GNUNET_MY_ResultSpec *rs,
 176                              MYSQL_STMT *stmt,
 177                              unsigned int column,
 178                              MYSQL_BIND *results);
 179
 180 /**
 181  * Function called to cleanup result data.
 182  *
 183  * @param cls closure
 184  * @param rs spec to clean up
 185  */
 186 typedef void
 187 (*GNUNET_MY_ResultCleanup)(void *cls,
 188                            struct GNUNET_MY_ResultSpec *rs);
 189
 190
 191 /**
 192  * Information we pass to #GNUNET_MY_extract_result() to
 193  * initialize the arguments of the prepared statement.
 194  */
 195 struct GNUNET_MY_ResultSpec
 196 {
 197   /**
 198    * Function to call to initialize the MYSQL_BIND array.
 199    */
 200   GNUNET_MY_ResultConverter pre_conv;
 201
 202   /**
 203    * Function to call for converting the result. Can be NULL.
 204    */
 205   GNUNET_MY_ResultConverter post_conv;
 206
 207   /**
 208    * Function to call for cleaning up the result. Can be NULL.
 209    */
 210   GNUNET_MY_ResultCleanup cleaner;
 211
 212   /**
 213    * Closure for @e conv.
 214    */
 215   void *conv_cls;
 216
 217   /**
 218    * Destination for the data.
 219    */
 220   void *dst;
 221
 222   /**
 223    * Allowed size for the data, 0 for variable-size
 224    * (in this case, the type of @e dst is a `void **`
 225    * and we need to allocate a buffer of the right size).
 226    */
 227   size_t dst_size;
 228
 229   /**
 230    * Where to store actual size of the result.
 231    */
 232   size_t *result_size;
 233
 234   /**
 235    * How many fields does this result specification occupy
 236    * in the result returned by MySQL.
 237    */
 238   unsigned int num_fields;
 239
 240   /**
 241    * Location where we temporarily store the output buffer
 242    * length from MySQL.  Internal to libgnunetmy.
 243    */
 244   unsigned long mysql_bind_output_length;
 245
 246   /**
 247    * Memory for MySQL to notify us about NULL values.
 248    */
 249   my_bool is_null;
 250 };
 251
 252
 253 /**
 254  * End of result speceter specification.
 255  *
 256  * @return array last entry for the result specification to use
 257  */
 258 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0, 0 }
 259
 260
 261
 262 /**
 263  * Obtain fixed size result of @a ptr_size bytes from
 264  * MySQL, store in already allocated buffer at @a ptr.
 265  *
 266  * @spec ptr where to write the result
 267  * @oaran ptr_size number of bytes available at @a ptr
 268  */
 269 struct GNUNET_MY_ResultSpec
 270 GNUNET_MY_result_spec_fixed_size (void *ptr,
 271                                   size_t ptr_size);
 272
 273 /**
 274  * Generate query parameter for a string
 275  *
 276  *@param ptr pointer to the string query parameter to pass
 277  */
 278 struct GNUNET_MY_QueryParam
 279 GNUNET_MY_query_param_string (const char *ptr);
 280
 281 /**
 282  * Generate fixed-size query parameter with size determined
 283  * by variable type.
 284  *
 285  * @param x pointer to the query parameter to pass
 286  */
 287 #define GNUNET_MY_query_param_auto_from_type( \
 288     x) GNUNET_MY_query_param_fixed_size ((x), sizeof(*(x)))
 289
 290 /**
 291  * Generate query parameter for an RSA public key. The
 292  * database must contain a BLOB type in the respective position.
 293  *
 294  * @param x the query parameter to pass
 295  * @return array entry for the query parameters to use
 296  */
 297 struct GNUNET_MY_QueryParam
 298 GNUNET_MY_query_param_rsa_public_key (const struct
 299                                       GNUNET_CRYPTO_RsaPublicKey *x);
 300
 301 /**
 302  * Generate query parameter for an RSA signature. The
 303  * database must contain a BLOB type in the respective position
 304  *
 305  *@param x the query parameter to pass
 306  *@return array entry for the query parameters to use
 307  */
 308 struct GNUNET_MY_QueryParam
 309 GNUNET_MY_query_param_rsa_signature (const struct
 310                                      GNUNET_CRYPTO_RsaSignature *x);
 311
 312 /**
 313  * Generate query parameter for an absolute time value.
 314  * The database must store a 64-bit integer.
 315  *
 316  *@param x pointer to the query parameter to pass
 317  *@return array entry for the query parameters to use
 318  */
 319 struct GNUNET_MY_QueryParam
 320 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 321
 322
 323 /**
 324  * Generate query parameter for an absolute time value.
 325  * The database must store a 64-bit integer.
 326  *
 327  *@param x pointer to the query parameter to pass
 328  */
 329 struct GNUNET_MY_QueryParam
 330 GNUNET_MY_query_param_absolute_time_nbo (const struct
 331                                          GNUNET_TIME_AbsoluteNBO *x);
 332
 333 /**
 334  * Generate query parameter for an uint16_t in host byte order.
 335  *
 336  * @param x pointer to the query parameter to pass
 337  */
 338 struct GNUNET_MY_QueryParam
 339 GNUNET_MY_query_param_uint16 (const uint16_t *x);
 340
 341 /**
 342  * Generate query parameter for an uint32_t in host byte order
 343  *
 344  *@param x pointer to the query parameter to pass
 345  */
 346 struct GNUNET_MY_QueryParam
 347 GNUNET_MY_query_param_uint32 (const uint32_t *x);
 348
 349 /**
 350  * Generate query parameter for an uint64_t in host byte order
 351  *
 352  *@param x pointer to the query parameter to pass
 353  */
 354 struct GNUNET_MY_QueryParam
 355 GNUNET_MY_query_param_uint64 (const uint64_t *x);
 356
 357 /**
 358  * We expect a fixed-size result, with size determined by the type of `* dst`
 359  *
 360  * @spec name name of the field in the table
 361  * @spec dst point to where to store the result, type fits expected result size
 362  * @return array entry for the result specification to use
 363  */
 364 #define GNUNET_MY_result_spec_auto_from_type( \
 365     dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof(*(dst)))
 366
 367
 368 /**
 369  * Variable-size result expected
 370  *
 371  * @param[out] dst where to store the result, allocated
 372  * @param[out] sptr where to store the size of @a dst
 373  * @return array entru for the result specification to use
 374  */
 375 struct GNUNET_MY_ResultSpec
 376 GNUNET_MY_result_spec_variable_size (void **dst,
 377                                      size_t *ptr_size);
 378
 379 /**
 380  * RSA public key expected
 381  *
 382  * @param name name of the field in the table
 383  * @param[out] rsa where to store the result
 384  * @return array entry for the result specification to use
 385  */
 386 struct GNUNET_MY_ResultSpec
 387 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 388
 389
 390 /**
 391  * RSA signature expected.
 392  *
 393  * @param[out] sig where to store the result;
 394  * @return array entry for the result specification to use
 395  */
 396 struct GNUNET_MY_ResultSpec
 397 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
 398
 399 /**
 400  * 0- terminated string exprected.
 401  *
 402  * @param[out] dst where to store the result, allocated
 403  * @return array entry for the result specification to use
 404  */
 405 struct GNUNET_MY_ResultSpec
 406 GNUNET_MY_result_spec_string (char **dst);
 407
 408 /**
 409  * Absolute time expected
 410  *
 411  * @param name name of the field in the table
 412  * @param[out] at where to store the result
 413  * @return array entry for the result specification to use
 414  */
 415 struct GNUNET_MY_ResultSpec
 416 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
 417
 418 /**
 419  * Absolute time in network byte order expected
 420  *
 421  * @param[out] at where to store the result
 422  * @return array entry for the result specification to use
 423  */
 424 struct GNUNET_MY_ResultSpec
 425 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
 426
 427 /**
 428  * uint16_t expected
 429  *
 430  * @param[out] u16 where to store the result
 431  * @return array entry for the result specification to use
 432  */
 433 struct GNUNET_MY_ResultSpec
 434 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
 435
 436 /**
 437  * uint32_t expected
 438  *
 439  * @param[out] u32 where to store the result
 440  * @return array entry for the result specification to use
 441  */
 442 struct GNUNET_MY_ResultSpec
 443 GNUNET_MY_result_spec_uint32 (uint32_t *u32);
 444
 445 /**
 446  * uint64_t expected.
 447  *
 448  * @param[out] u64 where to store the result
 449  * @return array entry for the result specification to use
 450  */
 451 struct GNUNET_MY_ResultSpec
 452 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
 453
 454
 455 /**
 456  * Extract results from a query result according to the given
 457  * specification.  Always fetches the next row.
 458  *
 459  * @param sh statement that returned results
 460  * @param rs specification to extract for
 461  * @return
 462  *  #GNUNET_YES if all results could be extracted
 463  *  #GNUNET_NO if there is no more data in the result set
 464  *  #GNUNET_SYSERR if a result was invalid
 465  */
 466 int
 467 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
 468                           struct GNUNET_MY_ResultSpec *specs);
 469
 470
 471 /**
 472  * Free all memory that was allocated in @a qp during
 473  * #GNUNET_MY_exect_prepared().
 474  *
 475  * @param qp query specification to clean up
 476  * @param qbind mysql query
 477  */
 478 void
 479 GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp,
 480                          MYSQL_BIND *qbind);
 481
 482
 483 /**
 484  * Free all memory that was allocated in @a rs during
 485  * #GNUNET_MY_extract_result().
 486  *
 487  * @param rs reult specification to clean up
 488  */
 489 void
 490 GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
 491
 492
 493 #if 0                           /* keep Emacsens' auto-indent happy */
 494 {
 495 #endif
 496 #ifdef __cplusplus
 497 }
 498 #endif
 499
 500 #endif
 501
 502 /** @} */  /* end of group */