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