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.
 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 /**
 125  * Run a prepared SELECT statement.
 126  *
 127  * @param mc mysql context
 128  * @param sh handle to SELECT statment
 129  * @param params parameters to the statement
 130  * @return TBD
 131  */
 132 int
 133 GNUNET_MY_exec_prepared (struct GNUNET_MYSQL_Context *mc,
 134                          struct GNUNET_MYSQL_StatementHandle *sh,
 135                          const struct GNUNET_MY_QueryParam *params);
 136
 137
 138 /**
 139  * Information we pass to #GNUNET_MY_extract_result() to
 140  * initialize the arguments of the prepared statement.
 141  */
 142 struct GNUNET_MY_ResultParam;
 143
 144
 145 /**
 146  * Function called to convert input argument into SQL parameters.
 147  *
 148  * @param cls closure
 149  * @param pq data about the query
 150  * @return -1 on error
 151  */
 152 typedef int
 153 (*GNUNET_MY_ResultConverter)(void *cls,
 154                              struct GNUNET_MY_QueryParam *qp,
 155                              MYSQL_BIND *results);
 156
 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   /**
 166    * Function to call for the type conversion.
 167    */
 168   GNUNET_MY_ResultConverter conv;
 169
 170   /**
 171    * Closure for @e conv.
 172    */
 173   void *conv_cls;
 174
 175   /**
 176    * Destination for the data.
 177    */
 178   void *dst;
 179
 180   /**
 181    * Allowed size for the data, 0 for variable-size
 182    * (in this case, the type of @e dst is a `void **`
 183    * and we need to allocate a buffer of the right size).
 184    */
 185   size_t dst_size;
 186
 187   /**
 188    * Where to store actual size of the result.
 189    */
 190   size_t *result_size;
 191
 192 };
 193
 194
 195 /**
 196  * End of result speceter specification.
 197  *
 198  * @return array last entry for the result specification to use
 199  */
 200 #define GNUNET_MY_result_spec_end { NULL, NULL, NULL, 0, NULL }
 201
 202
 203
 204 /**
 205  * Obtain fixed size result of @a ptr_size bytes from
 206  * MySQL, store in already allocated buffer at @a ptr.
 207  *
 208  * @spec ptr where to write the result
 209  * @oaran ptr_size number of bytes available at @a ptr
 210  */
 211 struct GNUNET_MY_ResultSpec
 212 GNUNET_MY_result_spec_fixed_size (void *ptr,
 213                                   size_t ptr_size);
 214
 215
 216 /**
 217  * We expect a fixed-size result, with size determined by the type of `* dst`
 218  *
 219  * @spec name name of the field in the table
 220  * @spec dst point to where to store the result, type fits expected result size
 221  * @return array entry for the result specification to use
 222  */
 223 #define GNUNET_MY_result_spec_auto_from_type(dst) GNUNET_MY_result_spec_fixed_size ((dst), sizeof (*(dst)))
 224
 225 /**
 226  * FIXME.
 227  *
 228  */
 229 int
 230 GNUNET_MY_extract_result (MYSQL_BIND * result,
 231                           int row,
 232                           struct GNUNET_MY_ResultSpec *specs);
 233
 234 #if 0                           /* keep Emacsens' auto-indent happy */
 235 {
 236 #endif
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif
 242
 243 /** @} */  /* end of group */