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
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40
  41 /**
  42  * Mysql context.
  43  */
  44 struct GNUNET_MYSQL_Context;
  45
  46
  47 /**
  48  * Handle for a prepared statement.
  49  */
  50 struct GNUNET_MYSQL_StatementHandle;
  51
  52
  53 /**
  54  * Type of a callback that will be called for each
  55  * data set returned from MySQL.
  56  *
  57  * @param cls user-defined argument
  58  * @param num_values number of elements in values
  59  * @param values values returned by MySQL
  60  * @return GNUNET_OK to continue iterating, GNUNET_SYSERR to abort
  61  */
  62 typedef int (*GNUNET_MYSQL_DataProcessor) (void *cls, unsigned int num_values,
  63                                            MYSQL_BIND * values);
  64
  65
  66 /**
  67  * Create a mysql context.
  68  *
  69  * @param cfg configuration
  70  * @param section configuration section to use to get MySQL configuration options
  71  * @return the mysql context
  72  */
  73 struct GNUNET_MYSQL_Context *
  74 GNUNET_MYSQL_context_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
  75                              const char *section);
  76
  77
  78 /**
  79  * Destroy a mysql context.  Also frees all associated prepared statements.
  80  *
  81  * @param mc context to destroy
  82  */
  83 void
  84 GNUNET_MYSQL_context_destroy (struct GNUNET_MYSQL_Context *mc);
  85
  86
  87 /**
  88  * Prepare a statement.  Prepared statements are automatically discarded
  89  * when the MySQL context is destroyed.
  90  *
  91  * @param mc mysql context
  92  * @param query query text
  93  * @return prepared statement, NULL on error
  94  */
  95 struct GNUNET_MYSQL_StatementHandle *
  96 GNUNET_MYSQL_statement_prepare (struct GNUNET_MYSQL_Context *mc,
  97                                 const char *query);
  98
  99
 100 /**
 101  * Run a SQL statement.
 102  *
 103  * @param mc mysql context
 104  * @param sql SQL statement to run
 105  * @return GNUNET_OK on success
 106  *         GNUNET_SYSERR if there was a problem
 107  */
 108 int
 109 GNUNET_MYSQL_statement_run (struct GNUNET_MYSQL_Context *mc,
 110                             const char *sql);
 111
 112
 113 /**
 114  * Run a prepared SELECT statement.
 115  *
 116  * @param mc mysql context
 117  * @param sh handle to SELECT statment
 118  * @param result_size number of elements in results array
 119  * @param results pointer to already initialized MYSQL_BIND
 120  *        array (of sufficient size) for passing results
 121  * @param processor function to call on each result
 122  * @param processor_cls extra argument to processor
 123  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 124  *        values (size + buffer-reference for pointers); terminated
 125  *        with "-1"
 126  * @return GNUNET_SYSERR on error, otherwise
 127  *         the number of successfully affected (or queried) rows
 128  */
 129 int
 130 GNUNET_MYSQL_statement_run_prepared_select (struct GNUNET_MYSQL_Context *mc,
 131                                             struct GNUNET_MYSQL_StatementHandle *sh,
 132                                             unsigned int result_size, MYSQL_BIND * results,
 133                                             GNUNET_MYSQL_DataProcessor processor,
 134                                             void *processor_cls, ...);
 135
 136
 137 /**
 138  * Run a prepared statement that does NOT produce results.
 139  *
 140  * @param mc mysql context
 141  * @param sh handle to statment
 142  * @param insert_id NULL or address where to store the row ID of whatever
 143  *        was inserted (only for INSERT statements!)
 144  * @param ... pairs and triplets of "MYSQL_TYPE_XXX" keys and their respective
 145  *        values (size + buffer-reference for pointers); terminated
 146  *        with "-1"
 147  * @return GNUNET_SYSERR on error, otherwise
 148  *         the number of successfully affected rows
 149  */
 150 int
 151 GNUNET_MYSQL_statement_run_prepared (struct GNUNET_MYSQL_Context *mc,
 152                                      struct GNUNET_MYSQL_StatementHandle *sh,
 153                                      unsigned long long *insert_id, ...);
 154
 155
 156 #if 0                           /* keep Emacsens' auto-indent happy */
 157 {
 158 #endif
 159 #ifdef __cplusplus
 160 }
 161 #endif
 162
 163 /* end of gnunet_mysql_lib.h */
 164 #endif