Browse code

- small doxygen updates (group, syntax), small docs update - patch provided from Olle E. Johansson, closes #2025079

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

Henning Westerholt authored on 24/07/2008 15:20:11
Showing 14 changed files
... ...
@@ -12,8 +12,8 @@ Daniel-Constantin Mierla
12 12
 
13 13
    Copyright � 2006 voice-system.ro
14 14
    Revision History
15
-   Revision $Revision$ $Date: 2008-03-19 21:31:30 +0200
16
-                              (Wed, 19 Mar 2008) $
15
+   Revision $Revision$ $Date: 2008-03-19 20:31:30 +0100
16
+                              (Mi, 19 Mär 2008) $
17 17
      __________________________________________________________
18 18
 
19 19
    Table of Contents
... ...
@@ -59,15 +59,15 @@ Chapter 1. Admin Guide
59 59
 
60 60
    The following libraries or applications must be installed
61 61
    before running OpenSER with this module loaded:
62
-     * libmysqlclient-dev - the development libraries of
63
-       mysql-client.
62
+     * mysql - the development libraries forthe Mysql database. In
63
+       some Linux distributions named "libmysqlclient-dev".
64 64
 
65 65
 1.3. Exported Parameters
66 66
 
67 67
 1.3.1. ping_interval (integer)
68 68
 
69
-   Time interval to send ping messages to MySQL server in order to
70
-   keep the connection open.
69
+   Time interval in seconds to send ping messages to MySQL server
70
+   in order to keep the connection open.
71 71
 
72 72
    Default value is 300 (5 min).
73 73
 
... ...
@@ -78,14 +78,14 @@ modparam("db_mysql", "ping_interval", 600)
78 78
 
79 79
 1.3.2. timeout_interval (integer)
80 80
 
81
-   Time interval after that an connection attempt, read or write
82
-   request is aborted. The value counts three times, as several
83
-   retries are done from the driver before it gives up.
81
+   Time interval (in seconds) after that an connection attempt,
82
+   read or write request is aborted. The value counts three times,
83
+   as several retries are done from the driver before it gives up.
84 84
 
85
-   The read timeout parameter is ignored on driver versions prior
86
-   to "5.1.12", "5.0.25" and "4.1.22". The write timeout parameter
87
-   is ignored on version prior to "5.1.12" and "5.0.25", the "4.1"
88
-   release don't support it at all.
85
+   The read timeout parameter is ignored on MySQL driver versions
86
+   prior to "5.1.12", "5.0.25" and "4.1.22". The write timeout
87
+   parameter is ignored on versions prior to "5.1.12" and
88
+   "5.0.25", the "4.1" release don't support it at all.
89 89
 
90 90
    Default value is 2 (6 sec).
91 91
 
... ...
@@ -96,8 +96,8 @@ modparam("db_mysql", "timeout_interval", 2)
96 96
 
97 97
 1.3.3. auto_reconnect (integer)
98 98
 
99
-   Configure the module to auto reconnect to MySQL server if the
100
-   connection was lost.
99
+   Configure whether the module should automatically reconnect to
100
+   MySQL server if the connection was lost.
101 101
 
102 102
    Default value is 1 (1 - on / 0 - off).
103 103
 
... ...
@@ -113,8 +113,8 @@ modparam("auto_reconnect", "auto_reconnect", 0)
113 113
 1.5. Installation
114 114
 
115 115
    Because it dependes on an external library, the mysql module is
116
-   not compiled and installed by default. You can use one of the
117
-   next options.
116
+   not compiled and installed by default. You can use one of these
117
+   options.
118 118
      * - edit the "Makefile" and remove "db_mysql" from
119 119
        "excluded_modules" list. Then follow the standard procedure
120 120
        to install OpenSER: "make all; make install".
... ...
@@ -29,6 +29,18 @@
29 29
  *  2003-03-16  flags export parameter added (janakj)
30 30
  */
31 31
 
32
+/*! \file
33
+ *  \brief DB_MYSQL :: Core
34
+ *  \ingroup db_mysql
35
+ *  Module: \ref db_mysql
36
+ */
37
+
38
+/*! \defgroup db_mysql DB_MYSQL :: the MySQL driver for OpenSER
39
+ *  \brief The OpenSER database interface to the MySQL database
40
+ *  - http://www.mysql.org
41
+ *
42
+ */
43
+
32 44
 #include "../../sr_module.h"
33 45
 #include "../../db/db.h"
34 46
 #include "dbase.h"
... ...
@@ -46,7 +58,7 @@ MODULE_VERSION
46 46
 
47 47
 int db_mysql_bind_api(db_func_t *dbb);
48 48
 
49
-/*
49
+/*! \brief
50 50
  * MySQL database module interface
51 51
  */
52 52
 static cmd_export_t cmds[] = {
... ...
@@ -55,7 +67,7 @@ static cmd_export_t cmds[] = {
55 55
 };
56 56
 
57 57
 
58
-/*
58
+/*! \brief
59 59
  * Exported parameters
60 60
  */
61 61
 static param_export_t params[] = {
... ...
@@ -28,6 +28,13 @@
28 28
  *  2003-03-16  flags export parameter added (janakj)
29 29
  */
30 30
 
31
+/*! \file
32
+ *  \brief DB_MYSQL :: Core
33
+ *  \ingroup db_mysql
34
+ *  Module: \ref db_mysql
35
+ */
36
+
37
+
31 38
 #ifndef DB_MOD_H
32 39
 #define DB_MOD_H
33 40
 
... ...
@@ -23,12 +23,14 @@
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25 25
 
26
-/**
26
+/*!
27 27
  * \file
28 28
  * \brief Implementation of core functions for the MySQL driver.
29 29
  *
30 30
  * This file contains the implementation of core functions for the MySQL
31 31
  * database driver, for example to submit a query or fetch a result.
32
+ * \ingroup db_mysql
33
+ *  Module: \ref db_mysql
32 34
  */
33 35
 
34 36
 #include <stdio.h>
... ...
@@ -23,6 +23,13 @@
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25 25
 
26
+/*! \file
27
+ *  \brief DB_MYSQL :: Core
28
+ *  \ingroup db_mysql
29
+ *  Module: \ref db_mysql
30
+ */
31
+
32
+
26 33
 
27 34
 #ifndef DBASE_H
28 35
 #define DBASE_H
... ...
@@ -35,25 +42,25 @@
35 35
 #include "../../db/db_val.h"
36 36
 #include "../../str.h"
37 37
 
38
-/*
38
+/*! \brief
39 39
  * Initialize database connection
40 40
  */
41 41
 db_con_t* db_mysql_init(const str* _sqlurl);
42 42
 
43 43
 
44
-/*
44
+/*! \brief
45 45
  * Close a database connection
46 46
  */
47 47
 void db_mysql_close(db_con_t* _h);
48 48
 
49 49
 
50
-/*
50
+/*! \brief
51 51
  * Free all memory allocated by get_result
52 52
  */
53 53
 int db_mysql_free_result(db_con_t* _h, db_res_t* _r);
54 54
 
55 55
 
56
-/*
56
+/*! \brief
57 57
  * Do a query
58 58
  */
59 59
 int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
... ...
@@ -61,32 +68,32 @@ int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
61 61
 	     const db_key_t _o, db_res_t** _r);
62 62
 
63 63
 
64
-/*
64
+/*! \brief
65 65
  * fetch rows from a result
66 66
  */
67 67
 int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows);
68 68
 
69 69
 
70
-/*
70
+/*! \brief
71 71
  * Raw SQL query
72 72
  */
73 73
 int db_mysql_raw_query(const db_con_t* _h, const str* _s, db_res_t** _r);
74 74
 
75 75
 
76
-/*
76
+/*! \brief
77 77
  * Insert a row into table
78 78
  */
79 79
 int db_mysql_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n);
80 80
 
81 81
 
82
-/*
82
+/*! \brief
83 83
  * Delete a row from table
84 84
  */
85 85
 int db_mysql_delete(const db_con_t* _h, const db_key_t* _k, const 
86 86
 	db_op_t* _o, const db_val_t* _v, const int _n);
87 87
 
88 88
 
89
-/*
89
+/*! \brief
90 90
  * Update a row in table
91 91
  */
92 92
 int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
... ...
@@ -94,24 +101,24 @@ int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
94 94
 	const int _un);
95 95
 
96 96
 
97
-/*
97
+/*! \brief
98 98
  * Just like insert, but replace the row if it exists
99 99
  */
100 100
 int db_mysql_replace(const db_con_t* handle, const db_key_t* keys, const db_val_t* 	vals, const int n);
101 101
 
102
-/*
102
+/*! \brief
103 103
  * Returns the last inserted ID
104 104
  */
105 105
 int db_last_inserted_id(const db_con_t* _h);
106 106
 
107
-/*
107
+/*! \brief
108 108
  * Insert a row into table, update on duplicate key
109 109
  */
110 110
 int db_insert_update(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
111 111
 	const int _n);
112 112
 
113 113
 
114
-/*
114
+/*! \brief
115 115
  * Store name of table that will be used by
116 116
  * subsequent database functions
117 117
  */
... ...
@@ -35,7 +35,7 @@
35 35
 			<itemizedlist>
36 36
 			<listitem>
37 37
 			<para>
38
-				<emphasis>libmysqlclient-dev</emphasis> - the development libraries of mysql-client.
38
+				<emphasis>mysql</emphasis> - the development libraries forthe Mysql database. In some Linux distributions named "libmysqlclient-dev".
39 39
 			</para>
40 40
 			</listitem>
41 41
 			</itemizedlist>
... ...
@@ -47,7 +47,7 @@
47 47
 	<section>
48 48
 		<title><varname>ping_interval</varname> (integer)</title>
49 49
 		<para>
50
-		Time interval to send ping messages to MySQL server in order to keep
50
+		Time interval in seconds to send ping messages to MySQL server in order to keep
51 51
 		the connection open.
52 52
 		</para>
53 53
 		<para>
... ...
@@ -67,14 +67,14 @@ modparam("db_mysql", "ping_interval", 600)
67 67
 		<section>
68 68
 		<title><varname>timeout_interval</varname> (integer)</title>
69 69
 		<para>
70
-		Time interval after that an connection attempt, read or write request
70
+		Time interval (in seconds) after that an connection attempt, read or write request
71 71
 		is aborted. The value counts three times, as several retries are done
72 72
 		from the driver before it gives up.
73 73
 		</para>
74 74
 		<para>
75
-		The read timeout parameter is ignored on driver versions prior to
75
+		The read timeout parameter is ignored on MySQL driver versions prior to
76 76
 		<quote>5.1.12</quote>, <quote>5.0.25</quote> and <quote>4.1.22</quote>.
77
-		The write timeout parameter is ignored on version prior to <quote>5.1.12</quote>
77
+		The write timeout parameter is ignored on versions prior to <quote>5.1.12</quote>
78 78
 		and <quote>5.0.25</quote>, the <quote>4.1</quote> release don't support it at all.
79 79
 		</para>
80 80
 		<para>
... ...
@@ -94,7 +94,7 @@ modparam("db_mysql", "timeout_interval", 2)
94 94
 	<section>
95 95
 		<title><varname>auto_reconnect</varname> (integer)</title>
96 96
 		<para>
97
-		Configure the module to auto reconnect to MySQL server if the
97
+		Configure whether the module should automatically reconnect to MySQL server if the
98 98
 		connection was lost.
99 99
 		</para>
100 100
 		<para>
... ...
@@ -122,7 +122,7 @@ modparam("auto_reconnect", "auto_reconnect", 0)
122 122
 	<title>Installation</title>
123 123
 		<para>
124 124
 		Because it dependes on an external library, the mysql module is not
125
-		compiled and installed by default. You can use one of the next options.
125
+		compiled and installed by default. You can use one of these options.
126 126
 		</para>
127 127
 		<itemizedlist>
128 128
 			<listitem>
... ...
@@ -21,6 +21,13 @@
21 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22 22
  */
23 23
 
24
+/*! \file
25
+ *  \brief DB_MYSQL :: Connections
26
+ *  \ingroup db_mysql
27
+ *  Module: \ref db_mysql
28
+ */
29
+
30
+
24 31
 #include "my_con.h"
25 32
 #include "db_mysql.h"
26 33
 #include <mysql/mysql_version.h>
... ...
@@ -29,7 +36,7 @@
29 29
 #include "../../ut.h"
30 30
 
31 31
 
32
-/**
32
+/*! \brief
33 33
  * Create a new connection structure,
34 34
  * open the MySQL connection and set reference count to 1
35 35
  */
... ...
@@ -104,7 +111,7 @@ struct my_con* db_mysql_new_connection(const struct db_id* id)
104 104
 }
105 105
 
106 106
 
107
-/**
107
+/*! \brief
108 108
  * Close the connection and release memory
109 109
  */
110 110
 void db_mysql_free_connection(struct pool_con* con)
... ...
@@ -21,6 +21,14 @@
21 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22 22
  */
23 23
 
24
+/*! \file
25
+ *  \brief DB_MYSQL :: Core
26
+ *  \ref my_con.c
27
+ *  \ingroup db_mysql
28
+ *  Module: \ref db_mysql
29
+ */
30
+
31
+
24 32
 #ifndef MY_CON_H
25 33
 #define MY_CON_H
26 34
 
... ...
@@ -32,14 +40,14 @@
32 32
 
33 33
 
34 34
 struct my_con {
35
-	struct db_id* id;        /* Connection identifier */
36
-	unsigned int ref;        /* Reference count */
37
-	struct pool_con* next;   /* Next connection in the pool */
35
+	struct db_id* id;        /*!< Connection identifier */
36
+	unsigned int ref;        /*!< Reference count */
37
+	struct pool_con* next;   /*!< Next connection in the pool */
38 38
 
39
-	MYSQL_RES* res;          /* Actual result */
40
-	MYSQL* con;              /* Connection representation */
41
-	MYSQL_ROW row;           /* Actual row in the result */
42
-	time_t timestamp;        /* Timestamp of last query */
39
+	MYSQL_RES* res;          /*!< Actual result */
40
+	MYSQL* con;              /*!< Connection representation */
41
+	MYSQL_ROW row;           /*!< Actual row in the result */
42
+	time_t timestamp;        /*!< Timestamp of last query */
43 43
 };
44 44
 
45 45
 
... ...
@@ -52,14 +60,14 @@ struct my_con {
52 52
 #define CON_TIMESTAMP(db_con)  (((struct my_con*)((db_con)->tail))->timestamp)
53 53
 
54 54
 
55
-/*
55
+/*! \brief
56 56
  * Create a new connection structure,
57 57
  * open the MySQL connection and set reference count to 1
58 58
  */
59 59
 struct my_con* db_mysql_new_connection(const struct db_id* id);
60 60
 
61 61
 
62
-/*
62
+/*! \brief
63 63
  * Close the connection and release memory
64 64
  */
65 65
 void db_mysql_free_connection(struct pool_con* con);
... ...
@@ -24,6 +24,13 @@
24 24
  */
25 25
 
26 26
 
27
+/*! \file
28
+ *  \brief DB_MYSQL :: Result related functions
29
+ *  \ingroup db_mysql
30
+ *  Module: \ref db_mysql
31
+ */
32
+
33
+
27 34
 #include <string.h>
28 35
 #include <mysql/mysql.h>
29 36
 #include "../../db/db_res.h"
... ...
@@ -34,7 +41,7 @@
34 34
 #include "res.h"
35 35
 
36 36
 
37
-/**
37
+/*! \brief
38 38
  * Get and convert columns from a result
39 39
  */
40 40
 int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
... ...
@@ -130,7 +137,7 @@ int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
130 130
 }
131 131
 
132 132
 
133
-/**
133
+/*! \brief
134 134
  * Convert rows from mysql to db API representation
135 135
  */
136 136
 static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
... ...
@@ -177,7 +184,7 @@ static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
177 177
 }
178 178
 
179 179
 
180
-/**
180
+/*! \brief
181 181
  * Fill the structure with data from database
182 182
  */
183 183
 int db_mysql_convert_result(const db_con_t* _h, db_res_t* _r)
... ...
@@ -23,6 +23,14 @@
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25 25
 
26
+/*! \file
27
+ *  \brief DB_MYSQL :: Result related functions
28
+ *  \ref res.c
29
+ *  \ingroup db_mysql
30
+ *  Module: \ref db_mysql
31
+ */
32
+
33
+
26 34
 #ifndef RES_H
27 35
 #define RES_H
28 36
 
... ...
@@ -23,6 +23,11 @@
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25 25
 
26
+/*! \file
27
+ *  \brief DB_MYSQL :: Row related functions
28
+ *  \ingroup db_mysql
29
+ *  Module: \ref db_mysql
30
+ */
26 31
 
27 32
 #include "../../dprint.h"
28 33
 #include "../../mem/mem.h"
... ...
@@ -32,8 +37,7 @@
32 32
 #include "val.h"
33 33
 #include "row.h"
34 34
 
35
-
36
-/**
35
+/*! \brief
37 36
  * Convert a row from result into db API representation
38 37
  */
39 38
 int db_mysql_convert_row(const db_con_t* _h, db_res_t* _res, db_row_t* _r)
... ...
@@ -23,6 +23,14 @@
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25 25
 
26
+/*! \file
27
+ *  \brief DB_MYSQL :: Row related functions
28
+ *  \ref row.c
29
+ *  \ingroup db_mysql
30
+ *  Module: \ref db_mysql
31
+ */
32
+
33
+
26 34
 #ifndef ROW_H
27 35
 #define ROW_H
28 36
 
... ...
@@ -21,6 +21,11 @@
21 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22 22
  */
23 23
 
24
+/*! \file
25
+ *  \brief DB_MYSQL :: Data conversion
26
+ *  \ingroup db_mysql
27
+ *  Module: \ref db_mysql
28
+ */
24 29
 
25 30
 #include "../../dprint.h"
26 31
 #include "../../db/db_ut.h"
... ...
@@ -31,7 +36,7 @@
31 31
 #include <stdio.h>
32 32
 
33 33
 
34
-/*
34
+/*! \brief
35 35
  * Convert str to db value, does not copy strings
36 36
  */
37 37
 int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l)
... ...
@@ -127,7 +132,7 @@ int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int
127 127
 }
128 128
 
129 129
 
130
-/*
130
+/*! \brief
131 131
  * Used when converting result from a query
132 132
  */
133 133
 int db_mysql_val2str(const db_con_t* _c, const db_val_t* _v, char* _s, int* _len)
... ...
@@ -21,6 +21,14 @@
21 21
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
22 22
  */
23 23
 
24
+/*! \file
25
+ *  \brief DB_MYSQL :: Conversions
26
+ *  \ref val.c
27
+ *  \ingroup db_mysql
28
+ *  Module: \ref db_mysql
29
+ */
30
+
31
+
24 32
 #ifndef VAL_H
25 33
 #define VAL_H
26 34