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