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