Browse code

- add doxygen documentation

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

Henning Westerholt authored on 17/11/2008 19:52:43
Showing 6 changed files
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * Group membership
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -26,7 +24,13 @@
26 24
  * 2003-02-25 - created by janakj
27 25
  * 2004-06-07   updated to the new DB api, added group_db_{bind,init,close,ver}
28 26
  *               (andrei)
29
- *
27
+ */
28
+
29
+/**
30
+ * \file
31
+ * \brief Group membership module
32
+ * \ingroup group
33
+ * - Module: \ref group
30 34
  */
31 35
 
32 36
 
... ...
@@ -41,15 +45,24 @@
41 45
 #include "group.h"
42 46
 #include "group_mod.h"                   /* Module parameters */
43 47
 
44
-
45
-
48
+/*!
49
+ * \brief Extract the username and domain from the SIP message
50
+ *
51
+ * Set the username and domain depending on the value of the SIP
52
+ * message and the group check structure.
53
+ * \param msg SIP message
54
+ * \param gcp group check structure
55
+ * \param username stored username
56
+ * \param domain stored domain
57
+ * \return 0 on success, -1 on failure
58
+ */
46 59
 int get_username_domain(struct sip_msg *msg, group_check_p gcp,
47 60
 											str *username, str *domain)
48 61
 {
49 62
 	struct sip_uri puri;
50 63
 	struct sip_uri *turi;
51 64
 	struct hdr_field* h;
52
-	struct auth_body* c = 0; /* Makes gcc happy */
65
+	struct auth_body* c = 0;
53 66
 	pv_value_t value;
54 67
 
55 68
 	turi = NULL;
... ...
@@ -117,8 +130,12 @@ int get_username_domain(struct sip_msg *msg, group_check_p gcp,
117 130
 
118 131
 
119 132
 
120
-/*
121
- * Check if username in specified header field is in a table
133
+/*!
134
+ * \brief Check if username in specified header field is in a table
135
+ * \param _msg SIP message
136
+ * \param _hf Header field
137
+ * \param _grp checked table
138
+ * \param 1 on success, negative on failure 
122 139
  */
123 140
 int is_user_in(struct sip_msg* _msg, char* _hf, char* _grp)
124 141
 {
... ...
@@ -173,6 +190,11 @@ int is_user_in(struct sip_msg* _msg, char* _hf, char* _grp)
173 190
 }
174 191
 
175 192
 
193
+/*!
194
+ * \brief Initialize the DB connection
195
+ * \param db_url database URL
196
+ * \return 0 on success, -1 on failure
197
+ */
176 198
 int group_db_init(const str* db_url)
177 199
 {
178 200
 	if (group_dbf.init==0){
... ...
@@ -190,6 +212,11 @@ error:
190 212
 }
191 213
 
192 214
 
215
+/*!
216
+ * \brief Bind the DB connection
217
+ * \param db_url database URL
218
+ * \return 0 on success, -1 on failure
219
+ */
193 220
 int group_db_bind(const str* db_url)
194 221
 {
195 222
 	if (db_bind_mod(db_url, &group_dbf)<0){
... ...
@@ -206,6 +233,10 @@ int group_db_bind(const str* db_url)
206 233
 }
207 234
 
208 235
 
236
+/*!
237
+ * \brief Close the DB connection
238
+ * \param db_url database URL
239
+ */
209 240
 void group_db_close(void)
210 241
 {
211 242
 	if (group_dbh && group_dbf.close){
... ...
@@ -213,4 +244,3 @@ void group_db_close(void)
213 244
 		group_dbh=0;
214 245
 	}
215 246
 }
216
-
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * Group membership
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -24,9 +22,14 @@
24 22
  * History:
25 23
  * --------
26 24
  * 2003-02-25 - created by janakj
27
- *
28 25
  */
29 26
 
27
+/**
28
+ * \file
29
+ * \brief Group membership module
30
+ * \ingroup group
31
+ * - Module: \ref group
32
+ */
30 33
 
31 34
 #ifndef GROUP_H
32 35
 #define GROUP_H
... ...
@@ -43,21 +46,51 @@ typedef struct _group_check
43 46
 } group_check_t, *group_check_p;
44 47
 
45 48
 
46
-/*
47
- * extracts username and domain from MSG
49
+/*!
50
+ * \brief Extract the username and domain from the SIP message
51
+ *
52
+ * Set the username and domain depending on the value of the SIP
53
+ * message and the group check structure.
54
+ * \param msg SIP message
55
+ * \param gcp group check structure
56
+ * \param username stored username
57
+ * \param domain stored domain
58
+ * \return 0 on success, -1 on failure
48 59
  */
49 60
 int get_username_domain(struct sip_msg *msg, group_check_p gcp,
50 61
 	str *username, str *domain);
51 62
 
52 63
 
53
-/*
54
- * Check if username in specified header field is in a table
64
+/*!
65
+ * \brief Check if username in specified header field is in a table
66
+ * \param _msg SIP message
67
+ * \param _hf Header field
68
+ * \param _grp checked table
69
+ * \param 1 on success, negative on failure 
55 70
  */
56 71
 int is_user_in(struct sip_msg* _msg, char* _hf, char* _grp);
57 72
 
58 73
 
74
+/*!
75
+ * \brief Initialize the DB connection
76
+ * \param db_url database URL
77
+ * \return 0 on success, -1 on failure
78
+ */
59 79
 int group_db_init(const str* db_url);
80
+
81
+
82
+/*!
83
+ * \brief Bind the DB connection
84
+ * \param db_url database URL
85
+ * \return 0 on success, -1 on failure
86
+ */
60 87
 int group_db_bind(const str* db_url);
88
+
89
+
90
+/*!
91
+ * \brief Close the DB connection
92
+ * \param db_url database URL
93
+ */
61 94
 void group_db_close(void);
62 95
 
63
-#endif /* GROUP_H */
96
+#endif
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$ 
3 3
  *
4
- * Group membership - module interface
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -32,6 +30,19 @@
32 30
  *  2005-10-06 - added support for regexp-based groups (bogdan)
33 31
  */
34 32
 
33
+/**
34
+ * \file
35
+ * \brief Group membership module
36
+ * \ingroup group
37
+ * - Module: \ref group
38
+ */
39
+
40
+/*!
41
+ * \defgroup group GROUP :: The Kamailio group Module
42
+ * This module provides functions to check if a certain user belongs to a
43
+ * group. This group definitions are read from a DB table.
44
+ */
45
+
35 46
 
36 47
 #include <stdio.h>
37 48
 #include <stdlib.h>
... ...
@@ -51,28 +62,27 @@ MODULE_VERSION
51 62
 #define TABLE_VERSION    2
52 63
 #define RE_TABLE_VERSION 1
53 64
 
54
-/*
55
- * Module destroy function prototype
65
+/*!
66
+ * \brief Module destroy function prototype
56 67
  */
57 68
 static void destroy(void);
58 69
 
59 70
 
60
-/*
61
- * Module child-init function prototype
71
+/*!
72
+ * \brief Module child-init function prototype
62 73
  */
63 74
 static int child_init(int rank);
64 75
 
65 76
 
66
-/*
67
- * Module initialization function prototype
77
+/*!
78
+ * \brief Module initialization function prototype
68 79
  */
69 80
 static int mod_init(void);
70 81
 
71
-
72
-/* Header field fixup */
82
+/*! Header field fixup */
73 83
 static int hf_fixup(void** param, int param_no);
74 84
 
75
-
85
+/*! get user group ID fixup */
76 86
 static int get_gid_fixup(void** param, int param_no);
77 87
 
78 88
 
... ...
@@ -101,14 +111,14 @@ static int get_gid_fixup(void** param, int param_no);
101 111
  * Module parameter variables
102 112
  */
103 113
 static str db_url = {DEFAULT_RODB_URL, DEFAULT_RODB_URL_LEN};
104
-/* Table name where group definitions are stored */
114
+/*! Table name where group definitions are stored */
105 115
 str table         = {TABLE, TABLE_LEN}; 
106 116
 str user_column   = {USER_COL, USER_COL_LEN};
107 117
 str domain_column = {DOMAIN_COL, DOMAIN_COL_LEN};
108 118
 str group_column  = {GROUP_COL, GROUP_COL_LEN};
109 119
 int use_domain    = 0;
110 120
 
111
-/* tabel and columns used for re-based groups */
121
+/* table and columns used for regular expression-based groups */
112 122
 str re_table      = {0, 0};
113 123
 str re_exp_column = {RE_EXP_COL, RE_EXP_COL_LEN};
114 124
 str re_gid_column = {RE_GID_COL, RE_GID_COL_LEN};
... ...
@@ -119,7 +129,7 @@ db_func_t group_dbf;
119 129
 db_con_t* group_dbh = 0;
120 130
 
121 131
 
122
-/*
132
+/*!
123 133
  * Exported functions
124 134
  */
125 135
 static cmd_export_t cmds[] = {
... ...
@@ -131,7 +141,7 @@ static cmd_export_t cmds[] = {
131 141
 };
132 142
 
133 143
 
134
-/*
144
+/*!
135 145
  * Exported parameters
136 146
  */
137 147
 static param_export_t params[] = {
... ...
@@ -149,7 +159,7 @@ static param_export_t params[] = {
149 159
 };
150 160
 
151 161
 
152
-/*
162
+/*!
153 163
  * Module interface
154 164
  */
155 165
 struct module_exports exports = {
... ...
@@ -226,11 +236,13 @@ static void destroy(void)
226 236
 }
227 237
 
228 238
 
229
-/*
230
- * Convert HF description string to hdr_field pointer
239
+/*!
240
+ * \brief Convert HF description string to hdr_field pointer
231 241
  *
232
- * Supported strings: 
233
- * "Request-URI", "To", "From", "Credentials"
242
+ * Convert a header field description string to hdr_field structure
243
+ * Supported strings: "Request-URI", "To", "From", "Credentials"
244
+ * \param header field description string
245
+ * \return hdr_field structure on success, NULL on failure
234 246
  */
235 247
 static group_check_p get_hf( char *str1)
236 248
 {
... ...
@@ -272,6 +284,12 @@ static group_check_p get_hf( char *str1)
272 284
 }
273 285
 
274 286
 
287
+/*!
288
+ * \brief Header fixup function
289
+ * \param param fixed parameter
290
+ * \param param_no number of parameters
291
+ * \return 0 on success, negative on failure
292
+ */
275 293
 static int hf_fixup(void** param, int param_no)
276 294
 {
277 295
 	void* ptr;
... ...
@@ -296,6 +314,12 @@ static int hf_fixup(void** param, int param_no)
296 314
 }
297 315
 
298 316
 
317
+/*!
318
+ * \brief Group ID fixup
319
+ * \param param fixed parameter
320
+ * \param param_no number of parameters
321
+ * \return 0 on success, negative on failure
322
+ */
299 323
 static int get_gid_fixup(void** param, int param_no)
300 324
 {
301 325
 	pv_spec_t *sp;
... ...
@@ -326,4 +350,3 @@ static int get_gid_fixup(void** param, int param_no)
326 350
 
327 351
 	return 0;
328 352
 }
329
-
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * Group membership 
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -26,6 +24,13 @@
26 24
  * 2003-02-25 - created by janakj
27 25
  */
28 26
 
27
+/**
28
+ * \file
29
+ * \brief Group membership module
30
+ * \ingroup group
31
+ * - Module: \ref group
32
+ */
33
+
29 34
 
30 35
 #ifndef GROUP_MOD_H
31 36
 #define GROUP_MOD_H
... ...
@@ -39,11 +44,11 @@
39 44
 /*
40 45
  * Module parameters variables
41 46
  */
42
-extern str table;           /* 'group' table name */
43
-extern str user_column;     /* 'user' column name in group table */
44
-extern str domain_column;   /* 'domain' column name in group table */
45
-extern str group_column;    /* "group' column name in group table */
46
-extern int use_domain;      /* Use domain in is_user_in */
47
+extern str table;           /*!< 'group' table name */
48
+extern str user_column;     /*!< 'user' column name in group table */
49
+extern str domain_column;   /*!< 'domain' column name in group table */
50
+extern str group_column;    /*!< "group' column name in group table */
51
+extern int use_domain;      /*!< Use domain in is_user_in */
47 52
 
48 53
 extern str re_table;
49 54
 extern str re_exp_column;
... ...
@@ -55,4 +60,4 @@ extern db_func_t group_dbf;
55 60
 extern db_con_t* group_dbh;
56 61
 
57 62
 
58
-#endif /* GROUP_MOD_H */
63
+#endif
... ...
@@ -24,6 +24,13 @@
24 24
  *  2005-10-06 - created by bogdan
25 25
  */
26 26
 
27
+/**
28
+ * \file
29
+ * \brief Group membership module
30
+ * \ingroup group
31
+ * - Module: \ref group
32
+ */
33
+
27 34
 #include <sys/types.h>
28 35
 #include <regex.h>
29 36
 
... ...
@@ -34,17 +41,23 @@
34 41
 #include "re_group.h"
35 42
 #include "group.h"
36 43
 
37
-
44
+/*! regular expression for groups */
38 45
 struct re_grp {
39 46
 	regex_t       re;
40 47
 	int_str       gid;
41 48
 	struct re_grp *next;
42 49
 };
43 50
 
44
-
51
+/*! global regexp list */
45 52
 static struct re_grp *re_list = 0;
46 53
 
47 54
 
55
+/*!
56
+ * \brief Create a group regexp and add it to the list
57
+ * \param re regular expression string
58
+ * \param gid group ID
59
+ * \return 0 on success, -1 on failure
60
+ */
48 61
 static int add_re(const char *re, int gid)
49 62
 {
50 63
 	struct re_grp *rg;
... ...
@@ -75,7 +88,11 @@ error:
75 88
 }
76 89
 
77 90
 
78
-
91
+/*!
92
+ * \brief Load regular expression rules from a database
93
+ * \param table DB table
94
+ * \return 0 on success, -1 on failure
95
+ */
79 96
 int load_re( str *table )
80 97
 {
81 98
 	db_key_t cols[2];
... ...
@@ -127,7 +144,13 @@ error:
127 144
 }
128 145
 
129 146
 
130
-
147
+/*!
148
+ * \brief Get the user group and compare to the regexp list
149
+ * \param req SIP message
150
+ * \param user user string
151
+ * \param avp AVP value
152
+ * \return number of all matches (positive), -1 on errors or when not found
153
+ */
131 154
 int get_user_group(struct sip_msg *req, char *user, char *avp)
132 155
 {
133 156
 	static char uri_buf[MAX_URI_SIZE];
... ...
@@ -24,14 +24,35 @@
24 24
  *  2005-10-06 - created by bogdan
25 25
  */
26 26
 
27
+/**
28
+ * \file
29
+ * \brief Group membership module
30
+ * \ingroup group
31
+ * - Module: \ref group
32
+ */
33
+
27 34
 #ifndef RE_GROUP_H
28 35
 #define RE_GROUP_H
29 36
 
30 37
 #include "../../str.h"
31 38
 #include "../../parser/msg_parser.h"
32 39
 
40
+
41
+/*!
42
+ * \brief Load regular expression rules from a database
43
+ * \param table DB table
44
+ * \return 0 on success, -1 on failure
45
+ */
33 46
 int load_re(str *table);
34 47
 
48
+
49
+/*!
50
+ * \brief Get the user group and compare to the regexp list
51
+ * \param req SIP message
52
+ * \param user user string
53
+ * \param avp AVP value
54
+ * \return number of all matches (positive), -1 on errors or when not found
55
+ */
35 56
 int get_user_group(struct sip_msg *req, char *user, char *avp);
36 57
 
37 58
 #endif