src/include/gnunet_mysql_lib.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2012 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20 /**
  21  * @file include/gnunet_mysql_lib.h
  22  * @brief library to help with access to a MySQL database
  23  * @author Christian Grothoff
  24  */
  25 #ifndef GNUNET_MYSQL_LIB_H
  26 #define GNUNET_MYSQL_LIB_H
  27
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_bandwidth_lib.h"
  30 #include "gnunet_statistics_service.h"
  31 #include <mysql/mysql.h>
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41
  42 /**
  43  * Mysql context.
  44  */
  45 struct GNUNET_MYSQL_Context;
  46
  47
  48 /**
  49  * Handle for a prepared statement.
  50  */
  51 struct GNUNET_MYSQL_StatementHandle;
  52
  53
  54 /**
  55  * Type of a callback that will be called for each
  56  * data set returned from MySQL.
  57  *
  58  * @param cls user-defined argument
  59  * @param num_values number of elements in values
  60  * @param values values returned by MySQL
  61  * @return GNUNET_OK to continue iterating, GNUNET_SYSERR to abort
  62  */
  63 typedef int (*GNUNET_MYSQL_DataProcessor) (void *cls, unsigned int num_values,
  64                                            MYSQL_BIND * values);
  65
  66
  67 /**
  68  * Create a mysql context.
  69  *
  70  * @param cfg configuration
  71  * @param section configuration section to use to get MySQL configuration options
  72  * @return the mysql context
  73  */
  74 struct GNUNET_MYSQL_Context *
  75 GNUNET_MYSQL_context_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
  76                              const char *section);
  77
  78
  79 /**
  80  * Destroy a mysql context.  Also frees all associated prepared statements.
  81  *
  82  * @param mc context to destroy
  83  */
  84 void
  85 GNUNET_MYSQL_context_destroy (struct GNUNET_MYSQL_Context *mc);
  86
  87
  88 /**
  89  * Close database connection and all prepared statements (we got a DB
  90  * error).  The connection will automatically be re-opened and
  91  * statements will be re-prepared if they are needed again later.
  92  *
  93  * @param mc mysql context
  94  */
  95 void
  96 GNUNET_MYSQL_statements_invalidate (struct GNUNET_MYSQL_Context *mc);
  97
  98
  99 /**
 100  * Get internal handle for a prepared statement.  This function should rarely
 101  * be used, and if, with caution!  On failures during the interaction with
 102  * the handle, you must call 'GNUNET_MYSQL_statements_invalidate'!
 103  *
 104  * @param mc mysql context
 105  * @param sh prepared statement to introspect
 106  * @return MySQL statement handle, NULL on error
 107  */
 108 MYSQL_STMT *
 109 GNUNET_MYSQL_statement_get_stmt (struct GNUNET_MYSQL_Context *mc,
 110                                  struct GNUNET_MYSQL_StatementHandle *sh);
 111
 112
 113 /**
 114  * Prepare a statement.  Prepared statements are automatically discarded
 115  * when the MySQL context is destroyed.
 116  *
 117  * @param mc mysql context
 118  * @param query query text
 119  * @return prepared statement, NULL on error
 120  */
 121 struct GNUNET_MYSQL_StatementHandle *
 122 GNUNET_MYSQL_statement_prepare (struct GNUNET_MYSQL_Context *mc,
 123                                 const char *query);
 124
 125
 126 /**
 127  * Run a SQL statement.
 128  *
 129  * @param mc mysql context
 130  * @param sql SQL statement to run
 131  * @return GNUNET_OK on success
 132  *         GNUNET_SYSERR if there was a problem
 133  */
 134 int
 135 GNUNET_MYSQL_statement_run (struct GNUNET_MYSQL_Context *mc,
 136                             const char *sql);
 137
 138
 139 /**
 140  * Run a prepared SELECT statement.
 141  *
 142  * @param mc mysql context
 143  * @param sh handle to SELECT statment
 144  * @param result_size number of elements in results array
 145  * @param results pointer to already initialized MYSQL_BIND
 146  *        array (of sufficient size) for passing results
 147  * @param processor function to call on each result
 148  * @param processor_cls extra argument to processor
 149  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 150  *        values (size + buffer-reference for pointers); terminated
 151  *        with "-1"
 152  * @return GNUNET_SYSERR on error, otherwise
 153  *         the number of successfully affected (or queried) rows
 154  */
 155 int
 156 GNUNET_MYSQL_statement_run_prepared_select (struct GNUNET_MYSQL_Context *mc,
 157                                             struct GNUNET_MYSQL_StatementHandle *sh,
 158                                             unsigned int result_size, MYSQL_BIND * results,
 159                                             GNUNET_MYSQL_DataProcessor processor,
 160                                             void *processor_cls, ...);
 161
 162
 163 /**
 164  * Run a prepared SELECT statement.
 165  *
 166  * @param mc mysql context
 167  * @param s statement to run
 168  * @param result_size number of elements in results array
 169  * @param results pointer to already initialized MYSQL_BIND
 170  *        array (of sufficient size) for passing results
 171  * @param processor function to call on each result
 172  * @param processor_cls extra argument to processor
 173  * @param ap pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 174  *        values (size + buffer-reference for pointers); terminated
 175  *        with "-1"
 176  * @return GNUNET_SYSERR on error, otherwise
 177  *         the number of successfully affected (or queried) rows
 178  */
 179 int
 180 GNUNET_MYSQL_statement_run_prepared_select_va (struct GNUNET_MYSQL_Context *mc,
 181                                                struct GNUNET_MYSQL_StatementHandle *s,
 182                                                unsigned int result_size,
 183                                                MYSQL_BIND * results,
 184                                                GNUNET_MYSQL_DataProcessor processor,
 185                                                void *processor_cls,
 186                                                va_list ap);
 187
 188
 189 /**
 190  * Run a prepared statement that does NOT produce results.
 191  *
 192  * @param mc mysql context
 193  * @param sh handle to statment
 194  * @param insert_id NULL or address where to store the row ID of whatever
 195  *        was inserted (only for INSERT statements!)
 196  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 197  *        values (size + buffer-reference for pointers); terminated
 198  *        with "-1"
 199  * @return GNUNET_SYSERR on error, otherwise
 200  *         the number of successfully affected rows
 201  */
 202 int
 203 GNUNET_MYSQL_statement_run_prepared (struct GNUNET_MYSQL_Context *mc,
 204                                      struct GNUNET_MYSQL_StatementHandle *sh,
 205                                      unsigned long long *insert_id, ...);
 206
 207
 208 #if 0                           /* keep Emacsens' auto-indent happy */
 209 {
 210 #endif
 211 #ifdef __cplusplus
 212 }
 213 #endif
 214
 215 /* end of gnunet_mysql_lib.h */
 216 #endif