Debian Codegraph @

database/sqlite/sqlite.h

raw
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_ */