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 /**
 104  * End of query parameter specification.
 105  *
 106  * @return array last entry for the result specification to use
 107  */
 108 #define GNUNET_MY_query_param_end { NULL, NULL, 0, NULL, 0 }
 109
 110
 111
 112 /**
 113  * Generate query parameter for a buffer @a ptr of
 114  * @a ptr_size bytes.FG
 115  *
 116  * @param ptr pointer to the query parameter to pass
 117  * @oaran ptr_size number of bytes in @a ptr
 118  */
 119 struct GNUNET_MY_QueryParam
 120 GNUNET_MY_query_param_fixed_size (const void *ptr,
 121                                   size_t ptr_size);
 122
 123 /**
 124  * Run a prepared SELECT statement.
 125  *
 126  * @param mc mysql context
 127  * @param sh handle to SELECT statment
 128  * @param params parameters to the statement
 129  * @return TBD
 130  */
 131 int
 132 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
 133                          struct GNUNET_MYSQL_StatementHandle *sh,
 134                          const struct GNUNET_MY_QueryParam *params);
 135
 136
 137 /**
 138  * Information we pass to #GNUNET_MY_extract_result() to
 139  * initialize the arguments of the prepared statement.
 140  */
 141 struct GNUNET_MY_ResultParam;
 142
 143 /**
 144  * Information we pass to #GNUNET_MY_extract_result() to
 145  * initialize the arguments of the prepared statement.
 146  */
 147 struct GNUNET_MY_ResultSpec;
 148
 149 /**
 150  * Function called to convert input argument into SQL parameters.
 151  *
 152  * @param cls closure
 153  * @param pq data about the query
 154  * @return -1 on error
 155  */
 156 typedef int
 157 (*GNUNET_MY_ResultConverter)(void *cls,
 158                              struct GNUNET_MY_ResultSpec *rs,
 159                              MYSQL_BIND *results);
 160
 161 /**
 162  * Information we pass to #GNUNET_MY_extract_result() to
 163  * initialize the arguments of the prepared statement.
 164  */
 165 struct GNUNET_MY_ResultSpec
 166 {
 167
 168   /**
 169    * Function to call for the type conversion.
 170    */
 171   GNUNET_MY_ResultConverter conv;
 172
 173   /**
 174    * Closure for @e conv.
 175    */
 176   void *conv_cls;
 177
 178   /**
 179    * Destination for the data.
 180    */
 181   void *dst;
 182
 183   /**
 184    * Allowed size for the data, 0 for variable-size
 185    * (in this case, the type of @e dst is a `void **`
 186    * and we need to allocate a buffer of the right size).
 187    */
 188   size_t dst_size;
 189
 190   /**
 191    * Where to store actual size of the result.
 192    */
 193   size_t *result_size;
 194
 195 };
 196
 197
 198 /**
 199  * End of result speceter specification.
 200  *
 201  * @return array last entry for the result specification to use
 202  */
 203 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL }
 204
 205
 206
 207 /**
 208  * Obtain fixed size result of @a ptr_size bytes from
 209  * MySQL, store in already allocated buffer at @a ptr.
 210  *
 211  * @spec ptr where to write the result
 212  * @oaran ptr_size number of bytes available at @a ptr
 213  */
 214 struct GNUNET_MY_ResultSpec
 215 GNUNET_MY_result_spec_fixed_size (void *ptr,
 216                                   size_t ptr_size);
 217
 218 /**
 219   * Generate query parameter for a string
 220   *
 221   *@param ptr pointer to the string query parameter to pass
 222   */
 223 struct GNUNET_MY_QueryParam
 224 GNUNET_MY_query_param_string (const char *ptr);
 225
 226 /**
 227   * Generate fixed-size query parameter with size determined
 228   * by variable type.
 229   *
 230   * @param x pointer to the query parameter to pass
 231   */
 232 #define GNUNET_MY_query_param_auto_from_type(x) GNUNET_MY_query_param_fixed_size ((x), sizeof (*(x)))
 233
 234 /**
 235   * Generate query parameter for an RSA public key. The
 236   * database must contain a BLOB type in the respective position.
 237   *
 238   * @param x the query parameter to pass
 239   * @return array entry for the query parameters to use
 240   */
 241 struct GNUNET_MY_QueryParam
 242 GNUNET_MY_query_param_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *x);
 243
 244 /**
 245   * Generate query parameter for an RSA signature. The
 246   * database must contain a BLOB type in the respective position
 247   *
 248   *@param x the query parameter to pass
 249   *@return array entry for the query parameters to use
 250   */
 251 struct GNUNET_MY_QueryParam
 252 GNUNET_MY_query_param_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *x);
 253
 254 /**
 255   * Generate query parameter for an absolute time value.
 256   * The database must store a 64-bit integer.
 257   *
 258   *@param x pointer to the query parameter to pass
 259   *@return array entry for the query parameters to use
 260   */
 261 struct GNUNET_MY_QueryParam
 262 GNUNET_MY_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 263
 264 /**
 265   * Generate query parameter for an absolute time value.
 266   * The database must store a 64-bit integer.
 267   *
 268   *@param x pointer to the query parameter to pass
 269   */
 270 struct GNUNET_MY_QueryParam
 271 GNUNET_MY_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x);
 272
 273 /**
 274   * Generate query parameter for an uint16_t in host byte order.
 275   *
 276   * @param x pointer to the query parameter to pass
 277   */
 278 struct GNUNET_MY_QueryParam
 279 GNUNET_MY_query_param_uint16 (const uint16_t *x);
 280
 281 /**
 282   * Generate query parameter for an uint32_t in host byte order
 283   *
 284   *@param x pointer to the query parameter to pass
 285   */
 286 struct GNUNET_MY_QueryParam
 287 GNUNET_MY_query_param_uint32 (const uint32_t *x);
 288
 289 /**
 290   * Generate query parameter for an uint64_t in host byte order
 291   *
 292   *@param x pointer to the query parameter to pass
 293   */
 294 struct GNUNET_MY_QueryParam
 295 GNUNET_MY_query_param_uint64 (const uint64_t *x);
 296
 297 /**
 298  * We expect a fixed-size result, with size determined by the type of `* dst`
 299  *
 300  * @spec name name of the field in the table
 301  * @spec dst point to where to store the result, type fits expected result size
 302  * @return array entry for the result specification to use
 303  */
 304 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
 305
 306
 307 /**
 308  * FIXME.
 309  *
 310  */
 311
 312  /**
 313   * Variable-size result expected
 314   *
 315   * @param[out] dst where to store the result, allocated
 316   * @param[out] sptr where to store the size of @a dst
 317   * @return array entru for the result specification to use
 318   */
 319 struct GNUNET_MY_ResultSpec
 320 GNUNET_MY_result_spec_variable_size (void **dst,
 321                                     size_t *ptr_size);
 322 /**
 323   * RSA public key expected
 324   *
 325   * @param name name of the field in the table
 326   * @param[out] rsa where to store the result
 327   * @return array entry for the result specification to use
 328   */
 329 struct GNUNET_MY_ResultSpec
 330 GNUNET_MY_result_spec_rsa_public_key (struct GNUNET_CRYPTO_RsaPublicKey **rsa);
 331
 332 /**
 333   * RSA signature expected.
 334   *
 335   * @param[out] sig where to store the result;
 336   * @return array entry for the result specification to use
 337   */
 338 struct GNUNET_MY_ResultSpec
 339 GNUNET_MY_result_spec_rsa_signature (struct GNUNET_CRYPTO_RsaSignature **sig);
 340
 341 /**
 342   * 0- terminated string exprected.
 343   *
 344   * @param[out] dst where to store the result, allocated
 345   * @return array entry for the result specification to use
 346   */
 347 struct GNUNET_MY_ResultSpec
 348 GNUNET_MY_result_spec_string (char **dst);
 349
 350 /**
 351   * Absolute time expected
 352   *
 353   * @param name name of the field in the table
 354   * @param[out] at where to store the result
 355   * @return array entry for the result specification to use
 356   */
 357 struct GNUNET_MY_ResultSpec
 358 GNUNET_MY_result_spec_absolute_time (struct GNUNET_TIME_Absolute *at);
 359
 360 /**
 361   * Absolute time in network byte order expected
 362   *
 363   * @param[out] at 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_absolute_time_nbo (struct GNUNET_TIME_AbsoluteNBO *at);
 368
 369 /**
 370   * uint16_t expected
 371   *
 372   * @param[out] u16 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_uint16 (uint16_t *u16);
 377
 378 /**
 379   * uint32_t expected
 380   *
 381   * @param[out] u32 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_uint32 (uint32_t *u32);
 386
 387 /**
 388   * uint64_t expected.
 389   *
 390   * @param[out] u64 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_uint64 (uint64_t *u64);
 395
 396 int
 397 GNUNET_MY_extract_result (struct GNUNET_MYSQL_StatementHandle *sh,
 398                           struct GNUNET_MY_QueryParam *qp,
 399                           struct GNUNET_MY_ResultSpec *specs,
 400                           int row);
 401
 402 #if 0                           /* keep Emacsens' auto-indent happy */
 403 {
 404 #endif
 405 #ifdef __cplusplus
 406 }
 407 #endif
 408
 409 #endif
 410
 411 /** @} */  /* end of group */