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  * Prepare a statement.  Prepared statements are automatically discarded
  90  * when the MySQL context is destroyed.
  91  *
  92  * @param mc mysql context
  93  * @param query query text
  94  * @return prepared statement, NULL on error
  95  */
  96 struct GNUNET_MYSQL_StatementHandle *
  97 GNUNET_MYSQL_statement_prepare (struct GNUNET_MYSQL_Context *mc,
  98                                 const char *query);
  99
 100
 101 /**
 102  * Run a SQL statement.
 103  *
 104  * @param mc mysql context
 105  * @param sql SQL statement to run
 106  * @return GNUNET_OK on success
 107  *         GNUNET_SYSERR if there was a problem
 108  */
 109 int
 110 GNUNET_MYSQL_statement_run (struct GNUNET_MYSQL_Context *mc,
 111                             const char *sql);
 112
 113
 114 /**
 115  * Run a prepared SELECT statement.
 116  *
 117  * @param mc mysql context
 118  * @param sh handle to SELECT statment
 119  * @param result_size number of elements in results array
 120  * @param results pointer to already initialized MYSQL_BIND
 121  *        array (of sufficient size) for passing results
 122  * @param processor function to call on each result
 123  * @param processor_cls extra argument to processor
 124  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 125  *        values (size + buffer-reference for pointers); terminated
 126  *        with "-1"
 127  * @return GNUNET_SYSERR on error, otherwise
 128  *         the number of successfully affected (or queried) rows
 129  */
 130 int
 131 GNUNET_MYSQL_statement_run_prepared_select (struct GNUNET_MYSQL_Context *mc,
 132                                             struct GNUNET_MYSQL_StatementHandle *sh,
 133                                             unsigned int result_size, MYSQL_BIND * results,
 134                                             GNUNET_MYSQL_DataProcessor processor,
 135                                             void *processor_cls, ...);
 136
 137
 138 /**
 139  * Run a prepared statement that does NOT produce results.
 140  *
 141  * @param mc mysql context
 142  * @param sh handle to statment
 143  * @param insert_id NULL or address where to store the row ID of whatever
 144  *        was inserted (only for INSERT statements!)
 145  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 146  *        values (size + buffer-reference for pointers); terminated
 147  *        with "-1"
 148  * @return GNUNET_SYSERR on error, otherwise
 149  *         the number of successfully affected rows
 150  */
 151 int
 152 GNUNET_MYSQL_statement_run_prepared (struct GNUNET_MYSQL_Context *mc,
 153                                      struct GNUNET_MYSQL_StatementHandle *sh,
 154                                      unsigned long long *insert_id, ...);
 155
 156
 157 #if 0                           /* keep Emacsens' auto-indent happy */
 158 {
 159 #endif
 160 #ifdef __cplusplus
 161 }
 162 #endif
 163
 164 /* end of gnunet_mysql_lib.h */
 165 #endif