@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2003 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  * 

  * This file is part of openser, a free SIP server.

  *

@@ -26,6 +27,21 @@

   *  2006-10-10  Added support for retrieving the last inserted ID (Carsten Bock, BASIS AudioNet GmbH)

   */

+/**

+ * \file db/db.c

+ * \brief Generic Database Interface

+ *

+ * This is a generic database interface for modules that need to utilize a

+ * database. The interface should be used by all modules that access database.

+ * The interface will be independent of the underlying database server.

+ * Notes:

+ * If possible, use the predefined macros if you need to access any structure

+ * attributes.

+ * For additional description, see the comments in the sources of mysql module.

+ *

+ * If you want to see more complicated examples of how the API could be used,

+ * take a look at the sources of the usrloc or auth modules.

+ */

 #include "../dprint.h"

 #include "../sr_module.h"

@@ -38,7 +54,6 @@

 #include "db.h"

-

 /* fills mydbf with the corresponding db module callbacks

  * returns 0 on success, -1 on error

  * on error mydbf will contain only 0s */

@@ -164,6 +179,92 @@ int bind_dbmod(char* mod, db_func_t* mydbf)

 }

+/*

+ * Initialize database module

+ * No function should be called before this

+ */

+db_con_t* db_do_init(const char* url, void* (*new_connection)())

+{

+	struct db_id* id;

+	void* con;

+	db_con_t* res;

+

+	int con_size = sizeof(db_con_t) + sizeof(void *);

+	id = 0;

+	res = 0;

+

+	if (!url || !new_connection) {

+		LM_ERR("invalid parameter value\n");

+		return 0;

+	}

+	if (strlen(url) > 255)

+	{

+		LM_ERR("SQL URL too long\n");

+		return 0;

+	}

+	

+	/* this is the root memory for this database connection. */

+	res = (db_con_t*)pkg_malloc(con_size);

+	if (!res) {

+		LM_ERR("no private memory left\n");

+		return 0;

+	}

+	memset(res, 0, con_size);

+

+	id = new_db_id(url);

+	if (!id) {

+		LM_ERR("cannot parse URL '%s'\n", url);

+		goto err;

+	}

+

+	/* Find the connection in the pool */

+	con = pool_get(id);

+	if (!con) {

+		LM_DBG("connection %p not found in pool\n", id);

+		/* Not in the pool yet */

+		con = new_connection(id);

+		if (!con) {

+			LM_ERR("could not add connection to the pool");

+			goto err;

+		}

+		pool_insert((struct pool_con*)con);

+	} else {

+		LM_DBG("connection %p found in pool\n", id);

+	}

+

+	res->tail = (unsigned long)con;

+	return res;

+

+ err:

+	if (id) free_db_id(id);

+	if (res) pkg_free(res);

+	return 0;

+}

+

+

+/*

+ * Shut down database module

+ * No function should be called after this

+ */

+void db_do_close(db_con_t* _h, void (*free_connection)())

+{

+	struct pool_con* con;

+

+	if (!_h) {

+		LM_ERR("invalid parameter value\n");

+		return;

+	}

+

+	con = (struct pool_con*)_h->tail;

+	if (pool_remove(con) == 1) {

+		free_connection(con);

+	}

+

+	pkg_free(_h);

+}

+

+

+

 /*

  * Get version of a table

  * 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)

 	return ret;

 }

+

 /*

- * Initialize database module

- * No function should be called before this

+ * Store name of table that will be used by

+ * subsequent database functions

  */

-db_con_t* db_do_init(const char* url, void* (*new_connection)())

+int db_use_table(db_con_t* _h, const char* _t)

 {

-	struct db_id* id;

-	void* con;

-	db_con_t* res;

-

-	int con_size = sizeof(db_con_t) + sizeof(void *);

-	id = 0;

-	res = 0;

-

-	if (!url) {

+	if ((!_h) || (!_t)) {

 		LM_ERR("invalid parameter value\n");

-		return 0;

-	}

-	if (strlen(url) > 255)

-	{

-		LM_ERR("SQL URL too long\n");

-		return 0;

-	}

-	

-	/* this is the root memory for this database connection. */

-	res = (db_con_t*)pkg_malloc(con_size);

-	if (!res) {

-		LM_ERR("no private memory left\n");

-		return 0;

-	}

-	memset(res, 0, con_size);

-

-	id = new_db_id(url);

-	if (!id) {

-		LM_ERR("cannot parse URL '%s'\n", url);

-		goto err;

-	}

-

-	/* Find the connection in the pool */

-	con = pool_get(id);

-	if (!con) {

-		LM_DBG("connection %p not found in pool\n", id);

-		/* Not in the pool yet */

-		con = new_connection(id);

-		if (!con) {

-			LM_ERR("could not add connection to the pool");

-			goto err;

-		}

-		pool_insert((struct pool_con*)con);

-	} else {

-		LM_DBG("connection %p found in pool\n", id);

+		return -1;

 	}

-	res->tail = (unsigned long)con;

-	return res;

-

- err:

-	if (id) free_db_id(id);

-	if (res) pkg_free(res);

+	CON_TABLE(_h) = _t;

 	return 0;

 }

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2003 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of ser, a free SIP server.

  *

@@ -32,7 +33,7 @@

  */

 /**

- * \file db.h

+ * \file db/db.h

  * \brief Generic Database Interface

  *

  * This is a generic database interface for modules that need to utilize a

@@ -45,7 +46,7 @@

  *

  * If you want to see more complicated examples of how the API could be used,

  * take a look at the sources of the usrloc or auth modules.

-*/

+ */

 #ifndef DB_H

 #define DB_H

@@ -57,6 +58,7 @@

 #include "db_row.h"

 #include "db_res.h"

 #include "db_cap.h"

+#include "db_con.h"

 /**

@@ -67,7 +69,7 @@

  * that table.

  * \param _h database connection handle

  * \param _t table name

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_use_table_f)(db_con_t* _h, const char* _t);

@@ -92,7 +94,7 @@ typedef int (*db_use_table_f)(db_con_t* _h, const char* _t);

  * \see bind_dbmod

  * \param _sqlurl database connection URL

  * \return returns a pointer to the db_con_t representing the connection if it was

-  successful, otherwise 0 is returned.

+ * successful, otherwise 0 is returned

  */

 typedef db_con_t* (*db_init_f) (const char* _sqlurl);

@@ -134,7 +136,7 @@ typedef void (*db_close_f) (db_con_t* _h);

  * \param _nc number of columns in _c parameter

  * \param _o order by statement for query

  * \param _r address of variable where pointer to the result will be stored

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_query_f) (db_con_t* _h, db_key_t* _k,

 			   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,

  * \param _h structure representing database connection

  * \param _r structure for the result

  * \param _n the number of rows that should be fetched

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_fetch_result_f) (db_con_t* _h, db_res_t** _r, int _n);

@@ -167,7 +169,7 @@ typedef int (*db_fetch_result_f) (db_con_t* _h, db_res_t** _r, int _n);

  * \param _h structure representing database connection

  * \param _s the SQL query

  * \param _r structure for the result

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_raw_query_f) (db_con_t* _h, char* _s, db_res_t** _r);

@@ -180,7 +182,7 @@ typedef int (*db_raw_query_f) (db_con_t* _h, char* _s, db_res_t** _r);

  * structure anymore. You must call this function before you call db_query again!

  * \param _h database connection handle

  * \param _r pointer to db_res_t structure to destroy

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_free_result_f) (db_con_t* _h, db_res_t* _r);

@@ -194,7 +196,7 @@ typedef int (*db_free_result_f) (db_con_t* _h, db_res_t* _r);

  * \param _k array of keys (column names) 

  * \param _v array of values for keys specified in _k parameter

  * \param _n number of keys-value pairs int _k and _v parameters

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_insert_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);

@@ -213,7 +215,7 @@ typedef int (*db_insert_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);

  * \param _o array of operators to be used with key-value pairs

  * \param _v array of values that the row must match to be deleted

  * \param _n number of keys-value parameters in _k and _v parameters

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_delete_f) (db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _v, int _n);

@@ -247,7 +249,7 @@ typedef int (*db_update_f) (db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _

  * \param _k key names

  * \param _v values of the keys

  * \param _n number of key=value pairs

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

 */

 typedef int (*db_replace_f) (db_con_t* handle, db_key_t* keys, db_val_t* vals, int n);

@@ -276,7 +278,7 @@ typedef int (*db_last_inserted_id_f) (db_con_t* _h);

  * \param _k key names

  * \param _v values of the keys

  * \param _n number of key=value pairs

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 typedef int (*db_insert_update_f) (db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);

@@ -323,11 +325,33 @@ typedef struct db_func {

  * \see db_func_t

  * \param mod database connection URL or a database module name

  * \param dbf database module callbacks

- * \return returns 0 if everything is OK, otherwise returns value < 0.

+ * \return returns 0 if everything is OK, otherwise returns value < 0

  */

 int bind_dbmod(char* mod, db_func_t* dbf);

+/**

+ * \brief Helper for db_init function.

+ *

+ * This helper method do the actual work for the database specific db_init

+ * functions.

+ * \param url database connection URL

+ * \param (*new_connection)() Pointer to the db specific connection creation method

+ * \return returns a pointer to the db_con_t representing the connection if it was

+   successful, otherwise 0 is returned.

+ */

+db_con_t* db_do_init(const char* url, void* (*new_connection)());

+

+/**

+ * \brief Helper for db_close function.

+ *

+ * This helper method does some work for the closing of a database 

+ * connection. No function should be called after this

+ * \param _h database connection handle

+ * \param (*free_connection) Pointer to the db specifc free_connection method

+ */

+void db_do_close(db_con_t* _h, void (*free_connection)());

+

 /**

  * \brief Get the version of a table.

  *

@@ -339,16 +363,17 @@ int bind_dbmod(char* mod, db_func_t* dbf);

  */

 int table_version(db_func_t* dbf, db_con_t* con, const str* table);

+

 /**

- * \brief Helper for db_init function.

+ * \brief Stores the name of table

  *

- * This helper method do the actual work for the database specific db_init

- * functions.

- * \param url database connection URL

- * \param (*new_connection)() Pointer to the db specific connection creation method

- * \return returns a pointer to the db_con_t representing the connection if it was

-   successful, otherwise 0 is returned.

+ * Stores the name of the table that will be used by subsequent database

+ * functions calls in a db_con_t structure.

+ * \param _h database connection handle

+ * \param _t stored name

+ * \return 0 if everything is ok, otherwise returns value < 0

  */

-db_con_t* db_do_init(const char* url, void* (*new_connection)());

+int db_use_table(db_con_t* _h, const char* _t);

+

 #endif /* DB_H */

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2004 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,36 +21,45 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db_cap.h

+ * \brief Data structures that represents capabilities in the database.

+ *

+ * This file defines data structures that represents certain database

+ * capabilities. It also provides some macros for convenient access to this

+ * values.

+ */

+

 #ifndef DB_CAP_H

 #define DB_CAP_H

-/*

- * Database capabilities

+/**

+ * Represents the capabilities that a database driver supports.

  */

 typedef enum db_cap {

-	DB_CAP_QUERY =     1 << 0,  /* Database driver can query database */

-	DB_CAP_RAW_QUERY = 1 << 1,  /* Database driver can perform raw queries */

-	DB_CAP_INSERT =    1 << 2,  /* Database driver can insert data into database */

-	DB_CAP_DELETE =    1 << 3,  /* Database driver can delete data from database */

-	DB_CAP_UPDATE =    1 << 4,  /* Database driver can update data in the database */

-	DB_CAP_REPLACE =   1 << 5,  /* Replace (also known as INSERT OR UPDATE) support */

-	DB_CAP_FETCH   =   1 << 6,  /* Fetch result support */

-	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /* ID of the last insert */

- 	DB_CAP_INSERT_UPDATE = 1 << 8 /* Database driver can insert data into database and update on duplicate */

+	DB_CAP_QUERY =     1 << 0,  /**< driver can perform queries                                     */

+	DB_CAP_RAW_QUERY = 1 << 1,  /**< driver can perform raw queries                                 */

+	DB_CAP_INSERT =    1 << 2,  /**< driver can insert data                                         */

+	DB_CAP_DELETE =    1 << 3,  /**< driver can delete data                                         */

+	DB_CAP_UPDATE =    1 << 4,  /**< driver can update data                                         */

+	DB_CAP_REPLACE =   1 << 5,  /**< driver can replace (also known as INSERT OR UPDATE) data       */

+	DB_CAP_FETCH   =   1 << 6,  /**< driver supports fetch result queries                           */

+	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /**< driver can return the ID of the last insert operation   */

+ 	DB_CAP_INSERT_UPDATE = 1 << 8 /**< driver can insert data into database and update on duplicate */

 } db_cap_t;

-/*

+/**

  * All database capabilities except raw_query, replace, insert_update and 

  * last_inserted_id which should be checked separately when needed

  */

 #define DB_CAP_ALL (DB_CAP_QUERY | DB_CAP_INSERT | DB_CAP_DELETE | DB_CAP_UPDATE)

-/*

- * True if all the capabilities in cpv are supported by module

+/**

+ * Returns true if all the capabilities in cpv are supported by module

  * represented by dbf, false otherwise

  */

 #define DB_CAPABILITY(dbf, cpv) (((dbf).cap & (cpv)) == (cpv))

deleted file mode 100644

@@ -1,42 +0,0 @@

-/* 

- * $Id$ 

- *

- * Copyright (C) 2001-2003 FhG Fokus

- * Copyright (C) 2007 1und1 Internet AG

- *

- * This file is part of openser, a free SIP server.

- *

- * openser is free software; you can redistribute it and/or modify

- * it under the terms of the GNU General Public License as published by

- * the Free Software Foundation; either version 2 of the License, or

- * (at your option) any later version

- *

- * openser is distributed in the hope that it will be useful,

- * but WITHOUT ANY WARRANTY; without even the implied warranty of

- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

- * GNU General Public License for more details.

- *

- * You should have received a copy of the GNU General Public License 

- * along with this program; if not, write to the Free Software 

- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

- */

-

-#include "db_col.h"

-

-#include "../dprint.h"

-#include "../mem/mem.h"

-

-/*

- * Release memory used by columns

- */

-inline int db_free_columns(db_res_t* _r)

-{

-	if (!_r) {

-		LM_ERR("invalid parameter\n");

-		return -1;

-	}

-

-	if (RES_NAMES(_r)) pkg_free(RES_NAMES(_r));

-	if (RES_TYPES(_r)) pkg_free(RES_TYPES(_r));

-	return 0;

-}

deleted file mode 100644

@@ -1,36 +0,0 @@

-/* 

- * $Id$ 

- *

- * Copyright (C) 2001-2003 FhG Fokus

- *

- * This file is part of openser, a free SIP server.

- *

- * openser is free software; you can redistribute it and/or modify

- * it under the terms of the GNU General Public License as published by

- * the Free Software Foundation; either version 2 of the License, or

- * (at your option) any later version

- *

- * openser is distributed in the hope that it will be useful,

- * but WITHOUT ANY WARRANTY; without even the implied warranty of

- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

- * GNU General Public License for more details.

- *

- * You should have received a copy of the GNU General Public License 

- * along with this program; if not, write to the Free Software 

- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

- */

-

-

-#ifndef DB_COL_H

-#define DB_COL_H

-

-

-#include "db_res.h"

-

-

-/*

- * Release memory used by columns

- */

-int db_free_columns(db_res_t* _r);

-

-#endif /* DB_COL_H */

@@ -2,6 +2,7 @@

  * $Id$ 

  *

  * Copyright (C) 2001-2003 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,25 +21,28 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

-

+/**

+ * \file db/db_con.h

+ * \brief Type that represents a database connection

+ */

 #ifndef DB_CON_H

 #define DB_CON_H

-/*

- * This structure represents a database connection

- * and pointer to this structure is used as a connection

- * handle

+/**

+ * This structure represents a database connection, pointer to this structure

+ * are used as a connection handle from modules uses the db API.

  */

 typedef struct {

-	const char* table;     /* Default table to use */

-	unsigned long tail;    /* Variable length tail

-				* database module specific */    

+	const char* table;     /**< Default table that should be used              */

+	unsigned long tail;    /**< Variable length tail, database module specific */

 } db_con_t;

+/** Return the table of the connection handle */

 #define CON_TABLE(cn)      ((cn)->table)

+/** Return the tail of the connection handle */

 #define CON_TAIL(cn)       ((cn)->tail)

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2005 iptel.org

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,6 +21,11 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_id.c

+ * \brief Functions for parsing a database URL and work with db identifier.

+ */

+

 #include "db_id.h"

 #include "../dprint.h"

 #include "../mem/mem.h"

@@ -239,7 +245,7 @@ struct db_id* new_db_id(const char* url)

 /*

  * Compare two connection identifiers

  */

-unsigned char cmp_db_id(struct db_id* id1, struct db_id* id2)

+unsigned char cmp_db_id(const struct db_id* id1, const struct db_id* id2)

 {

 	if (!id1 || !id2) return 0;

 	if (id1->port != id2->port) return 0;

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2005 iptel.org

+ * Copyright (C) 2007-2008 1&1 Internet AG

  * 

  * This file is part of openser, a free SIP server.

  *

@@ -20,36 +21,47 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_id.c

+ * \brief Functions for parsing a database URL and works with db identifier.

+ */

+

 #ifndef _DB_ID_H

 #define _DB_ID_H

 #include "../str.h"

-

+/** Structure representing a database ID */

 struct db_id {

-	char* scheme;        /* URL scheme */

-	char* username;      /* Username, case sensitive */

-	char* password;      /* Password, case sensitive */

-	char* host;          /* Host or IP, case insensitive */

-	unsigned short port; /* Port number */

-	char* database;      /* Database, case sensitive */

+	char* scheme;        /**< URL scheme */

+	char* username;      /**< Username, case sensitive */

+	char* password;      /**< Password, case sensitive */

+	char* host;          /**< Host or IP, case insensitive */

+	unsigned short port; /**< Port number */

+	char* database;      /**< Database, case sensitive */

 };

-/*

+/**

  * Create a new connection identifier

+ * \param url database URL

+ * \return new allocated db_id structure, NULL on failure

  */

 struct db_id* new_db_id(const char* url);

-/*

+/**

  * Compare two connection identifiers

+ * \param id1 first identifier

+ * \param id2 second identifier

+ * \return 1 if both identifier are equal, 0 if there not equal

  */

-unsigned char cmp_db_id(struct db_id* id1, struct db_id* id2);

+unsigned char cmp_db_id(const struct db_id* id1, const struct db_id* id2);

-/*

+/**

  * Free a connection identifier

+ * \param id the identifier that should released

  */

 void free_db_id(struct db_id* id);

@@ -2,6 +2,7 @@

  * $Id$ 

  *

  * Copyright (C) 2001-2003 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,13 +21,18 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_key.h

+ * \brief Type that represents a database key.

+ */

 #ifndef DB_KEY_H

 #define DB_KEY_H

-/*

- * Type of a database key (column)

+/**

+ * This type represents a database key (column).

+ * Every time you need to specify a key value, this type should be used.

  */

 typedef const char* db_key_t;

@@ -2,6 +2,7 @@

  * $Id$ 

  *

  * Copyright (C) 2001-2003 FhG Fokus

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,20 +21,30 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_op.h

+ * \brief Type that represents a expression operator.

+ */

 #ifndef DB_OP_H

 #define DB_OP_H

+/** operator less than */

 #define OP_LT  "<"

+/** operator greater than */

 #define OP_GT  ">"

+/** operator equal */

 #define OP_EQ  "="

+/** operator less than equal */

 #define OP_LEQ "<="

+/** operator greater than equal */

 #define OP_GEQ ">="

+/** operator negation */

 #define OP_NEQ "!="

-/*

- * Type of a operator

+/**

+ * This type represents an expression operator uses for SQL queries.

  */

 typedef const char* db_op_t;

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2005 iptel.org

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,6 +21,11 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_pool.c

+ * \brief Functions for managing a pool of database connections.

+ */

+

 #include "../dprint.h"

 #include "db_pool.h"

@@ -33,7 +39,7 @@ static struct pool_con* db_pool = 0;

  * the identifier equal to id, NULL is returned

  * when no connection is found

  */

-struct pool_con* pool_get(struct db_id* id)

+struct pool_con* pool_get(const struct db_id* id)

 {

 	struct pool_con* ptr;

@@ -2,6 +2,7 @@

  * $Id$

  *

  * Copyright (C) 2001-2005 iptel.org

+ * Copyright (C) 2007-2008 1&1 Internet AG

  *

  * This file is part of openser, a free SIP server.

  *

@@ -20,6 +21,11 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/**

+ * \file db/db_pool.h

+ * \brief Functions for managing a pool of database connections.

+ */

+

 #ifndef _DB_POOL_H

 #define _DB_POOL_H

@@ -27,7 +33,7 @@

 #include "db_con.h"

-/*

+/**

  * This is a stub that contains all attributes

  * that pool members must have, it is not really

  * used, real connection structures are created

@@ -36,28 +42,30 @@

  * attributes.

  */

 struct pool_con {

-	struct db_id* id;        /* Connection identifier */

-	unsigned int ref;        /* Reference count */

-	struct pool_con* next;   /* Next element in the pool */

+	struct db_id* id;        /**< Connection identifier */

+	unsigned int ref;        /**< Reference count */

+	struct pool_con* next;   /**< Next element in the pool */

 };

-/*

- * Search the pool for a connection with

- * the identifier equal to id, NULL is returned

- * when no connection is found

+/**

+ * Search the pool for a connection with the identifier equal to

+ * the id.

+ * \param id searched id

+ * \return the connection if it could be found, NULL otherwise

  */

-struct pool_con* pool_get(struct db_id* id);

+struct pool_con* pool_get(const struct db_id* id);

-/*

- * Insert a new connection into the pool

+/**

+ * Insert a new connection into the pool.

+ * \param con the inserted connection 

  */

 void pool_insert(struct pool_con* con);

-/*

- * Release connection from the pool, the function

+/**

+ * Release a connection from the pool, the function

  * would return 1 when if the connection is not

  * referenced anymore and thus can be closed and

  * deleted by the backend. The function returns

@@ -65,6 +73,8 @@ void pool_insert(struct pool_con* con);

  * because some other module is still using it.

  * The function returns -1 if the connection is

  * not in the pool.

+ * \param con connection that should be removed

+ * \return 1 if the connection can be freed, 0 if it can't be freed, -1 if not found

  */

 int pool_remove(struct pool_con* con);

new file mode 100644

@@ -0,0 +1,300 @@

+/*

+ * $Id$

+ *

+ * Copyright (C) 2007-2008 1&1 Internet AG

+ *

+ * This file is part of openser, a free SIP server.

+ *

+ * openser is free software; you can redistribute it and/or modify

+ * it under the terms of the GNU General Public License as published by

+ * the Free Software Foundation; either version 2 of the License, or

+ * (at your option) any later version

+ *