src/include/gnunet_my_lib.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2012 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20 /**
  21  * @author Christian Grothoff
  22  *
  23  * @file
  24  * Helper library to access a MySQL database
  25  *
  26  * @defgroup mysql  MySQL library
  27  * Helper library to access a MySQL database.
  28  * @{
  29  */
  30 #ifndef GNUNET_MY_LIB_H
  31 #define GNUNET_MY_LIB_H
  32
  33 #include "gnunet_util_lib.h"
  34 #include "gnunet_mysql_lib.h"
  35 #include <mysql/mysql.h>
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  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                            struct GNUNET_MY_QueryParam *qp);
  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   /**
  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 /**
 119  * End of query parameter specification.
 120  *
 121  * @return array last entry for the result specification to use
 122  */
 123 #define GNUNET_MY_query_param_end { NULL, NULL, NULL, 0, NULL, 0 }
 124
 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  * Run a prepared SELECT statement.
 140  *
 141  * @param mc mysql context
 142  * @param sh handle to SELECT statment
 143  * @param params parameters to the statement
 144  * @return TBD
 145  */
 146 int
 147 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
 148                          struct GNUNET_MYSQL_StatementHandle *sh,
 149                          const struct GNUNET_MY_QueryParam *params);
 150
 151
 152 /**
 153  * Information we pass to #GNUNET_MY_extract_result() to
 154  * initialize the arguments of the prepared statement.
 155  */
 156 struct GNUNET_MY_ResultParam;
 157
 158 /**
 159  * Information we pass to #GNUNET_MY_extract_result() to
 160  * initialize the arguments of the prepared statement.
 161  */
 162 struct GNUNET_MY_ResultSpec;
 163
 164 /**
 165  * Function called to convert input argument into SQL parameters.
 166  *
 167  * @param cls closure
 168  * @param[in,out] rs
 169  * @param stmt the mysql statement that is being run
 170  * @param column the column that is being processed
 171  * @param[out] results
 172  * @return -1 on error
 173  */
 174 typedef int
 175 (*GNUNET_MY_ResultConverter)(void *cls,
 176                              struct GNUNET_MY_ResultSpec *rs,
 177                              MYSQL_STMT *stmt,
 178                              unsigned int column,
 179                              MYSQL_BIND *results);
 180
 181 /**
 182  * Function called to cleanup result data.
 183  *
 184  * @param cls closure
 185  * @param rs spec to clean up
 186  */
 187 typedef void
 188 (*GNUNET_MY_ResultCleanup)(void *cls,
 189                            struct GNUNET_MY_ResultSpec *rs);
 190
 191
 192 /**
 193  * Information we pass to #GNUNET_MY_extract_result() to
 194  * initialize the arguments of the prepared statement.
 195  */
 196 struct GNUNET_MY_ResultSpec
 197 {
 198
 199   /**
 200    * Function to call to initialize the MYSQL_BIND array.
 201    */
 202   GNUNET_MY_ResultConverter pre_conv;
 203
 204   /**
 205    * Function to call for converting the result. Can be NULL.
 206    */
 207   GNUNET_MY_ResultConverter post_conv;
 208
 209     /**
 210    * Function to call for cleaning up the result. Can be NULL.
 211    */
 212   GNUNET_MY_ResultCleanup cleaner;
 213
 214   /**
 215    * Closure for @e conv.
 216    */
 217   void *conv_cls;
 218
 219   /**
 220    * Destination for the data.
 221    */
 222   void *dst;
 223
 224   /**
 225    * Allowed size for the data, 0 for variable-size
 226    * (in this case, the type of @e dst is a `void **`
 227    * and we need to allocate a buffer of the right size).
 228    */
 229   size_t dst_size;
 230
 231   /**
 232    * Where to store actual size of the result.
 233    */
 234   size_t *result_size;
 235
 236   /**
 237    * How many fields does this result specification occupy
 238    * in the result returned by MySQL.
 239    */
 240   unsigned int num_fields;
 241
 242   /**
 243    * Location where we temporarily store the output buffer
 244    * length from MySQL.  Internal to libgnunetmy.
 245    */
 246   unsigned long mysql_bind_output_length;
 247
 248 };
 249
 250
 251 /**
 252  * End of result speceter specification.
 253  *
 254  * @return array last entry for the result specification to use
 255  */
 256 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL, 0 }
 257
 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(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
 286
 287 /**
 288   * Generate query parameter for an RSA public key. The
 289   * database must contain a BLOB type in the respective position.
 290   *
 291   * @param x the query parameter to pass
 292   * @return array entry for the query parameters to use
 293   */
 294 struct GNUNET_MY_QueryParam
 295 GNUNET_MY_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
 296
 297 /**
 298   * Generate query parameter for an RSA signature. The
 299   * database must contain a BLOB type in the respective position
 300   *
 301   *@param x the query parameter to pass
 302   *@return array entry for the query parameters to use
 303   */
 304 struct GNUNET_MY_QueryParam
 305 GNUNET_MY_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
 306
 307 /**q
 308   * Generate query parameter for an absolute time value.
 309   * The database must store a 64-bit integer.
 310   *
 311   *@param x pointer to the query parameter to pass
 312   *@return array entry for the query parameters to use
 313   */
 314 struct GNUNET_MY_QueryParam
 315 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 316
 317 /**
 318   * Generate query parameter for an absolute time value.
 319   * The database must store a 64-bit integer.
 320   *
 321   *@param x pointer to the query parameter to pass
 322   */
 323 struct GNUNET_MY_QueryParam
 324 GNUNET_MY_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
 325
 326 /**
 327   * Generate query parameter for an uint16_t in host byte order.
 328   *
 329   * @param x pointer to the query parameter to pass
 330   */
 331 struct GNUNET_MY_QueryParam
 332 GNUNET_MY_query_param_uint16 (const uint16_t *x);
 333
 334 /**
 335   * Generate query parameter for an uint32_t in host byte order
 336   *
 337   *@param x pointer to the query parameter to pass
 338   */
 339 struct GNUNET_MY_QueryParam
 340 GNUNET_MY_query_param_uint32 (const uint32_t *x);
 341
 342 /**
 343   * Generate query parameter for an uint64_t in host byte order
 344   *
 345   *@param x pointer to the query parameter to pass
 346   */
 347 struct GNUNET_MY_QueryParam
 348 GNUNET_MY_query_param_uint64 (const uint64_t *x);
 349
 350 /**
 351  * We expect a fixed-size result, with size determined by the type of `* dst`
 352  *
 353  * @spec name name of the field in the table
 354  * @spec dst point to where to store the result, type fits expected result size
 355  * @return array entry for the result specification to use
 356  */
 357 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
 358
 359
 360 /**
 361  * FIXME.
 362  *
 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   * RSA public key expected
 377   *
 378   * @param name name of the field in the table
 379   * @param[out] rsa where to store the result
 380   * @return array entry for the result specification to use
 381   */
 382 struct GNUNET_MY_ResultSpec
 383 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 384
 385 /**
 386   * RSA signature expected.
 387   *
 388   * @param[out] sig where to store the result;
 389   * @return array entry for the result specification to use
 390   */
 391 struct GNUNET_MY_ResultSpec
 392 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
 393
 394 /**
 395   * 0- terminated string exprected.
 396   *
 397   * @param[out] dst where to store the result, allocated
 398   * @return array entry for the result specification to use
 399   */
 400 struct GNUNET_MY_ResultSpec
 401 GNUNET_MY_result_spec_string (char **dst);
 402
 403 /**
 404   * Absolute time expected
 405   *
 406   * @param name name of the field in the table
 407   * @param[out] at where to store the result
 408   * @return array entry for the result specification to use
 409   */
 410 struct GNUNET_MY_ResultSpec
 411 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
 412
 413 /**
 414   * Absolute time in network byte order expected
 415   *
 416   * @param[out] at where to store the result
 417   * @return array entry for the result specification to use
 418   */
 419 struct GNUNET_MY_ResultSpec
 420 GNUNET_MY_result_spec_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
 421
 422 /**
 423   * uint16_t expected
 424   *
 425   * @param[out] u16 where to store the result
 426   * @return array entry for the result specification to use
 427   */
 428 struct GNUNET_MY_ResultSpec
 429 GNUNET_MY_result_spec_uint16 (uint16_t *u16);
 430
 431 /**
 432   * uint32_t expected
 433   *
 434   * @param[out] u32 where to store the result
 435   * @return array entry for the result specification to use
 436   */
 437 struct GNUNET_MY_ResultSpec
 438 GNUNET_MY_result_spec_uint32 (uint32_t *u32);
 439
 440 /**
 441   * uint64_t expected.
 442   *
 443   * @param[out] u64 where to store the result
 444   * @return array entry for the result specification to use
 445   */
 446 struct GNUNET_MY_ResultSpec
 447 GNUNET_MY_result_spec_uint64 (uint64_t *u64);
 448
 449
 450 /**
 451  * Extract results from a query result according to the given
 452  * specification.  Always fetches the next row.
 453  *
 454  * @param sh statement that returned results
 455  * @param rs specification to extract for
 456  * @return
 457  *  #GNUNET_YES if all results could be extracted
 458  *  #GNUNET_NO if there is no more data in the result set
 459  *  #GNUNET_SYSERR if a result was invalid
 460  */
 461 int
 462 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
 463                           struct GNUNET_MY_ResultSpec *specs);
 464
 465
 466 /**
 467  * Free all memory that was allocated in @a qp during
 468  * #GNUNET_MY_exect_prepared().
 469  *
 470  * @param qp query specification to clean up
 471  */
 472 void
 473 GNUNET_MY_cleanup_query (struct GNUNET_MY_QueryParam *qp);
 474
 475
 476 /**
 477  * Free all memory that was allocated in @a rs during
 478  * #GNUNET_MY_extract_result().
 479  *
 480  * @param rs reult specification to clean up
 481  */
 482 void
 483 GNUNET_MY_cleanup_result (struct GNUNET_MY_ResultSpec *rs);
 484
 485
 486 #if 0                           /* keep Emacsens' auto-indent happy */
 487 {
 488 #endif
 489 #ifdef __cplusplus
 490 }
 491 #endif
 492
 493 #endif
 494
 495 /** @} */  /* end of group */