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 /**
  19  * @author Christian Grothoff
  20  * @author Christophe Genevey
  21  *
  22  * @file
  23  * Helper library to access a MySQL database
  24  *
  25  * @defgroup mysql  MySQL library
  26  * Helper library to access a MySQL database.
  27  * @{
  28  */
  29 #ifndef GNUNET_MY_LIB_H
  30 #define GNUNET_MY_LIB_H
  31
  32 #include "gnunet_util_lib.h"
  33 #include "gnunet_mysql_lib.h"
  34 #include <mysql/mysql.h>
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44
  45
  46 /**
  47  * Information we pass to #GNUNET_MY_exec_prepared() to
  48  * initialize the arguments of the prepared statement.
  49  */
  50 struct GNUNET_MY_QueryParam;
  51
  52
  53 /**
  54  * Function called to convert input argument into SQL parameters.
  55  *
  56  * @param cls closure
  57  * @param pq data about the query
  58  * @param qbind array of parameters to initialize
  59  * @return -1 on error
  60  */
  61 typedef int
  62 (*GNUNET_MY_QueryConverter)(void *cls,
  63                             const struct GNUNET_MY_QueryParam *qp,
  64                             MYSQL_BIND *qbind);
  65
  66
  67 /**
  68  * Function called to cleanup result data.
  69  *
  70  * @param cls closure
  71  * @param rs spec to clean up
  72  */
  73 typedef void
  74 (*GNUNET_MY_QueryCleanup)(void *cls,
  75                            MYSQL_BIND *qbind);
  76 /**
  77  * Information we pass to #GNUNET_MY_exec_prepared() to
  78  * initialize the arguments of the prepared statement.
  79  */
  80
  81
  82 struct GNUNET_MY_QueryParam
  83 {
  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 /**
 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   /**
 199    * Function to call to initialize the MYSQL_BIND array.
 200    */
 201   GNUNET_MY_ResultConverter pre_conv;
 202
 203   /**
 204    * Function to call for converting the result. Can be NULL.
 205    */
 206   GNUNET_MY_ResultConverter post_conv;
 207
 208     /**
 209    * Function to call for cleaning up the result. Can be NULL.
 210    */
 211   GNUNET_MY_ResultCleanup cleaner;
 212
 213   /**
 214    * Closure for @e conv.
 215    */
 216   void *conv_cls;
 217
 218   /**
 219    * Destination for the data.
 220    */
 221   void *dst;
 222
 223   /**
 224    * Allowed size for the data, 0 for variable-size
 225    * (in this case, the type of @e dst is a `void **`
 226    * and we need to allocate a buffer of the right size).
 227    */
 228   size_t dst_size;
 229
 230   /**
 231    * Where to store actual size of the result.
 232    */
 233   size_t *result_size;
 234
 235   /**
 236    * How many fields does this result specification occupy
 237    * in the result returned by MySQL.
 238    */
 239   unsigned int num_fields;
 240
 241   /**
 242    * Location where we temporarily store the output buffer
 243    * length from MySQL.  Internal to libgnunetmy.
 244    */
 245   unsigned long mysql_bind_output_length;
 246
 247   /**
 248    * Memory for MySQL to notify us about NULL values.
 249    */
 250   my_bool is_null;
 251
 252 };
 253
 254
 255 /**
 256  * End of result speceter specification.
 257  *
 258  * @return array last entry for the result specification to use
 259  */
 260 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0, 0 }
 261
 262
 263
 264 /**
 265  * Obtain fixed size result of @a ptr_size bytes from
 266  * MySQL, store in already allocated buffer at @a ptr.
 267  *
 268  * @spec ptr where to write the result
 269  * @oaran ptr_size number of bytes available at @a ptr
 270  */
 271 struct GNUNET_MY_ResultSpec
 272 GNUNET_MY_result_spec_fixed_size (void *ptr,
 273                                   size_t ptr_size);
 274
 275 /**
 276   * Generate query parameter for a string
 277   *
 278   *@param ptr pointer to the string query parameter to pass
 279   */
 280 struct GNUNET_MY_QueryParam
 281 GNUNET_MY_query_param_string (const char *ptr);
 282
 283 /**
 284   * Generate fixed-size query parameter with size determined
 285   * by variable type.
 286   *
 287   * @param x pointer to the query parameter to pass
 288   */
 289 #define GNUNET_MY_query_param_auto_from_type(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
 290
 291 /**
 292   * Generate query parameter for an RSA public key. The
 293   * database must contain a BLOB type in the respective position.
 294   *
 295   * @param x the query parameter to pass
 296   * @return array entry for the query parameters to use
 297   */
 298 struct GNUNET_MY_QueryParam
 299 GNUNET_MY_query_param_rsa_public_key (const struct 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 GNUNET_CRYPTO_RsaSignature *x);
 310
 311 /**
 312   * Generate query parameter for an absolute time value.
 313   * The database must store a 64-bit integer.
 314   *
 315   *@param x pointer to the query parameter to pass
 316   *@return array entry for the query parameters to use
 317   */
 318 struct GNUNET_MY_QueryParam
 319 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 320
 321
 322 /**
 323   * Generate query parameter for an absolute time value.
 324   * The database must store a 64-bit integer.
 325   *
 326   *@param x pointer to the query parameter to pass
 327   */
 328 struct GNUNET_MY_QueryParam
 329 GNUNET_MY_query_param_absolute_time_nbo (const struct 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(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
 363
 364
 365 /**
 366  * Variable-size result expected
 367  *
 368  * @param[out] dst where to store the result, allocated
 369  * @param[out] sptr where to store the size of @a dst
 370  * @return array entru for the result specification to use
 371  */
 372 struct GNUNET_MY_ResultSpec
 373 GNUNET_MY_result_spec_variable_size (void **dst,
 374                                      size_t *ptr_size);
 375
 376 /**
 377  * RSA public key expected
 378  *
 379  * @param name name of the field in the table
 380  * @param[out] rsa where to store the result
 381  * @return array entry for the result specification to use
 382  */
 383 struct GNUNET_MY_ResultSpec
 384 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 385
 386
 387 /**
 388  * RSA signature expected.
 389  *
 390  * @param[out] sig where to store the result;
 391  * @return array entry for the result specification to use
 392  */
 393 struct GNUNET_MY_ResultSpec
 394 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
 395
 396 /**
 397   * 0- terminated string exprected.
 398   *
 399   * @param[out] dst where to store the result, allocated
 400   * @return array entry for the result specification to use
 401   */
 402 struct GNUNET_MY_ResultSpec
 403 GNUNET_MY_result_spec_string (char **dst);
 404
 405 /**
 406   * Absolute time expected
 407   *
 408   * @param name name of the field in the table
 409   * @param[out] at where to store the result
 410   * @return array entry for the result specification to use
 411   */
 412 struct GNUNET_MY_ResultSpec
 413 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
 414
 415 /**
 416   * Absolute time in network byte order expected
 417   *
 418   * @param[out] at where to store the result
 419   * @return array entry for the result specification to use
 420   */
 421 struct GNUNET_MY_ResultSpec
 422 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
 423
 424 /**
 425   * uint16_t expected
 426   *
 427   * @param[out] u16 where to store the result
 428   * @return array entry for the result specification to use
 429   */
 430 struct GNUNET_MY_ResultSpec
 431 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
 432
 433 /**
 434   * uint32_t expected
 435   *
 436   * @param[out] u32 where to store the result
 437   * @return array entry for the result specification to use
 438   */
 439 struct GNUNET_MY_ResultSpec
 440 GNUNET_MY_result_spec_uint32 (uint32_t *u32);
 441
 442 /**
 443   * uint64_t expected.
 444   *
 445   * @param[out] u64 where to store the result
 446   * @return array entry for the result specification to use
 447   */
 448 struct GNUNET_MY_ResultSpec
 449 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
 450
 451
 452 /**
 453  * Extract results from a query result according to the given
 454  * specification.  Always fetches the next row.
 455  *
 456  * @param sh statement that returned results
 457  * @param rs specification to extract for
 458  * @return
 459  *  #GNUNET_YES if all results could be extracted
 460  *  #GNUNET_NO if there is no more data in the result set
 461  *  #GNUNET_SYSERR if a result was invalid
 462  */
 463 int
 464 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
 465                           struct GNUNET_MY_ResultSpec *specs);
 466
 467
 468 /**
 469  * Free all memory that was allocated in @a qp during
 470  * #GNUNET_MY_exect_prepared().
 471  *
 472  * @param qp query specification to clean up
 473  * @param qbind mysql query
 474  */
 475 void
 476 GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp,
 477                          MYSQL_BIND *qbind);
 478
 479
 480 /**
 481  * Free all memory that was allocated in @a rs during
 482  * #GNUNET_MY_extract_result().
 483  *
 484  * @param rs reult specification to clean up
 485  */
 486 void
 487 GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
 488
 489
 490 #if 0                           /* keep Emacsens' auto-indent happy */
 491 {
 492 #endif
 493 #ifdef __cplusplus
 494 }
 495 #endif
 496
 497 #endif
 498
 499 /** @} */  /* end of group */