daemon: Flush shunts before unloading plugins
[strongswan.git] / src / libstrongswan / database / database.h
1 /*
2 * Copyright (C) 2013 Tobias Brunner
3 * Copyright (C) 2008 Martin Willi
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup databasei database
19 * @{ @ingroup database
20 */
21
22 #ifndef DATABASE_H_
23 #define DATABASE_H_
24
25 typedef enum db_type_t db_type_t;
26 typedef enum db_driver_t db_driver_t;
27 typedef struct database_t database_t;
28
29 #include <collections/enumerator.h>
30
31 /**
32 * Database column types
33 */
34 enum db_type_t {
35 /** integer type, argument is an "int" */
36 DB_INT,
37 /** unsigned integer, argument is an "u_int" */
38 DB_UINT,
39 /** string type, argument is a "char*" */
40 DB_TEXT,
41 /** binary large object type, argument is a "chunk_t" */
42 DB_BLOB,
43 /** floating point, argument is a "double" */
44 DB_DOUBLE,
45 /** NULL, takes no argument */
46 DB_NULL,
47 };
48
49 /**
50 * Database implementation type.
51 */
52 enum db_driver_t {
53 /** matches to other databases */
54 DB_ANY = 0,
55 /** SQLite database */
56 DB_SQLITE,
57 /** MySQL database */
58 DB_MYSQL,
59 };
60
61 /**
62 * Names for db_driver_t
63 */
64 extern enum_name_t *db_driver_names;
65
66 /**
67 * Interface for a database implementation.
68 *
69 * @code
70 int affected, rowid, aint;
71 char *atext;
72 database_t *db;
73 enumerator_t *enumerator;
74
75 db = lib->database->create("mysql://user:pass@host/database");
76 affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
77 DB_INT, 77, DB_TEXT, "a text");
78 printf("inserted %d row, new row ID: %d\n", affected, rowid);
79
80 enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
81 DB_INT, 10, // 1 argument to SQL string
82 DB_INT, DB_TEXT); // 2 enumerated types in query
83 if (enumerator)
84 {
85 while (enumerator->enumerate(enumerator, &aint, &atext))
86 {
87 printf("%d: %s\n", aint, atext);
88 }
89 enumerator->destroy(enumerator);
90 }
91 @endcode
92 */
93 struct database_t {
94
95 /**
96 * Run a query which returns rows, such as a SELECT.
97 *
98 * @param sql sql query string, containing '?' placeholders
99 * @param ... list of sql placeholder db_type_t followed by its value,
100 * followed by enumerators arguments as db_type_t's
101 * @return enumerator as defined with arguments, NULL on failure
102 */
103 enumerator_t* (*query)(database_t *this, char *sql, ...);
104
105 /**
106 * Execute a query which does not return rows, such as INSERT.
107 *
108 * @param rowid pointer to write inserted AUTO_INCREMENT row ID, or NULL
109 * @param sql sql string, containing '?' placeholders
110 * @param ... list of sql placeholder db_type_t followed by its value
111 * @return number of affected rows, < 0 on failure
112 */
113 int (*execute)(database_t *this, int *rowid, char *sql, ...);
114
115 /**
116 * Start a transaction.
117 *
118 * A serializable transaction forces a strict separation between other
119 * transactions. Due to the performance overhead they should only be used
120 * in certain situations (e.g. SELECT->INSERT|UPDATE).
121 *
122 * @note Either commit() or rollback() has to be called to end the
123 * transaction.
124 * @note Transactions are thread-specific. So commit()/rollbak() has to be
125 * called from the same thread.
126 * @note While this method can be called multiple times (commit/rollback
127 * have to be called an equal number of times) real nested transactions are
128 * not supported. So if any if the "inner" transactions are rolled back
129 * the outer most transaction is rolled back.
130 *
131 * @param serializable TRUE to create a serializable transaction
132 * @return TRUE on success
133 */
134 bool (*transaction)(database_t *this, bool serializable);
135
136 /**
137 * Commit all changes made during the current transaction.
138 *
139 * @return TRUE on success
140 */
141 bool (*commit)(database_t *this);
142
143 /**
144 * Rollback/revert all changes made during the current transaction.
145 *
146 * @return TRUE on success
147 */
148 bool (*rollback)(database_t *this);
149
150 /**
151 * Get the database implementation type.
152 *
153 * To allow driver specific SQL or performance optimizations each database
154 * implementations can be queried for its type.
155 *
156 * @return database implementation type
157 */
158 db_driver_t (*get_driver)(database_t *this);
159
160 /**
161 * Destroy a database connection.
162 */
163 void (*destroy)(database_t *this);
164 };
165
166 #endif /** DATABASE_H_ @}*/