39f909cd754a1c40ce7fe1db59cf5a1e19cb65ec
[strongswan.git] / src / libstrongswan / database / database.h
1 /*
2 * Copyright (C) 2008 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup databasei database
18 * @{ @ingroup database
19 */
20
21 #ifndef DATABASE_H_
22 #define DATABASE_H_
23
24 typedef enum db_type_t db_type_t;
25 typedef enum db_driver_t db_driver_t;
26 typedef struct database_t database_t;
27
28 #include <utils/enumerator.h>
29
30 /**
31 * Database column types
32 */
33 enum db_type_t {
34 /** integer type, argument is an "int" */
35 DB_INT,
36 /** unsigned integer, argument is an "u_int" */
37 DB_UINT,
38 /** string type, argument is a "char*" */
39 DB_TEXT,
40 /** binary large object type, argument is a "chunk_t" */
41 DB_BLOB,
42 /** floating point, argument is a "double" */
43 DB_DOUBLE,
44 /** NULL, takes no argument */
45 DB_NULL,
46 };
47
48 /**
49 * Database implementation type.
50 */
51 enum db_driver_t {
52 /** SQLite database */
53 DB_SQLITE,
54 /** MySQL database */
55 DB_MYSQL,
56 };
57
58 /**
59 * Interface for a database implementation.
60 *
61 * @code
62 int affected, rowid, aint;
63 char *atext;
64 database_t *db;
65 enumerator_t *enumerator;
66
67 db = lib->database->create("mysql://user:pass@host/database");
68 affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
69 DB_INT, 77, DB_TEXT, "a text");
70 printf("inserted %d row, new row ID: %d\n", affected, rowid);
71
72 enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
73 DB_INT, 10, // 1 argument to SQL string
74 DB_INT, DB_TEXT); // 2 enumerated types in query
75 if (enumerator)
76 {
77 while (enumerator->enumerate(enumerator, &aint, &atext))
78 {
79 printf("%d: %s\n", aint, atext);
80 }
81 enumerator->destroy(enumerator);
82 }
83 @endcode
84 */
85 struct database_t {
86
87 /**
88 * Run a query which returns rows, such as a SELECT.
89 *
90 * @param sql sql query string, containing '?' placeholders
91 * @param ... list of sql placeholder db_type_t followed by its value,
92 * followed by enumerators arguments as db_type_t's
93 * @return enumerator as defined with arguments, NULL on failure
94 */
95 enumerator_t* (*query)(database_t *this, char *sql, ...);
96
97 /**
98 * Execute a query which dows not return rows, such as INSERT.
99 *
100 * @param rowid pointer to write inserted AUTO_INCREMENT row ID, or NULL
101 * @param sql sql string, containing '?' placeholders
102 * @param ... list of sql placeholder db_type_t followed by its value
103 * @return number of affected rows, < 0 on failure
104 */
105 int (*execute)(database_t *this, int *rowid, char *sql, ...);
106
107 /**
108 * Get the database implementation type.
109 *
110 * To allow driver specific SQL or performance optimizations each database
111 * implementations can be queried for its type.
112 *
113 * @return database implementation type
114 */
115 db_driver_t (*get_driver)(database_t *this);
116
117 /**
118 * Destroy a database connection.
119 */
120 void (*destroy)(database_t *this);
121 };
122
123 #endif /* DATABASE_H_ @}*/