| 1 |
/* sqlite.h -- Generic functions to simplify SQLite3 queries - data structures defined here |
| 2 |
* |
| 3 |
* GPLv2 only - Copyright (C) 2008 - 2012 |
| 4 |
* David Sommerseth <[email protected]> |
| 5 |
* |
| 6 |
* This program is free software; you can redistribute it and/or |
| 7 |
* modify it under the terms of the GNU General Public License |
| 8 |
* as published by the Free Software Foundation; version 2 |
| 9 |
* of the License. |
| 10 |
* |
| 11 |
* This program is distributed in the hope that it will be useful, |
| 12 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 |
* GNU General Public License for more details. |
| 15 |
* |
| 16 |
* You should have received a copy of the GNU General Public License |
| 17 |
* along with this program; if not, write to the Free Software |
| 18 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| 19 |
* |
| 20 |
*/ |
| 21 |
|
| 22 |
/** |
| 23 |
* @file sqlite.h |
| 24 |
* @author David Sommerseth <[email protected]> |
| 25 |
* @date 2008-08-06 |
| 26 |
* |
| 27 |
* @brief Generic functions to simplify the SQLite3 integration. |
| 28 |
* |
| 29 |
*/ |
| 30 |
|
| 31 |
#ifndef SQLITE_H_ |
| 32 |
# define SQLITE_H_ |
| 33 |
|
| 34 |
#include <stdarg.h> |
| 35 |
#ifdef HAVE_LIBXML2 |
| 36 |
# include <libxml/tree.h> |
| 37 |
#endif |
| 38 |
#include <eurephiadb_mapping.h> |
| 39 |
|
| 40 |
/** |
| 41 |
* Defines XML field types, used when extracting SQLite3 results directly into an xmlNode |
| 42 |
*/ |
| 43 |
typedef enum _xmlFieldType { XML_ATTR, XML_NODE } xmlFieldType; |
| 44 |
|
| 45 |
/** |
| 46 |
* Contains information about all fields/columns in an SQLite3 result. |
| 47 |
* It also keeps track over the length of the longest record/field value in the given field. |
| 48 |
* |
| 49 |
* This struct is built up as a dual-way chain pointer ring. So you need to keep an eye |
| 50 |
* on the fieldid value to know if you have gone one round or not. |
| 51 |
*/ |
| 52 |
typedef struct __sqlite_header { |
| 53 |
unsigned int fieldid; /**< Numeric field ID, starts at 1 and increases */ |
| 54 |
char *name; /**< Name of the field/column */ |
| 55 |
// char *type; |
| 56 |
size_t namelength; /**< Length of the field name */ |
| 57 |
size_t maxvaluelength; /**< Length of the longest record in this column */ |
| 58 |
struct __sqlite_header *next; /**< Pointer to the next field */ |
| 59 |
struct __sqlite_header *prev; /**< Pointer to the previous field */ |
| 60 |
} _sqlite_header; |
| 61 |
|
| 62 |
|
| 63 |
/** |
| 64 |
* Contains information about a particular data cell. That means one specific record |
| 65 |
* in one specific column. |
| 66 |
* |
| 67 |
* This struct is built up as a dual-way chain pointer ring. So you need to keep an eye |
| 68 |
* on the fieldid and/or tupleid value to know if you have gone one round or not. |
| 69 |
*/ |
| 70 |
typedef struct __sqlite_tuples { |
| 71 |
unsigned int tupleid; /**< Defines the "record number" */ |
| 72 |
unsigned int fieldid; /**< Defines the field ID this record belongs to */ |
| 73 |
char *value; /**< Pointer to the value of this field */ |
| 74 |
size_t length; /**< Length of the value of this field */ |
| 75 |
_sqlite_header *header; /**< A pointer to the header record with more info about this field/column */ |
| 76 |
struct __sqlite_tuples *nextfield; /**< Pointer to the same record, but the next field in it */ |
| 77 |
struct __sqlite_tuples *prevfield; /**< Pointer to the same record, but the previous field in it */ |
| 78 |
struct __sqlite_tuples *nexttuple; /**< Pointer to the same field, but the next record */ |
| 79 |
struct __sqlite_tuples *prevtuple; /**< Pointer to the same field, but the previous record */ |
| 80 |
} _sqlite_tuples; |
| 81 |
|
| 82 |
|
| 83 |
/** |
| 84 |
* Defines dbresult status types |
| 85 |
*/ |
| 86 |
typedef enum _QueryStatus { dbEMPTY, /**< No SQL query has been performed */ |
| 87 |
dbSUCCESS, /**< SQL query was successful */ |
| 88 |
dbERROR, /**< SQL query failed */ |
| 89 |
dbINVALID /**< Invalid dbresult (NULL value) */ |
| 90 |
} QueryStatus; |
| 91 |
|
| 92 |
/** |
| 93 |
* Defines error severities |
| 94 |
*/ |
| 95 |
typedef enum _ErrorSeverity { sevWARNING, /**< Query returns some data, but with errors in completeing it */ |
| 96 |
sevERROR, /**< Query could not complete, but may try again */ |
| 97 |
sevCRITICAL, /**< Query failed and there is no point of trying again */ |
| 98 |
sevPANIC /**< Query failed and eurephia should shutdown */ |
| 99 |
} ErrorSeverity; |
| 100 |
|
| 101 |
/** |
| 102 |
* The main definition of the dbresult strucutre. This structure keeps the |
| 103 |
* complete information about both fields and values of all records from a query. |
| 104 |
* |
| 105 |
* This structure keeps to "search" pointers. This is used when the sqlite_get_value() or |
| 106 |
* sqlite_xml_value() functions are called. These pointers will point at the last record being looked |
| 107 |
* up, so that if you do sequencial look ups, it will not loop through the whole chain from the start. |
| 108 |
* Even if you go a little bit back an forth, it will find the quickest way to avoid as many iterations |
| 109 |
* as possible. |
| 110 |
*/ |
| 111 |
typedef struct __sqlite_dbresult { |
| 112 |
QueryStatus status; /**< Indicates if the query was successful or not */ |
| 113 |
char *query; /**< Copy of the parsed SQL query */ |
| 114 |
|
| 115 |
// Query results |
| 116 |
_sqlite_tuples *tuples; /**< Pointer to the chains which contains field values */ |
| 117 |
_sqlite_header *headerrec; /**< Pointer to the chains with info about the field/columns */ |
| 118 |
size_t num_tuples; /**< Number of records received in the SELECT query */ |
| 119 |
size_t num_fields; /**< Number of fields for each record */ |
| 120 |
sqlite_int64 last_insert_id; /**< Reference to the last record from a INSERT INTO statement */ |
| 121 |
int affected_rows; /**< How many records where INSERTed, UPDATEd or DELETEd */ |
| 122 |
|
| 123 |
// "Search" pointers |
| 124 |
_sqlite_tuples *srch_tuples; /**< "Cache" of the last record being looked up */ |
| 125 |
_sqlite_header *srch_headerrec; /**< "Cache" of the last header record being looked up */ |
| 126 |
|
| 127 |
// Error handling |
| 128 |
ErrorSeverity errSeverity; /**< Severity of the error */ |
| 129 |
char *errMsg; /**< If status == dbERROR, a error message can be found here */ |
| 130 |
} dbresult; |
| 131 |
|
| 132 |
|
| 133 |
/** |
| 134 |
* Enumeration of suported SQL queries via the sqlite_query_mapped() API |
| 135 |
*/ |
| 136 |
typedef enum _SQLqueryType { SQL_SELECT, SQL_INSERT, SQL_UPDATE, SQL_DELETE } SQLqueryType; |
| 137 |
|
| 138 |
|
| 139 |
int sqlite_init_functions(eurephiaCTX *ctx); |
| 140 |
|
| 141 |
/** |
| 142 |
* Free up a dbresult structure. This is the public interface for the |
| 143 |
* internal function _sqlite_free_results() |
| 144 |
* |
| 145 |
* @param r Pointer to the dbresult to be freed |
| 146 |
*/ |
| 147 |
#define sqlite_free_results(r) { _sqlite_free_results(r); r = NULL; } |
| 148 |
void _sqlite_free_results(dbresult *); |
| 149 |
|
| 150 |
void sqlite_log_error(eurephiaCTX *ctx, dbresult *dbres ); |
| 151 |
#ifdef HAVE_LIBXML2 |
| 152 |
xmlNode *sqlite_log_error_xml(eurephiaCTX *ctx, dbresult *dbres ); |
| 153 |
#endif |
| 154 |
|
| 155 |
dbresult *sqlite_query(eurephiaCTX *ctx, const char *, ...); |
| 156 |
dbresult *sqlite_query_mapped(eurephiaCTX *ctx, SQLqueryType type, const char *sqlstub, |
| 157 |
eDBfieldMap *valMap, eDBfieldMap *whereMap, const char *sortkeys); |
| 158 |
#define sqlite_query_status(res) (QueryStatus) (res != NULL ? res->status : dbINVALID) |
| 159 |
char *sqlite_get_value(dbresult *res, int, int); |
| 160 |
#ifdef HAVE_LIBXML2 |
| 161 |
xmlNodePtr sqlite_xml_value(xmlNodePtr node, xmlFieldType xmltyp, char *name, dbresult *res, int row, int col); |
| 162 |
#endif |
| 163 |
void sqlite_dump_result(FILE *, dbresult *); |
| 164 |
|
| 165 |
|
| 166 |
/** |
| 167 |
* Retrieve number of tuples in a given dbresult structure |
| 168 |
* |
| 169 |
* @param dbres Pointer to a dbresult |
| 170 |
* |
| 171 |
* @return Returns number of rows/number of tuples in the result. |
| 172 |
*/ |
| 173 |
#define sqlite_get_numtuples(dbres) (dbres != NULL ? dbres->num_tuples : 0) |
| 174 |
|
| 175 |
|
| 176 |
/** |
| 177 |
* Retrieve number of affected tuples in current dbresult structure. This is only useful |
| 178 |
* when called on a result from INSERT, UPDATE or DELETE queries. |
| 179 |
* |
| 180 |
* @param dbres Pointer to a dbresult |
| 181 |
* |
| 182 |
* @return Returns number of rows/tuples affected by the SQL query |
| 183 |
*/ |
| 184 |
#define sqlite_get_affected_rows(dbres) (dbres != NULL ? dbres->affected_rows : 0) |
| 185 |
|
| 186 |
#endif /* !SQLITE_H_ */ |