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