merged the modularization branch (credentials) back to trunk
[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 database 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 struct database_t database_t;
26
27 #include <utils/enumerator.h>
28
29 /**
30 * Database column types
31 */
32 enum db_type_t {
33 /** integer type, argument is an "int" */
34 DB_INT,
35 /** unsigned integer, argument is an "u_int" */
36 DB_UINT,
37 /** string type, argument is a "char*" */
38 DB_TEXT,
39 /** binary large object type, argument is a "chunk_t" */
40 DB_BLOB,
41 /** floating point, argument is a "double" */
42 DB_DOUBLE,
43 /** NULL, takes no argument */
44 DB_NULL,
45 };
46
47
48 /**
49 * Interface for a database implementation.
50 *
51 * @code
52 int affected, rowid, aint;
53 char *atext;
54 database_t *db;
55 enumerator_t *enumerator;
56
57 db = lib->database->create("mysql://user:pass@host/database");
58 affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
59 DB_INT, 77, DB_TEXT, "a text");
60 printf("inserted %d row, new row ID: %d\n", affected, rowid);
61
62 enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
63 DB_INT, 10, // 1 argument to SQL string
64 DB_INT, DB_TEXT); // 2 enumerated types in query
65 if (enumerator)
66 {
67 while (enumerator->enumerate(enumerator, &aint, &atext))
68 {
69 printf("%d: %s\n", aint, atext);
70 }
71 enumerator->destroy(enumerator);
72 }
73 @endcode
74 */
75 struct database_t {
76
77 /**
78 * Run a query which returns rows, such as a SELECT.
79 *
80 * @param sql sql query string, containing '?' placeholders
81 * @param ... list of sql placeholder db_type_t followed by its value,
82 * followed by enumerators arguments as db_type_t's
83 * @return enumerator as defined with arguments, NULL on failure
84 */
85 enumerator_t* (*query)(database_t *this, char *sql, ...);
86
87 /**
88 * Execute a query which dows not return rows, such as INSERT.
89 *
90 * @param rowid pointer to write inserted AUTO_INCREMENT row ID, or NULL
91 * @param sql sql string, containing '?' placeholders
92 * @param ... list of sql placeholder db_type_t followed by its value
93 * @return number of affected rows, < 0 on failure
94 */
95 int (*execute)(database_t *this, int *rowid, char *sql, ...);
96
97 /**
98 * Destroy a database connection.
99 */
100 void (*destroy)(database_t *this);
101 };
102
103 #endif /* DATABASE_H_ @}*/