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 it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 /**
  19  * @author Christian Grothoff
  20  *
  21  * @file
  22  * Helper library to access a MySQL database
  23  *
  24  * @defgroup mysql  MySQL library
  25  * Helper library to access a MySQL database.
  26  * @{
  27  */
  28 #ifndef GNUNET_MYSQL_LIB_H
  29 #define GNUNET_MYSQL_LIB_H
  30
  31 #include "gnunet_util_lib.h"
  32 #include <mysql/mysql.h>
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #if 0                           /* keep Emacsens' auto-indent happy */
  38 }
  39 #endif
  40 #endif
  41
  42
  43 /**
  44  * Mysql context.
  45  */
  46 struct GNUNET_MYSQL_Context;
  47
  48
  49 /**
  50  * Handle for a prepared statement.
  51  */
  52 struct GNUNET_MYSQL_StatementHandle;
  53
  54
  55 /**
  56  * Type of a callback that will be called for each
  57  * data set returned from MySQL.
  58  *
  59  * @param cls user-defined argument
  60  * @param num_values number of elements in values
  61  * @param values values returned by MySQL
  62  * @return #GNUNET_OK to continue iterating, #GNUNET_SYSERR to abort
  63  */
  64 typedef int
  65 (*GNUNET_MYSQL_DataProcessor) (void *cls,
  66                                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 sh prepared statement to introspect
 108  * @return MySQL statement handle, NULL on error
 109  */
 110 MYSQL_STMT *
 111 GNUNET_MYSQL_statement_get_stmt (struct GNUNET_MYSQL_StatementHandle *sh);
 112
 113
 114 /**
 115  * Prepare a statement.  Prepared statements are automatically discarded
 116  * when the MySQL context is destroyed.
 117  *
 118  * @param mc mysql context
 119  * @param query query text
 120  * @return prepared statement, NULL on error
 121  */
 122 struct GNUNET_MYSQL_StatementHandle *
 123 GNUNET_MYSQL_statement_prepare (struct GNUNET_MYSQL_Context *mc,
 124                                 const char *query);
 125
 126
 127 /**
 128  * Run a SQL statement.
 129  *
 130  * @param mc mysql context
 131  * @param sql SQL statement to run
 132  * @return #GNUNET_OK on success
 133  *         #GNUNET_SYSERR if there was a problem
 134  */
 135 int
 136 GNUNET_MYSQL_statement_run (struct GNUNET_MYSQL_Context *mc,
 137                             const char *sql);
 138
 139
 140 #if 0                           /* keep Emacsens' auto-indent happy */
 141 {
 142 #endif
 143 #ifdef __cplusplus
 144 }
 145 #endif
 146
 147 #endif
 148
 149 /** @} */  /* end of group */