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