Browse code

further cleanups in core database API - move use_table and close function for SQL DBs to core - move query, raw_query, insert, update, delete functions for SQL DBs to core - all this functions were almost identical implemented in the three DB, this functions uses now a function pointer based interface to do the work - the use_table functions from dbtext and db_berkeley uses also now the core API - move result management function from db_col to db_res to the other result management functions, they are not useful alone - change postgres module to match more the structure of mysql and unixodbc, remove the 'PARANOID' #define, the other modules don't have this and prefix all functions with db_postgres, make this more consistent to mysql module - prefix all functions in unixodbc module with db_unixodbc, make this consistent to the other modules, cleanup the namespace - prefix val2str function in mysql with db_mysql too - move the SQL_BUF_LENGTH to core API, all modules need this - remove the static SQL char buffer from postgres and unixodbc, uses the one provided from the core API - move documentation from db/doc to API files in doxygen format - improve and extend documentation for the whole API - make database API const correct, to guard against implementation errors and allow better compiler optimizations - change interface free_connection function in SQL DBs to connection structure to allow the usage of core API do_close - fix indention for postgres driver and make logging messages consistent - remove now unneeded system header includes for SQL DBs - remove transaction related code from postgres driver, this is not used at all and according to Klaus also brings no performance benefit if used. - probably some other smaller cleanups

Tested with the testcases, so basic functionality should work.. Please test! :-)


git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@3506 689a6050-402a-0410-94f2-e92a70836424

Henning Westerholt authored on 07/01/2008 14:26:27
Showing 21 changed files
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  * 
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -26,6 +27,21 @@
26 27
   *  2006-10-10  Added support for retrieving the last inserted ID (Carsten Bock, BASIS AudioNet GmbH)
27 28
   */
28 29
 
30
+/**
31
+ * \file db/db.c
32
+ * \brief Generic Database Interface
33
+ *
34
+ * This is a generic database interface for modules that need to utilize a
35
+ * database. The interface should be used by all modules that access database.
36
+ * The interface will be independent of the underlying database server.
37
+ * Notes:
38
+ * If possible, use the predefined macros if you need to access any structure
39
+ * attributes.
40
+ * For additional description, see the comments in the sources of mysql module.
41
+ *
42
+ * If you want to see more complicated examples of how the API could be used,
43
+ * take a look at the sources of the usrloc or auth modules.
44
+ */
29 45
 
30 46
 #include "../dprint.h"
31 47
 #include "../sr_module.h"
... ...
@@ -38,7 +54,6 @@
38 54
 #include "db.h"
39 55
 
40 56
 
41
-
42 57
 /* fills mydbf with the corresponding db module callbacks
43 58
  * returns 0 on success, -1 on error
44 59
  * on error mydbf will contain only 0s */
... ...
@@ -164,6 +179,92 @@ int bind_dbmod(char* mod, db_func_t* mydbf)
164 179
 }
165 180
 
166 181
 
182
+/*
183
+ * Initialize database module
184
+ * No function should be called before this
185
+ */
186
+db_con_t* db_do_init(const char* url, void* (*new_connection)())
187
+{
188
+	struct db_id* id;
189
+	void* con;
190
+	db_con_t* res;
191
+
192
+	int con_size = sizeof(db_con_t) + sizeof(void *);
193
+	id = 0;
194
+	res = 0;
195
+
196
+	if (!url || !new_connection) {
197
+		LM_ERR("invalid parameter value\n");
198
+		return 0;
199
+	}
200
+	if (strlen(url) > 255)
201
+	{
202
+		LM_ERR("SQL URL too long\n");
203
+		return 0;
204
+	}
205
+	
206
+	/* this is the root memory for this database connection. */
207
+	res = (db_con_t*)pkg_malloc(con_size);
208
+	if (!res) {
209
+		LM_ERR("no private memory left\n");
210
+		return 0;
211
+	}
212
+	memset(res, 0, con_size);
213
+
214
+	id = new_db_id(url);
215
+	if (!id) {
216
+		LM_ERR("cannot parse URL '%s'\n", url);
217
+		goto err;
218
+	}
219
+
220
+	/* Find the connection in the pool */
221
+	con = pool_get(id);
222
+	if (!con) {
223
+		LM_DBG("connection %p not found in pool\n", id);
224
+		/* Not in the pool yet */
225
+		con = new_connection(id);
226
+		if (!con) {
227
+			LM_ERR("could not add connection to the pool");
228
+			goto err;
229
+		}
230
+		pool_insert((struct pool_con*)con);
231
+	} else {
232
+		LM_DBG("connection %p found in pool\n", id);
233
+	}
234
+
235
+	res->tail = (unsigned long)con;
236
+	return res;
237
+
238
+ err:
239
+	if (id) free_db_id(id);
240
+	if (res) pkg_free(res);
241
+	return 0;
242
+}
243
+
244
+
245
+/*
246
+ * Shut down database module
247
+ * No function should be called after this
248
+ */
249
+void db_do_close(db_con_t* _h, void (*free_connection)())
250
+{
251
+	struct pool_con* con;
252
+
253
+	if (!_h) {
254
+		LM_ERR("invalid parameter value\n");
255
+		return;
256
+	}
257
+
258
+	con = (struct pool_con*)_h->tail;
259
+	if (pool_remove(con) == 1) {
260
+		free_connection(con);
261
+	}
262
+
263
+	pkg_free(_h);
264
+}
265
+
266
+
267
+
167 268
 /*
168 269
  * Get version of a table
169 270
  * If there is no row for the given table, return version 0
... ...
@@ -226,64 +327,18 @@ int table_version(db_func_t* dbf, db_con_t* connection, const str* table)
226 327
 	return ret;
227 328
 }
228 329
 
330
+
229 331
 /*
230
- * Initialize database module
231
- * No function should be called before this
332
+ * Store name of table that will be used by
333
+ * subsequent database functions
232 334
  */
233
-db_con_t* db_do_init(const char* url, void* (*new_connection)())
335
+int db_use_table(db_con_t* _h, const char* _t)
234 336
 {
235
-	struct db_id* id;
236
-	void* con;
237
-	db_con_t* res;
238
-
239
-	int con_size = sizeof(db_con_t) + sizeof(void *);
240
-	id = 0;
241
-	res = 0;
242
-
243
-	if (!url) {
337
+	if ((!_h) || (!_t)) {
244 338
 		LM_ERR("invalid parameter value\n");
245
-		return 0;
246
-	}
247
-	if (strlen(url) > 255)
248
-	{
249
-		LM_ERR("SQL URL too long\n");
250
-		return 0;
251
-	}
252
-	
253
-	/* this is the root memory for this database connection. */
254
-	res = (db_con_t*)pkg_malloc(con_size);
255
-	if (!res) {
256
-		LM_ERR("no private memory left\n");
257
-		return 0;
258
-	}
259
-	memset(res, 0, con_size);
260
-
261
-	id = new_db_id(url);
262
-	if (!id) {
263
-		LM_ERR("cannot parse URL '%s'\n", url);
264
-		goto err;
265
-	}
266
-
267
-	/* Find the connection in the pool */
268
-	con = pool_get(id);
269
-	if (!con) {
270
-		LM_DBG("connection %p not found in pool\n", id);
271
-		/* Not in the pool yet */
272
-		con = new_connection(id);
273
-		if (!con) {
274
-			LM_ERR("could not add connection to the pool");
275
-			goto err;
276
-		}
277
-		pool_insert((struct pool_con*)con);
278
-	} else {
279
-		LM_DBG("connection %p found in pool\n", id);
339
+		return -1;
280 340
 	}
281 341
 
282
-	res->tail = (unsigned long)con;
283
-	return res;
284
-
285
- err:
286
-	if (id) free_db_id(id);
287
-	if (res) pkg_free(res);
342
+	CON_TABLE(_h) = _t;
288 343
 	return 0;
289 344
 }
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of ser, a free SIP server.
7 8
  *
... ...
@@ -32,7 +33,7 @@
32 33
  */
33 34
 
34 35
 /**
35
- * \file db.h
36
+ * \file db/db.h
36 37
  * \brief Generic Database Interface
37 38
  *
38 39
  * This is a generic database interface for modules that need to utilize a
... ...
@@ -45,7 +46,7 @@
45 46
  *
46 47
  * If you want to see more complicated examples of how the API could be used,
47 48
  * take a look at the sources of the usrloc or auth modules.
48
-*/
49
+ */
49 50
 
50 51
 #ifndef DB_H
51 52
 #define DB_H
... ...
@@ -57,6 +58,7 @@
57 58
 #include "db_row.h"
58 59
 #include "db_res.h"
59 60
 #include "db_cap.h"
61
+#include "db_con.h"
60 62
 
61 63
 
62 64
 /**
... ...
@@ -67,7 +69,7 @@
67 69
  * that table.
68 70
  * \param _h database connection handle
69 71
  * \param _t table name
70
- * \return returns 0 if everything is OK, otherwise returns value < 0.
72
+ * \return returns 0 if everything is OK, otherwise returns value < 0
71 73
  */
72 74
 typedef int (*db_use_table_f)(db_con_t* _h, const char* _t);
73 75
 
... ...
@@ -92,7 +94,7 @@ typedef int (*db_use_table_f)(db_con_t* _h, const char* _t);
92 94
  * \see bind_dbmod
93 95
  * \param _sqlurl database connection URL
94 96
  * \return returns a pointer to the db_con_t representing the connection if it was
95
-  successful, otherwise 0 is returned.
97
+ * successful, otherwise 0 is returned
96 98
  */
97 99
 typedef db_con_t* (*db_init_f) (const char* _sqlurl);
98 100
 
... ...
@@ -134,7 +136,7 @@ typedef void (*db_close_f) (db_con_t* _h);
134 136
  * \param _nc number of columns in _c parameter
135 137
  * \param _o order by statement for query
136 138
  * \param _r address of variable where pointer to the result will be stored
137
- * \return returns 0 if everything is OK, otherwise returns value < 0.
139
+ * \return returns 0 if everything is OK, otherwise returns value < 0
138 140
  */
139 141
 typedef int (*db_query_f) (db_con_t* _h, db_key_t* _k,
140 142
 			   db_op_t* _op, db_val_t* _v, db_key_t* _c,
... ...
@@ -149,7 +151,7 @@ typedef int (*db_query_f) (db_con_t* _h, db_key_t* _k,
149 151
  * \param _h structure representing database connection
150 152
  * \param _r structure for the result
151 153
  * \param _n the number of rows that should be fetched
152
- * \return returns 0 if everything is OK, otherwise returns value < 0.
154
+ * \return returns 0 if everything is OK, otherwise returns value < 0
153 155
  */
154 156
 typedef int (*db_fetch_result_f) (db_con_t* _h, db_res_t** _r, int _n);
155 157
 
... ...
@@ -167,7 +169,7 @@ typedef int (*db_fetch_result_f) (db_con_t* _h, db_res_t** _r, int _n);
167 169
  * \param _h structure representing database connection
168 170
  * \param _s the SQL query
169 171
  * \param _r structure for the result
170
- * \return returns 0 if everything is OK, otherwise returns value < 0.
172
+ * \return returns 0 if everything is OK, otherwise returns value < 0
171 173
  */
172 174
 typedef int (*db_raw_query_f) (db_con_t* _h, char* _s, db_res_t** _r);
173 175
 
... ...
@@ -180,7 +182,7 @@ typedef int (*db_raw_query_f) (db_con_t* _h, char* _s, db_res_t** _r);
180 182
  * structure anymore. You must call this function before you call db_query again!
181 183
  * \param _h database connection handle
182 184
  * \param _r pointer to db_res_t structure to destroy
183
- * \return returns 0 if everything is OK, otherwise returns value < 0.
185
+ * \return returns 0 if everything is OK, otherwise returns value < 0
184 186
  */
185 187
 typedef int (*db_free_result_f) (db_con_t* _h, db_res_t* _r);
186 188
 
... ...
@@ -194,7 +196,7 @@ typedef int (*db_free_result_f) (db_con_t* _h, db_res_t* _r);
194 196
  * \param _k array of keys (column names) 
195 197
  * \param _v array of values for keys specified in _k parameter
196 198
  * \param _n number of keys-value pairs int _k and _v parameters
197
- * \return returns 0 if everything is OK, otherwise returns value < 0.
199
+ * \return returns 0 if everything is OK, otherwise returns value < 0
198 200
  */
199 201
 typedef int (*db_insert_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);
200 202
 
... ...
@@ -213,7 +215,7 @@ typedef int (*db_insert_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);
213 215
  * \param _o array of operators to be used with key-value pairs
214 216
  * \param _v array of values that the row must match to be deleted
215 217
  * \param _n number of keys-value parameters in _k and _v parameters
216
- * \return returns 0 if everything is OK, otherwise returns value < 0.
218
+ * \return returns 0 if everything is OK, otherwise returns value < 0
217 219
  */
218 220
 typedef int (*db_delete_f) (db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _v, int _n);
219 221
 
... ...
@@ -247,7 +249,7 @@ typedef int (*db_update_f) (db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _
247 249
  * \param _k key names
248 250
  * \param _v values of the keys
249 251
  * \param _n number of key=value pairs
250
- * \return returns 0 if everything is OK, otherwise returns value < 0.
252
+ * \return returns 0 if everything is OK, otherwise returns value < 0
251 253
 */
252 254
 typedef int (*db_replace_f) (db_con_t* handle, db_key_t* keys, db_val_t* vals, int n);
253 255
 
... ...
@@ -276,7 +278,7 @@ typedef int (*db_last_inserted_id_f) (db_con_t* _h);
276 278
  * \param _k key names
277 279
  * \param _v values of the keys
278 280
  * \param _n number of key=value pairs
279
- * \return returns 0 if everything is OK, otherwise returns value < 0.
281
+ * \return returns 0 if everything is OK, otherwise returns value < 0
280 282
  */
281 283
 typedef int (*db_insert_update_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);
282 284
 
... ...
@@ -323,11 +325,33 @@ typedef struct db_func {
323 325
  * \see db_func_t
324 326
  * \param mod database connection URL or a database module name
325 327
  * \param dbf database module callbacks
326
- * \return returns 0 if everything is OK, otherwise returns value < 0.
328
+ * \return returns 0 if everything is OK, otherwise returns value < 0
327 329
  */
328 330
 int bind_dbmod(char* mod, db_func_t* dbf);
329 331
 
330 332
 
333
+/**
334
+ * \brief Helper for db_init function.
335
+ *
336
+ * This helper method do the actual work for the database specific db_init
337
+ * functions.
338
+ * \param url database connection URL
339
+ * \param (*new_connection)() Pointer to the db specific connection creation method
340
+ * \return returns a pointer to the db_con_t representing the connection if it was
341
+   successful, otherwise 0 is returned.
342
+ */
343
+db_con_t* db_do_init(const char* url, void* (*new_connection)());
344
+
345
+/**
346
+ * \brief Helper for db_close function.
347
+ *
348
+ * This helper method does some work for the closing of a database 
349
+ * connection. No function should be called after this
350
+ * \param _h database connection handle
351
+ * \param (*free_connection) Pointer to the db specifc free_connection method
352
+ */
353
+void db_do_close(db_con_t* _h, void (*free_connection)());
354
+
331 355
 /**
332 356
  * \brief Get the version of a table.
333 357
  *
... ...
@@ -339,16 +363,17 @@ int bind_dbmod(char* mod, db_func_t* dbf);
339 363
  */
340 364
 int table_version(db_func_t* dbf, db_con_t* con, const str* table);
341 365
 
366
+
342 367
 /**
343
- * \brief Helper for db_init function.
368
+ * \brief Stores the name of table
344 369
  *
345
- * This helper method do the actual work for the database specific db_init
346
- * functions.
347
- * \param url database connection URL
348
- * \param (*new_connection)() Pointer to the db specific connection creation method
349
- * \return returns a pointer to the db_con_t representing the connection if it was
350
-   successful, otherwise 0 is returned.
370
+ * Stores the name of the table that will be used by subsequent database
371
+ * functions calls in a db_con_t structure.
372
+ * \param _h database connection handle
373
+ * \param _t stored name
374
+ * \return 0 if everything is ok, otherwise returns value < 0
351 375
  */
352
-db_con_t* db_do_init(const char* url, void* (*new_connection)());
376
+int db_use_table(db_con_t* _h, const char* _t);
377
+
353 378
 
354 379
 #endif /* DB_H */
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2004 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,36 +21,45 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db_cap.h
26
+ * \brief Data structures that represents capabilities in the database.
27
+ *
28
+ * This file defines data structures that represents certain database
29
+ * capabilities. It also provides some macros for convenient access to this
30
+ * values.
31
+ */
32
+
23 33
 #ifndef DB_CAP_H
24 34
 #define DB_CAP_H
25 35
 
26 36
 
27
-/*
28
- * Database capabilities
37
+/**
38
+ * Represents the capabilities that a database driver supports.
29 39
  */
30 40
 typedef enum db_cap {
31
-	DB_CAP_QUERY =     1 << 0,  /* Database driver can query database */
32
-	DB_CAP_RAW_QUERY = 1 << 1,  /* Database driver can perform raw queries */
33
-	DB_CAP_INSERT =    1 << 2,  /* Database driver can insert data into database */
34
-	DB_CAP_DELETE =    1 << 3,  /* Database driver can delete data from database */
35
-	DB_CAP_UPDATE =    1 << 4,  /* Database driver can update data in the database */
36
-	DB_CAP_REPLACE =   1 << 5,  /* Replace (also known as INSERT OR UPDATE) support */
37
-	DB_CAP_FETCH   =   1 << 6,  /* Fetch result support */
38
-	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /* ID of the last insert */
39
- 	DB_CAP_INSERT_UPDATE = 1 << 8 /* Database driver can insert data into database and update on duplicate */
41
+	DB_CAP_QUERY =     1 << 0,  /**< driver can perform queries                                     */
42
+	DB_CAP_RAW_QUERY = 1 << 1,  /**< driver can perform raw queries                                 */
43
+	DB_CAP_INSERT =    1 << 2,  /**< driver can insert data                                         */
44
+	DB_CAP_DELETE =    1 << 3,  /**< driver can delete data                                         */
45
+	DB_CAP_UPDATE =    1 << 4,  /**< driver can update data                                         */
46
+	DB_CAP_REPLACE =   1 << 5,  /**< driver can replace (also known as INSERT OR UPDATE) data       */
47
+	DB_CAP_FETCH   =   1 << 6,  /**< driver supports fetch result queries                           */
48
+	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /**< driver can return the ID of the last insert operation   */
49
+ 	DB_CAP_INSERT_UPDATE = 1 << 8 /**< driver can insert data into database and update on duplicate */
40 50
 
41 51
 } db_cap_t;
42 52
 
43 53
 
44
-/*
54
+/**
45 55
  * All database capabilities except raw_query, replace, insert_update and 
46 56
  * last_inserted_id which should be checked separately when needed
47 57
  */
48 58
 #define DB_CAP_ALL (DB_CAP_QUERY | DB_CAP_INSERT | DB_CAP_DELETE | DB_CAP_UPDATE)
49 59
 
50 60
 
51
-/*
52
- * True if all the capabilities in cpv are supported by module
61
+/**
62
+ * Returns true if all the capabilities in cpv are supported by module
53 63
  * represented by dbf, false otherwise
54 64
  */
55 65
 #define DB_CAPABILITY(dbf, cpv) (((dbf).cap & (cpv)) == (cpv))
56 66
deleted file mode 100644
... ...
@@ -1,42 +0,0 @@
1
-/* 
2
- * $Id$ 
3
- *
4
- * Copyright (C) 2001-2003 FhG Fokus
5
- * Copyright (C) 2007 1und1 Internet AG
6
- *
7
- * This file is part of openser, a free SIP server.
8
- *
9
- * openser is free software; you can redistribute it and/or modify
10
- * it under the terms of the GNU General Public License as published by
11
- * the Free Software Foundation; either version 2 of the License, or
12
- * (at your option) any later version
13
- *
14
- * openser is distributed in the hope that it will be useful,
15
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
16
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17
- * GNU General Public License for more details.
18
- *
19
- * You should have received a copy of the GNU General Public License 
20
- * along with this program; if not, write to the Free Software 
21
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22
- */
23
-
24
-#include "db_col.h"
25
-
26
-#include "../dprint.h"
27
-#include "../mem/mem.h"
28
-
29
-/*
30
- * Release memory used by columns
31
- */
32
-inline int db_free_columns(db_res_t* _r)
33
-{
34
-	if (!_r) {
35
-		LM_ERR("invalid parameter\n");
36
-		return -1;
37
-	}
38
-
39
-	if (RES_NAMES(_r)) pkg_free(RES_NAMES(_r));
40
-	if (RES_TYPES(_r)) pkg_free(RES_TYPES(_r));
41
-	return 0;
42
-}
43 0
deleted file mode 100644
... ...
@@ -1,36 +0,0 @@
1
-/* 
2
- * $Id$ 
3
- *
4
- * Copyright (C) 2001-2003 FhG Fokus
5
- *
6
- * This file is part of openser, a free SIP server.
7
- *
8
- * openser is free software; you can redistribute it and/or modify
9
- * it under the terms of the GNU General Public License as published by
10
- * the Free Software Foundation; either version 2 of the License, or
11
- * (at your option) any later version
12
- *
13
- * openser is distributed in the hope that it will be useful,
14
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
15
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16
- * GNU General Public License for more details.
17
- *
18
- * You should have received a copy of the GNU General Public License 
19
- * along with this program; if not, write to the Free Software 
20
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21
- */
22
-
23
-
24
-#ifndef DB_COL_H
25
-#define DB_COL_H
26
-
27
-
28
-#include "db_res.h"
29
-
30
-
31
-/*
32
- * Release memory used by columns
33
- */
34
-int db_free_columns(db_res_t* _r);
35
-
36
-#endif /* DB_COL_H */
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$ 
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,25 +21,28 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
23
-
24
+/**
25
+ * \file db/db_con.h
26
+ * \brief Type that represents a database connection
27
+ */
24 28
 
25 29
 #ifndef DB_CON_H
26 30
 #define DB_CON_H
27 31
 
28 32
 
29
-/*
30
- * This structure represents a database connection
31
- * and pointer to this structure is used as a connection
32
- * handle
33
+/**
34
+ * This structure represents a database connection, pointer to this structure
35
+ * are used as a connection handle from modules uses the db API.
33 36
  */
34 37
 typedef struct {
35
-	const char* table;     /* Default table to use */
36
-	unsigned long tail;    /* Variable length tail
37
-				* database module specific */    
38
+	const char* table;     /**< Default table that should be used              */
39
+	unsigned long tail;    /**< Variable length tail, database module specific */
38 40
 } db_con_t;
39 41
 
40 42
 
43
+/** Return the table of the connection handle */
41 44
 #define CON_TABLE(cn)      ((cn)->table)
45
+/** Return the tail of the connection handle */
42 46
 #define CON_TAIL(cn)       ((cn)->tail)
43 47
 
44 48
 
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2005 iptel.org
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,6 +21,11 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_id.c
26
+ * \brief Functions for parsing a database URL and work with db identifier.
27
+ */
28
+
23 29
 #include "db_id.h"
24 30
 #include "../dprint.h"
25 31
 #include "../mem/mem.h"
... ...
@@ -239,7 +245,7 @@ struct db_id* new_db_id(const char* url)
239 245
 /*
240 246
  * Compare two connection identifiers
241 247
  */
242
-unsigned char cmp_db_id(struct db_id* id1, struct db_id* id2)
248
+unsigned char cmp_db_id(const struct db_id* id1, const struct db_id* id2)
243 249
 {
244 250
 	if (!id1 || !id2) return 0;
245 251
 	if (id1->port != id2->port) return 0;
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2005 iptel.org
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  * 
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,36 +21,47 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_id.c
26
+ * \brief Functions for parsing a database URL and works with db identifier.
27
+ */
28
+
23 29
 #ifndef _DB_ID_H
24 30
 #define _DB_ID_H
25 31
 
26 32
 #include "../str.h"
27 33
 
28
-
34
+/** Structure representing a database ID */
29 35
 struct db_id {
30
-	char* scheme;        /* URL scheme */
31
-	char* username;      /* Username, case sensitive */
32
-	char* password;      /* Password, case sensitive */
33
-	char* host;          /* Host or IP, case insensitive */
34
-	unsigned short port; /* Port number */
35
-	char* database;      /* Database, case sensitive */
36
+	char* scheme;        /**< URL scheme */
37
+	char* username;      /**< Username, case sensitive */
38
+	char* password;      /**< Password, case sensitive */
39
+	char* host;          /**< Host or IP, case insensitive */
40
+	unsigned short port; /**< Port number */
41
+	char* database;      /**< Database, case sensitive */
36 42
 };
37 43
 
38 44
 
39
-/*
45
+/**
40 46
  * Create a new connection identifier
47
+ * \param url database URL
48
+ * \return new allocated db_id structure, NULL on failure
41 49
  */
42 50
 struct db_id* new_db_id(const char* url);
43 51
 
44 52
 
45
-/*
53
+/**
46 54
  * Compare two connection identifiers
55
+ * \param id1 first identifier
56
+ * \param id2 second identifier
57
+ * \return 1 if both identifier are equal, 0 if there not equal
47 58
  */
48
-unsigned char cmp_db_id(struct db_id* id1, struct db_id* id2);
59
+unsigned char cmp_db_id(const struct db_id* id1, const struct db_id* id2);
49 60
 
50 61
 
51
-/*
62
+/**
52 63
  * Free a connection identifier
64
+ * \param id the identifier that should released
53 65
  */
54 66
 void free_db_id(struct db_id* id);
55 67
 
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$ 
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,13 +21,18 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_key.h
26
+ * \brief Type that represents a database key.
27
+ */
23 28
 
24 29
 #ifndef DB_KEY_H
25 30
 #define DB_KEY_H
26 31
 
27 32
 
28
-/*
29
- * Type of a database key (column)
33
+/**
34
+ * This type represents a database key (column).
35
+ * Every time you need to specify a key value, this type should be used.
30 36
  */
31 37
 typedef const char* db_key_t;
32 38
 
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$ 
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,20 +21,30 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_op.h
26
+ * \brief Type that represents a expression operator.
27
+ */
23 28
 
24 29
 #ifndef DB_OP_H
25 30
 #define DB_OP_H
26 31
 
32
+/** operator less than */
27 33
 #define OP_LT  "<"
34
+/** operator greater than */
28 35
 #define OP_GT  ">"
36
+/** operator equal */
29 37
 #define OP_EQ  "="
38
+/** operator less than equal */
30 39
 #define OP_LEQ "<="
40
+/** operator greater than equal */
31 41
 #define OP_GEQ ">="
42
+/** operator negation */
32 43
 #define OP_NEQ "!="
33 44
 
34 45
 
35
-/*
36
- * Type of a operator
46
+/**
47
+ * This type represents an expression operator uses for SQL queries.
37 48
  */
38 49
 typedef const char* db_op_t;
39 50
 
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2005 iptel.org
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,6 +21,11 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_pool.c
26
+ * \brief Functions for managing a pool of database connections.
27
+ */
28
+
23 29
 #include "../dprint.h"
24 30
 #include "db_pool.h"
25 31
 
... ...
@@ -33,7 +39,7 @@ static struct pool_con* db_pool = 0;
33 39
  * the identifier equal to id, NULL is returned
34 40
  * when no connection is found
35 41
  */
36
-struct pool_con* pool_get(struct db_id* id)
42
+struct pool_con* pool_get(const struct db_id* id)
37 43
 {
38 44
 	struct pool_con* ptr;
39 45
 
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$
3 3
  *
4 4
  * Copyright (C) 2001-2005 iptel.org
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,6 +21,11 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_pool.h
26
+ * \brief Functions for managing a pool of database connections.
27
+ */
28
+
23 29
 #ifndef _DB_POOL_H
24 30
 #define _DB_POOL_H
25 31
 
... ...
@@ -27,7 +33,7 @@
27 33
 #include "db_con.h"
28 34
 
29 35
 
30
-/*
36
+/**
31 37
  * This is a stub that contains all attributes
32 38
  * that pool members must have, it is not really
33 39
  * used, real connection structures are created
... ...
@@ -36,28 +42,30 @@
36 42
  * attributes.
37 43
  */
38 44
 struct pool_con {
39
-	struct db_id* id;        /* Connection identifier */
40
-	unsigned int ref;        /* Reference count */
41
-	struct pool_con* next;   /* Next element in the pool */
45
+	struct db_id* id;        /**< Connection identifier */
46
+	unsigned int ref;        /**< Reference count */
47
+	struct pool_con* next;   /**< Next element in the pool */
42 48
 };
43 49
 
44 50
 
45
-/*
46
- * Search the pool for a connection with
47
- * the identifier equal to id, NULL is returned
48
- * when no connection is found
51
+/**
52
+ * Search the pool for a connection with the identifier equal to
53
+ * the id.
54
+ * \param id searched id
55
+ * \return the connection if it could be found, NULL otherwise
49 56
  */
50
-struct pool_con* pool_get(struct db_id* id);
57
+struct pool_con* pool_get(const struct db_id* id);
51 58
 
52 59
 
53
-/*
54
- * Insert a new connection into the pool
60
+/**
61
+ * Insert a new connection into the pool.
62
+ * \param con the inserted connection 
55 63
  */
56 64
 void pool_insert(struct pool_con* con);
57 65
 
58 66
 
59
-/*
60
- * Release connection from the pool, the function
67
+/**
68
+ * Release a connection from the pool, the function
61 69
  * would return 1 when if the connection is not
62 70
  * referenced anymore and thus can be closed and
63 71
  * deleted by the backend. The function returns
... ...
@@ -65,6 +73,8 @@ void pool_insert(struct pool_con* con);
65 73
  * because some other module is still using it.
66 74
  * The function returns -1 if the connection is
67 75
  * not in the pool.
76
+ * \param con connection that should be removed
77
+ * \return 1 if the connection can be freed, 0 if it can't be freed, -1 if not found
68 78
  */
69 79
 int pool_remove(struct pool_con* con);
70 80
 
71 81
new file mode 100644
... ...
@@ -0,0 +1,300 @@
1
+/*
2
+ * $Id$
3
+ *
4
+ * Copyright (C) 2007-2008 1&1 Internet AG
5
+ *
6
+ * This file is part of openser, a free SIP server.
7
+ *
8
+ * openser is free software; you can redistribute it and/or modify
9
+ * it under the terms of the GNU General Public License as published by
10
+ * the Free Software Foundation; either version 2 of the License, or
11
+ * (at your option) any later version
12
+ *
13
+ * openser is distributed in the hope that it will be useful,
14
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
15
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16
+ * GNU General Public License for more details.
17
+ *
18
+ * You should have received a copy of the GNU General Public License 
19
+ * along with this program; if not, write to the Free Software 
20
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21
+ *
22
+ */
23
+
24
+/**
25
+ * \file db/db_query.c
26
+ * \brief Query helper for database drivers
27
+ *
28
+ * This helper methods for database queries are used from the database
29
+ * SQL driver to do the actual work. Each function uses some functions from
30
+ * the actual driver with function pointers to the concrete, specific
31
+ * implementation.
32
+*/
33
+
34
+#include <stdio.h>
35
+#include "../dprint.h"
36
+#include "db_ut.h"
37
+#include "db_query.h"
38
+
39
+static char sql_buf[SQL_BUF_LEN];
40
+
41
+int db_do_query( const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
42
+	const db_val_t* _v, const db_key_t* _c, const int _n, const int _nc,
43
+	const db_key_t _o, db_res_t** _r, int (*val2str) (const db_con_t*,
44
+	const db_val_t*, char*, int* _len), int (*submit_query)(const db_con_t*,
45
+	const char*), int (*store_result)(const db_con_t*, db_res_t**))
46
+{
47
+	int off, ret;
48
+
49
+	if (!_h || !val2str || !submit_query || !store_result) {
50
+		LM_ERR("invalid parameter value\n");
51
+		return -1;
52
+	}
53
+
54
+	if (!_c) {
55
+		ret = snprintf(sql_buf, SQL_BUF_LEN, "select * from %s ", CON_TABLE(_h));
56
+		if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
57
+		off = ret;
58
+	} else {
59
+		ret = snprintf(sql_buf, SQL_BUF_LEN, "select ");
60
+		if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
61
+		off = ret;
62
+
63
+		ret = db_print_columns(sql_buf + off, SQL_BUF_LEN - off, _c, _nc);
64
+		if (ret < 0) return -1;
65
+		off += ret;
66
+
67
+		ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, "from %s ", CON_TABLE(_h));
68
+		if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
69
+		off += ret;
70
+	}
71
+	if (_n) {
72
+		ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, "where ");
73
+		if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
74
+		off += ret;
75
+
76
+		ret = db_print_where(_h, sql_buf + off,
77
+				SQL_BUF_LEN - off, _k, _op, _v, _n, val2str);
78
+		if (ret < 0) return -1;;
79
+		off += ret;
80
+	}
81
+	if (_o) {
82
+		ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, " order by %s", _o);
83
+		if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
84
+		off += ret;
85
+	}
86
+	
87
+	*(sql_buf + off) = '\0';
88
+	if (submit_query(_h, sql_buf) < 0) {
89
+		LM_ERR("error while submitting query\n");
90
+		return -2;
91
+	}
92
+
93
+	if(_r) {
94
+		int tmp = store_result(_h, _r);
95
+		if (tmp < 0) {
96
+			LM_ERR("error while storing result");
97
+			return tmp;
98
+		}
99
+	}
100
+
101
+	return 0;
102
+
103
+error:
104
+	LM_ERR("error while preparing query\n");
105
+	return -1;
106
+}
107
+
108
+
109
+int db_do_raw_query(const db_con_t* _h, const char* _s, db_res_t** _r, 
110
+	int (*submit_query)(const db_con_t* _h, const char* _c),
111
+	int (*store_result)(const db_con_t* _h, db_res_t** _r))
112
+{
113
+	if (!_h || !_s || !submit_query || !store_result) {
114
+		LM_ERR("invalid parameter value\n");
115
+		return -1;
116
+	}
117
+
118
+	if (submit_query(_h, _s) < 0) {
119
+		LM_ERR("error while submitting query\n");
120
+		return -2;
121
+	}
122
+
123
+	if(_r) {
124
+		int tmp = store_result(_h, _r);
125
+		if (tmp < 0) {
126
+			LM_ERR("error while storing result");
127
+			return tmp;
128
+		}
129
+	}
130
+	return 0;
131
+}
132
+
133
+
134
+int db_do_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
135
+	const int _n, int (*val2str) (const db_con_t*, const db_val_t*, char*, int*), 
136
+	int (*submit_query)(const db_con_t* _h, const char* _c))
137
+{
138
+	int off, ret;
139
+
140
+	if (!_h || !_k || !_v || !_n || !val2str || !submit_query) {
141
+		LM_ERR("invalid parameter value\n");
142
+		return -1;
143
+	}
144
+
145
+	ret = snprintf(sql_buf, SQL_BUF_LEN, "insert into %s (", CON_TABLE(_h));
146
+	if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
147
+	off = ret;
148
+
149
+	ret = db_print_columns(sql_buf + off, SQL_BUF_LEN - off, _k, _n);
150
+	if (ret < 0) return -1;
151
+	off += ret;
152
+
153
+	ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, ") values (");
154
+	if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
155
+	off += ret;
156
+
157
+	ret = db_print_values(_h, sql_buf + off, SQL_BUF_LEN - off, _v, _n, val2str);
158
+	if (ret < 0) return -1;
159
+	off += ret;
160
+
161
+	*(sql_buf + off++) = ')';
162
+	*(sql_buf + off) = '\0';
163
+
164
+	if (submit_query(_h, sql_buf) < 0) {
165
+	        LM_ERR("error while submitting query\n");
166
+		return -2;
167
+	}
168
+	return 0;
169
+
170
+error:
171
+	LM_ERR("error while preparing insert operation\n");
172
+	return -1;
173
+}
174
+
175
+
176
+int db_do_delete(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
177
+	const db_val_t* _v, const int _n, int (*val2str) (const db_con_t*,
178
+	const db_val_t*, char*, int*), int (*submit_query)(const db_con_t* _h,
179
+	const char* _c))
180
+{
181
+	int off, ret;
182
+
183
+	if (!_h || !val2str || !submit_query) {
184
+		LM_ERR("invalid parameter value\n");
185
+		return -1;
186
+	}
187
+
188
+	ret = snprintf(sql_buf, SQL_BUF_LEN, "delete from %s", CON_TABLE(_h));
189
+	if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
190
+	off = ret;
191
+
192
+	if (_n) {
193
+		ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, " where ");
194
+		if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
195
+		off += ret;
196
+
197
+		ret = db_print_where(_h, sql_buf + off,
198
+				SQL_BUF_LEN - off, _k, _o, _v, _n, val2str);
199
+		if (ret < 0) return -1;
200
+		off += ret;
201
+	}
202
+
203
+	*(sql_buf + off) = '\0';
204
+	if (submit_query(_h, sql_buf) < 0) {
205
+		LM_ERR("error while submitting query\n");
206
+		return -2;
207
+	}
208
+	return 0;
209
+
210
+error:
211
+	LM_ERR("error while preparing delete operation\n");
212
+	return -1;
213
+}
214
+
215
+
216
+int db_do_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
217
+	const db_val_t* _v, const db_key_t* _uk, const db_val_t* _uv, const int _n,
218
+	const int _un, int (*val2str) (const db_con_t*, const db_val_t*, char*, int*),
219
+	int (*submit_query)(const db_con_t* _h, const char* _c))
220
+{
221
+	int off, ret;
222
+
223
+	if (!_h || !_uk || !_uv || !_un || !val2str || !submit_query) {
224
+		LM_ERR("invalid parameter value\n");
225
+		return -1;
226
+	}
227
+
228
+	ret = snprintf(sql_buf, SQL_BUF_LEN, "update %s set ", CON_TABLE(_h));
229
+	if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
230
+	off = ret;
231
+
232
+	ret = db_print_set(_h, sql_buf + off, SQL_BUF_LEN - off, _uk, _uv, _un, val2str);
233
+	if (ret < 0) return -1;
234
+	off += ret;
235
+
236
+	if (_n) {
237
+		ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, " where ");
238
+		if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
239
+		off += ret;
240
+
241
+		ret = db_print_where(_h, sql_buf + off, SQL_BUF_LEN - off, _k, _o, _v, _n, val2str);
242
+		if (ret < 0) return -1;
243
+		off += ret;
244
+
245
+		*(sql_buf + off) = '\0';
246
+	}
247
+
248
+	if (submit_query(_h, sql_buf) < 0) {
249
+		LM_ERR("error while submitting query\n");
250
+		return -2;
251
+	}
252
+	return 0;
253
+
254
+error:
255
+	LM_ERR("error while preparing update operation\n");
256
+	return -1;
257
+}
258
+
259
+
260
+int db_do_replace(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
261
+	const int _n, int (*val2str) (const db_con_t*, const db_val_t*, char*,
262
+	int*), int (*submit_query)(const db_con_t* _h, const char* _c))
263
+{
264
+	int off, ret;
265
+
266
+	if (!_h || !_k || !_v || !val2str|| !submit_query) {
267
+		LM_ERR("invalid parameter value\n");
268
+		return -1;
269
+	}
270
+
271
+	ret = snprintf(sql_buf, SQL_BUF_LEN, "replace %s (", CON_TABLE(_h));
272
+	if (ret < 0 || ret >= SQL_BUF_LEN) goto error;
273
+	off = ret;
274
+
275
+	ret = db_print_columns(sql_buf + off, SQL_BUF_LEN - off, _k, _n);
276
+	if (ret < 0) return -1;
277
+	off += ret;
278
+
279
+	ret = snprintf(sql_buf + off, SQL_BUF_LEN - off, ") values (");
280
+	if (ret < 0 || ret >= (SQL_BUF_LEN - off)) goto error;
281
+	off += ret;
282
+
283
+	ret = db_print_values(_h, sql_buf + off, SQL_BUF_LEN - off, _v, _n,
284
+	val2str);
285
+	if (ret < 0) return -1;
286
+	off += ret;
287
+
288
+	*(sql_buf + off++) = ')';
289
+	*(sql_buf + off) = '\0';
290
+
291
+	if (submit_query(_h, sql_buf) < 0) {
292
+	        LM_ERR("error while submitting query\n");
293
+		return -2;
294
+	}
295
+	return 0;
296
+
297
+ error:
298
+	LM_ERR("error while preparing replace operation\n");
299
+	return -1;
300
+}
0 301
new file mode 100644
... ...
@@ -0,0 +1,188 @@
1
+/*
2
+ * $Id$
3
+ *
4
+ * Copyright (C) 2007-2008 1&1 Internet AG
5
+ *
6
+ * This file is part of openser, a free SIP server.
7
+ *
8
+ * openser is free software; you can redistribute it and/or modify
9
+ * it under the terms of the GNU General Public License as published by
10
+ * the Free Software Foundation; either version 2 of the License, or
11
+ * (at your option) any later version
12
+ *
13
+ * openser is distributed in the hope that it will be useful,
14
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
15
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16
+ * GNU General Public License for more details.
17
+ *
18
+ * You should have received a copy of the GNU General Public License 
19
+ * along with this program; if not, write to the Free Software 
20
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21
+ *
22
+ */
23
+
24
+/**
25
+ * \file db/db_query.h
26
+ * \brief Query helper for database drivers
27
+ *
28
+ * This helper methods for database queries are used from the database
29
+ * SQL driver to do the actual work. Each function uses some functions from
30
+ * the actual driver with function pointers to the concrete, specific
31
+ * implementation.
32
+*/
33
+
34
+#ifndef DB_QUERY_H
35
+#define DB_QUERY_H
36
+
37
+#include "db_key.h"
38
+#include "db_op.h"
39
+#include "db_val.h"
40
+#include "db_con.h"
41
+#include "db_row.h"
42
+#include "db_res.h"
43
+#include "db_cap.h"
44
+
45
+
46
+/**
47
+ * \brief Helper function for db queries
48
+ *
49
+ * This method evaluates the actual arguments for the database query and
50
+ * setups the string that is used for the query in the db module.
51
+ * Then its submit the query and stores the result if necessary. It uses for
52
+ * its work the implementation in the concrete database module.
53
+ *
54
+ * \param _h structure representing database connection
55
+ * \param _k key names, if not present the whole table will be returned
56
+ * \param _op operators
57
+ * \param _v values of the keys that must match
58
+ * \param _c column names that should be returned
59
+ * \param _n number of key/value pairs that are compared, if zero then no comparison is done
60
+ * \param _nc number of colums that should be returned
61
+ * \param _o order by the specificied column, optional
62
+ * \param _r the result that is returned
63
+ * \param (*val2str) function pointer to the db specific val conversion function
64
+ * \param (*submit_query) function pointer to the db specific query submit function
65
+ * \param (*store_result) function pointer to the db specific store result function
66
+ * \return zero on success, negative on errors
67
+ */
68
+int db_do_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
69
+	const db_val_t* _v, const db_key_t* _c, const int _n, const int _nc,
70
+	const db_key_t _o, db_res_t** _r, int (*val2str) (const db_con_t*,
71
+	const db_val_t*, char*, int*), int (*submit_query)(const db_con_t* _h,
72
+	const char* _c), int (*store_result)(const db_con_t* _h, db_res_t** _r));
73
+
74
+
75
+/**
76
+ * \brief Helper function for raw db queries
77
+ *
78
+ * This method evaluates the actual arguments for the database raw query
79
+ * and setups the string that is used for the query in the db module.
80
+ * Then its submit the query and stores the result if necessary.
81
+ * It uses for its work the implementation in the concrete database module.
82
+ *
83
+ * \param _h structure representing database connection
84
+ * \param _s char holding the raw query
85
+ * \param _r the result that is returned
86
+ * \param (*val2str) function pointer to the db specific val conversion function
87
+ * \param (*submit_query) function pointer to the db specific query submit function
88
+ * \param (*store_result) function pointer to the db specific store result function
89
+ * \return zero on success, negative on errors
90
+ */
91
+int db_do_raw_query(const db_con_t* _h, const char* _s, db_res_t** _r,
92
+	int (*submit_query)(const db_con_t* _h, const char* _c),
93
+	int (*store_result)(const db_con_t* _h, db_res_t** _r));
94
+
95
+
96
+/**
97
+ * \brief Helper function for db insert operations
98
+ *
99
+ * This method evaluates the actual arguments for the database operation
100
+ * and setups the string that is used for the insert operation in the db
101
+ * module. Then its submit the query for the operation. It uses for its work
102
+ * the implementation in the concrete database module.
103
+ *
104
+ * \param _h structure representing database connection
105
+ * \param _k key names
106
+ * \param _v values of the keys
107
+ * \param _n number of key/value pairs 
108
+ * \param (*val2str) function pointer to the db specific val conversion function
109
+ * \param (*submit_query) function pointer to the db specific query submit function
110
+ * \return zero on success, negative on errors
111
+ */
112
+int db_do_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
113
+	const int _n, int (*val2str) (const db_con_t*, const db_val_t*, char*, int*),
114
+	int (*submit_query)(const db_con_t* _h, const char* _c));
115
+
116
+
117
+/**
118
+ * \brief Helper function for db delete operations
119
+ *
120
+ * This method evaluates the actual arguments for the database operation
121
+ * and setups the string that is used for the delete operation in the db
122
+ * module. Then its submit the query for the operation. It uses for its work
123
+ * the implementation in the concrete database module.
124
+ *
125
+ * \param _h structure representing database connection
126
+ * \param _k key names
127
+ * \param _o operators
128
+ * \param _v values of the keys that must match
129
+ * \param _n number of key/value pairs that are compared, if zero then the whole table is deleted
130
+ * \param (*val2str) function pointer to the db specific val conversion function
131
+ * \param (*submit_query) function pointer to the db specific query submit function
132
+ * \return zero on success, negative on errors
133
+ */
134
+int db_do_delete(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
135
+	const db_val_t* _v, const int _n, int (*val2str) (const db_con_t*,
136
+	const db_val_t*, char*, int*), int (*submit_query)(const db_con_t* _h,
137
+	const char* _c));
138
+
139
+
140
+/**
141
+ * \brief Helper function for db update operations
142
+ *
143
+ * This method evaluates the actual arguments for the database operation
144
+ * and setups the string that is used for the update operation in the db
145
+ * module. Then its submit the query for the operation. It uses for its work
146
+ * the implementation in the concrete database module.
147
+ *
148
+ * \param _h structure representing database connection
149
+ * \param _k key names, if not present the whole table will be returned
150
+ * \param _o operators
151
+ * \param _v values of the keys that must match
152
+ * \param _uk: updated columns
153
+ * \param _uv: updated values of the columns
154
+ * \param _n number of key/value pairs that are compared, if zero then no comparison is done
155
+ * \param _un: number of columns that should be updated
156
+ * \param (*val2str) function pointer to the db specific val conversion function
157
+ * \param (*submit_query) function pointer to the db specific query submit function
158
+ * \return zero on success, negative on errors
159
+ */
160
+int db_do_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
161
+	const db_val_t* _v, const db_key_t* _uk, const db_val_t* _uv, const int _n,
162
+	const int _un, int (*val2str) (const db_con_t*, const db_val_t*, char*, int*),
163
+	int (*submit_query)(const db_con_t* _h, const char* _c));
164
+
165
+
166
+/**
167
+ * \brief Helper function for db delete operations
168
+ *
169
+ * This helper method evaluates the actual arguments for the database operation
170
+ * and setups the string that is used for the replace operation in the db
171
+ * module. Then its submit the query for the operation. It uses for its work the
172
+ * implementation in the concrete database module.
173
+ *
174
+ * \param _h structure representing database connection
175
+ * \param _k key names, if not present the whole table will be returned
176
+ * \param _v values of the keys that must match
177
+ * \param _n number of key/value pairs that are compared, if zero then no comparison is done
178
+ * \param _un: number of columns that should be updated
179
+ * \param (*val2str) function pointer to the db specific val conversion function
180
+ * \param (*submit_query) function pointer to the db specific query submit function
181
+ * \return zero on success, negative on errors
182
+ */
183
+int db_do_replace(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
184
+	const int _n, int (*val2str) (const db_con_t*, const db_val_t*, char*,
185
+	int*), int (*submit_query)(const db_con_t* _h, const char* _c));
186
+
187
+
188
+#endif
... ...
@@ -2,7 +2,7 @@
2 2
  * $Id$ 
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
- * Copyright (C) 2007 1und1 Internet AG
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
6 6
  *
7 7
  * This file is part of openser, a free SIP server.
8 8
  *
... ...
@@ -21,6 +21,14 @@
21 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22 22
  */
23 23
 
24
+/**
25
+ * \file db/db_res.c
26
+ * \brief Functions to manage result structures
27
+ *
28
+ * Provides some convenience macros and some memory management
29
+ * functions for result structures.
30
+ */
31
+
24 32
 #include "db_res.h"
25 33
 
26 34
 #include "db_row.h"
... ...
@@ -57,6 +65,22 @@ inline int db_free_rows(db_res_t* _r)
57 65
 }
58 66
 
59 67
 
68
+/*
69
+ * Release memory used by columns
70
+ */
71
+inline int db_free_columns(db_res_t* _r)
72
+{
73
+	if (!_r) {
74
+		LM_ERR("invalid parameter value\n");
75
+		return -1;
76
+	}
77
+
78
+	if (RES_NAMES(_r)) pkg_free(RES_NAMES(_r));
79
+	if (RES_TYPES(_r)) pkg_free(RES_TYPES(_r));
80
+	return 0;
81
+}
82
+
83
+
60 84
 /*
61 85
  * Create a new result structure and initialize it
62 86
  */
... ...
@@ -2,6 +2,7 @@
2 2
  * $Id$ 
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5
+ * Copyright (C) 2007-2008 1&1 Internet AG
5 6
  *
6 7
  * This file is part of openser, a free SIP server.
7 8
  *
... ...
@@ -20,6 +21,14 @@
20 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 22
  */
22 23
 
24
+/**
25
+ * \file db/db_res.h
26
+ * \brief Data structure that represents a result from a query.
27
+ *
28
+ * Data structure that represents a result from a database query,
29
+ * it also provides some convenience macros and some memory management
30
+ * functions for result structures.
31
+ */
23 32
 
24 33
 #ifndef DB_RES_H
25 34
 #define DB_RES_H
... ...
@@ -30,34 +39,65 @@
30 39
 #include "db_val.h"
31 40
 
32 41 <