d46fc3d344878dde9a553a271c2feb29d6af7cbb
[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 <collections/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 /** matches to other databases */
53 DB_ANY = 0,
54 /** SQLite database */
55 DB_SQLITE,
56 /** MySQL database */
57 DB_MYSQL,
58 };
59
60 /**
61 * Names for db_driver_t
62 */
63 extern enum_name_t *db_driver_names;
64
65 /**
66 * Interface for a database implementation.
67 *
68 * @code
69 int affected, rowid, aint;
70 char *atext;
71 database_t *db;
72 enumerator_t *enumerator;
73
74 db = lib->database->create("mysql://user:pass@host/database");
75 affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
76 DB_INT, 77, DB_TEXT, "a text");
77 printf("inserted %d row, new row ID: %d\n", affected, rowid);
78
79 enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
80 DB_INT, 10, // 1 argument to SQL string
81 DB_INT, DB_TEXT); // 2 enumerated types in query
82 if (enumerator)
83 {
84 while (enumerator->enumerate(enumerator, &aint, &atext))
85 {
86 printf("%d: %s\n", aint, atext);
87 }
88 enumerator->destroy(enumerator);
89 }
90 @endcode
91 */
92 struct database_t {
93
94 /**
95 * Run a query which returns rows, such as a SELECT.
96 *
97 * @param sql sql query string, containing '?' placeholders
98 * @param ... list of sql placeholder db_type_t followed by its value,
99 * followed by enumerators arguments as db_type_t's
100 * @return enumerator as defined with arguments, NULL on failure
101 */
102 enumerator_t* (*query)(database_t *this, char *sql, ...);
103
104 /**
105 * Execute a query which dows not return rows, such as INSERT.
106 *
107 * @param rowid pointer to write inserted AUTO_INCREMENT row ID, or NULL
108 * @param sql sql string, containing '?' placeholders
109 * @param ... list of sql placeholder db_type_t followed by its value
110 * @return number of affected rows, < 0 on failure
111 */
112 int (*execute)(database_t *this, int *rowid, char *sql, ...);
113
114 /**
115 * Get the database implementation type.
116 *
117 * To allow driver specific SQL or performance optimizations each database
118 * implementations can be queried for its type.
119 *
120 * @return database implementation type
121 */
122 db_driver_t (*get_driver)(database_t *this);
123
124 /**
125 * Destroy a database connection.
126 */
127 void (*destroy)(database_t *this);
128 };
129
130 #endif /** DATABASE_H_ @}*/