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 /**
  16  * @author Christian Grothoff
  17  *
  18  * @file
  19  * Helper library to access a MySQL database
  20  *
  21  * @defgroup mysql  MySQL library
  22  * Helper library to access a MySQL database.
  23  * @{
  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
  62 (*GNUNET_MYSQL_DataProcessor) (void *cls,
  63                                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  * Close database connection and all prepared statements (we got a DB
  90  * error).  The connection will automatically be re-opened and
  91  * statements will be re-prepared if they are needed again later.
  92  *
  93  * @param mc mysql context
  94  */
  95 void
  96 GNUNET_MYSQL_statements_invalidate (struct GNUNET_MYSQL_Context *mc);
  97
  98
  99 /**
 100  * Get internal handle for a prepared statement.  This function should rarely
 101  * be used, and if, with caution!  On failures during the interaction with
 102  * the handle, you must call #GNUNET_MYSQL_statements_invalidate()!
 103  *
 104  * @param sh prepared statement to introspect
 105  * @return MySQL statement handle, NULL on error
 106  */
 107 MYSQL_STMT *
 108 GNUNET_MYSQL_statement_get_stmt (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 #if 0                           /* keep Emacsens' auto-indent happy */
 138 {
 139 #endif
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144 #endif
 145
 146 /** @} */  /* end of group */