Browse code

- Doxygen updates on core files - Add project name to doxygen in Makefile

oej authored on 19/10/2009 20:35:43
Showing 22 changed files
... ...
@@ -280,6 +280,7 @@ doxygen:
280 280
 	# disable call graphes, because of the DOT dependencies
281 281
 	(cat ./$(COREPATH)/doc/doxygen/ser.doxygen; \
282 282
 	echo "HAVE_DOT=no" ;\
283
+	echo "PROJECT_NAME=SIP-ROUTER" ;\
283 284
 	echo "PROJECT_NUMBER=$(NAME)-$(RELEASE)" )| doxygen -
284 285
 	-@echo "Doxygen documentation created"
285 286
 
... ...
@@ -52,6 +52,7 @@
52 52
  *  2009-05-04  switched IF_T to rval_expr (andrei)
53 53
  *  2009-09-15  added SET_{FWD,RPL}_NO_CONNECT, SET_{FWD,RPL}_CLOSE (andrei)
54 54
  */
55
+
55 56
 /*!
56 57
  * \file
57 58
  * \brief SIP-router core :: 
... ...
@@ -26,6 +26,13 @@
26 26
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
27 27
  */
28 28
 
29
+/*!
30
+ * \file
31
+ * \brief SIP-router core ::
32
+ * \ingroup core
33
+ * Module: \ref core
34
+ */
35
+
29 36
 
30 37
 #ifndef action_h
31 38
 #define action_h
... ...
@@ -15,8 +15,18 @@
15 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18
+
19
+/*!
20
+ * \file
21
+ * \brief SIP-router core :: Atomic operations and memory barriers
22
+ * \ingroup core
23
+ * Module: \ref core
24
+ * See \ref atomicops
25
+ */
26
+
18 27
 /*
19
- *  atomic operations and memory barriers
28
+ * \page atomicops  Atomic operations and memory barriers
29
+ *
20 30
  *  WARNING: atomic ops do not include memory barriers
21 31
  *  
22 32
  *  memory barriers:
... ...
@@ -24,10 +24,15 @@
24 24
  * along with this program; if not, write to the Free Software
25 25
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 26
  */
27
-/*
28
- * atomic_ops init functions
29
- * (needed for lock intializing if no native asm locks are available
30
- *  for the current arch./compiler combination, see atomic_ops.c)
27
+/*!
28
+ * \file
29
+ * \brief SIP-router core :: atomic_ops init functions
30
+ *
31
+ * \ingroup core
32
+ * Module: \ref core
33
+ *
34
+ * Needed for lock intializing if no native asm locks are available
35
+ *  for the current arch./compiler combination, see \ref atomic_ops.c
31 36
  */
32 37
 /* 
33 38
  * History:
... ...
@@ -38,9 +43,9 @@
38 43
 #ifndef __atomic_ops_init_h
39 44
 #define __atomic_ops_init_h
40 45
 
41
-/* init atomic ops */
46
+/*! \brief init atomic ops */
42 47
 int init_atomic_ops();
43
-/* destroy atomic ops (e.g. frees the locks, if locks are used) */
48
+/*! \brief destroy atomic ops (e.g. frees the locks, if locks are used) */
44 49
 void destroy_atomic_ops();
45 50
 
46 51
 #endif
... ...
@@ -28,7 +28,7 @@
28 28
  */
29 29
 /*!
30 30
  * \file
31
- * \brief SIP-router core :: 
31
+ * \brief SIP-router core :: convert/decode to/from ascii using various bases
32 32
  * \ingroup core
33 33
  * Module: \ref core
34 34
  */
... ...
@@ -17,42 +17,38 @@
17 17
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 18
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 19
  */
20
-/*
20
+/*!
21
+ * \file
22
+ * \brief SIP-router core :: convert/decode to/from ascii using various bases
23
+ *
24
+ * \ingroup core
25
+ *
26
+ * Module: \ref core
27
+ *
28
+ *
21 29
  * Functions:
22
- *  init_basex()                              - inits internal lookup tables
23
- *  HEX_HI(unsigned char c)                   - returns the first 4 bits of
24
- *                                              c converted to a hex digit
25
- *  HEX_LOW(unsigned char c)                  - returns the low 4 bits of
26
- *                                              c converted to a hex digit
27
- *  UNHEX(unsigned char hex_digit)            - converts hex_digit to a
30
+ *  - init_basex()                    : inits internal lookup tables
31
+ *  - HEX_HI(unsigned char c)         : returns the first 4 bits of c converted to a hex digit
32
+ *  - HEX_LOW(unsigned char c)         : returns the low 4 bits of converted to a hex digit
33
+ *  - UNHEX(unsigned char hex_digit)            : converts hex_digit to a
28 34
  *                                              number (0..15); it might
29 35
  *                                              return 0xff for invalid 
30 36
  *                                              digit (but with some compile
31 37
  *                                              option it won't check)
32 38
  *
33
- *  base16_enc(src, src_len, dst, dst_len)    - encode to standard hex
34
- *  base16_dec(src, src_len, dst, dst_len)    - decode from standard hex
35
- *  base16_enc_len(len)                       - length needed to encode len
36
- *                                              bytes (macro)
37
- *  base16_max_dec_len(len)                   - length needed to decode a 
38
- *                                              string of size len
39
+ *  - base16_enc(src, src_len, dst, dst_len)    : encode to standard hex
40
+ *  - base16_dec(src, src_len, dst, dst_len)    : decode from standard hex
41
+ *  - base16_enc_len(len)                       : length needed to encode len bytes (macro)
42
+ *  - base16_max_dec_len(len)                   : length needed to decode a string of size len
39 43
  *
40
- *  base64_enc(src, src_len, dst, dst_len)    - encode to base64, standard
41
- *                                              alphabet
42
- *  base64_dec(src, src_len, dst, dst_len)    - decode from base64, standard
43
- *                                              alphabet
44
- *  base64_enc_len(len)                       - length needed to encode
45
- *                                               len bytes (macro)
46
- *  base64_max_dec_len(len)                   - maximum length needed to
47
- *                                               decode len bytes (macro)
48
- *  base64_dec_len(str, len)                  - size of the decoded str 
44
+ *  - base64_enc(src, src_len, dst, dst_len)    : encode to base64, standard alphabet
45
+ *  - base64_dec(src, src_len, dst, dst_len)    : decode from base64, standard  alphabet
46
+ *  - base64_enc_len(len)                       : length needed to encode len bytes (macro)
47
+ *  - base64_max_dec_len(len)                   : maximum length needed to decode len bytes (macro)
48
+ *  - base64_dec_len(str, len)                  : size of the decoded str 
49
+ *  - q_base64_enc(src, src_len, dst, dst_len)  : encode to special base64 alphabet (non standard)
50
+ *  - q_base64_dec(src, src_len, dst, dst_len)  - decode from special non-standard base64 alphabet
49 51
  *
50
- *
51
- *  q_base64_enc(src, src_len, dst, dst_len)  - encode to special base64
52
- *                                              alphabet (non standard)
53
- *
54
- *  q_base64_dec(src, src_len, dst, dst_len)  - decode from special non-
55
- *                                              standard base64 alphabet
56 52
  *  All the above functions return the size used (in dst) on success and
57 53
  *   0 or a negative number (which is -1*size_needed) on error.
58 54
  *
... ...
@@ -65,6 +61,7 @@
65 61
  *  for some interesting tests and ideeas).
66 62
  *
67 63
  *  Test results for 40 bytes  (typical ser nounce) in average cpu cycles:
64
+<verbatim>
68 65
  *                    lookup   lookup_large lookup8k no-lookup
69 66
  *  base16_enc           211/231  218/199      -       1331
70 67
  *  base16_dec           252/251  236          -       1226
... ...
@@ -73,22 +70,23 @@
73 70
  *  q_base64_enc         -                              288
74 71
  *  q_base64_dec         -                              281
75 72
  *  (see test/basex.txt for more results)
73
+</verbatim>
76 74
  *
77 75
  * Defines:
78
- *  BASE64_LOOKUP_TABLE/NO_BASE64_LOOKUP_TABLE - use (default)/don't use
76
+ *  - BASE64_LOOKUP_TABLE/NO_BASE64_LOOKUP_TABLE : use (default)/don't use
79 77
  *     small lookup tables for conversions (faster in general).
80
- *  BASE64_LOOKUP_LARGE    - use large lookup tables (2560 bytes for 
78
+ *  - BASE64_LOOKUP_LARGE    : use large lookup tables (2560 bytes for 
81 79
  *    encoding and 256 bytes for decoding; without it 64 bytes are used for
82 80
  *    encoding and 85 bytes for decoding.
83
- *  BASE64_LOOKUP_8K - use even larger lookup tables (8K for encoding and
81
+ *  - BASE64_LOOKUP_8K : use even larger lookup tables (8K for encoding and
84 82
  *    256 for decoding); also try to write 2 bytes at a time (short) if
85 83
  *    the destination is 2 byte aligned
86 84
  *
87
- *  BASE16_LOOKUP_TABLE/NO_BASE16_LOOKUP_TABLE - use (default)/don't use
85
+ *  - BASE16_LOOKUP_TABLE/NO_BASE16_LOOKUP_TABLE : use (default)/don't use
88 86
  *     small lookup tables for conversions (faster in general).
89
- *  BASE16_LOOKUP_LARGE  - use large lookup tables (512 bytes for 
87
+ *  - BASE16_LOOKUP_LARGE  : use large lookup tables (512 bytes for 
90 88
  *    encoding and 256 bytes for decoding
91
- *  BASE16_READ_WHOLE_INTS - read an int at a time
89
+ *  - BASE16_READ_WHOLE_INTS : read an int at a time
92 90
  *
93 91
  * History:
94 92
  * --------
... ...
@@ -129,7 +127,7 @@
129 127
 	defined BASE64_LOOKUP_8K
130 128
 #include "endianness.h"
131 129
 
132
-/* aligns p to a type* pointer, type must have a 2^k size */
130
+/*! \brief aligns p to a type* pointer, type must have a 2^k size */
133 131
 #define ALIGN_POINTER(p, type) \
134 132
 	((type*) ((long)((char*)(p)+sizeof(type)-1)&~(long)(sizeof(type)-1)))
135 133
 
... ...
@@ -141,7 +139,7 @@
141 139
 #ifdef BASE16_LOOKUP_TABLE
142 140
 
143 141
 #ifdef BASE16_LOOKUP_LARGE
144
-/* use large tables: 512 for lookup and 256 for decode */
142
+/*! \brief use large tables: 512 for lookup and 256 for decode */
145 143
 
146 144
 extern unsigned char _bx_hexdig_hi[256];
147 145
 extern unsigned char _bx_hexdig_low[256];
... ...
@@ -154,7 +152,7 @@ extern unsigned char _bx_unhexdig256[256];
154 152
 #define UNHEX(h)	_bx_unhexdig256[(h)]
155 153
 
156 154
 #else /* BASE16_LOOKUP_LARGE */
157
-/* use small tabes: 16 bytes for lookup and 32 for decode */
155
+/*! \brief use small tabes: 16 bytes for lookup and 32 for decode */
158 156
 
159 157
 extern unsigned char _bx_hexdig[16+1];
160 158
 
... ...
@@ -254,39 +252,40 @@ extern unsigned char _bx_ub64[0x54+1];
254 252
 
255 253
 
256 254
 
257
-/* lenght needed for encoding l bytes */
255
+/*! \brief lenght needed for encoding l bytes */
258 256
 #define base16_enc_len(l) (l*2)
259
-/* maximum lenght needed for decoding l bytes */
257
+/*! \brief maximum lenght needed for decoding l bytes */
260 258
 #define base16_max_dec_len(l) (l/2)
261
-/* actual space needed for decoding a string b of size l */
259
+/*! \brief actual space needed for decoding a string b of size l */
262 260
 #define base16_dec_len(b, l) base16_max_dec_len(l)
263
-/* minimum valid source len for decoding */
261
+/*! \brief minimum valid source len for decoding */
264 262
 #define base16_dec_min_len() 2
265
-/* minimum valid source len for encoding */
263
+/*! \brief minimum valid source len for encoding */
266 264
 #define base16_enc_min_len() 0
267 265
 
268
-/* space needed for encoding l bytes */
266
+/*! \brief space needed for encoding l bytes */
269 267
 #define base64_enc_len(l) (((l)+2)/3*4)
270
-/* maximum space needed for encoding l bytes */
268
+/*! \brief maximum space needed for encoding l bytes */
271 269
 #define base64_max_dec_len(l) ((l)/4*3)
272
-/* actual space needed for decoding a string b of size l, l>=4 */
270
+/*! \brief actual space needed for decoding a string b of size l, l>=4 */
273 271
 #define base64_dec_len(b, l) \
274 272
 	(base64_max_dec_len(l)-((b)[(l)-2]=='=') -((b)[(l)-1]=='='))
275
-/* minimum valid source len for decoding */
273
+/*! \brief minimum valid source len for decoding */
276 274
 #define base64_dec_min_len() 4
277
-/* minimum valid source len for encoding */
275
+/*! \brief minimum valid source len for encoding */
278 276
 #define base64_enc_min_len() 0
279 277
 
280 278
 
281 279
 #ifdef BASE16_READ_WHOLE_INTS
282 280
 
283
-/* params: 
284
- * returns: size used from the output buffer (dst) on success,
281
+/*! 
282
+ * \params: 
283
+ * \return: size used from the output buffer (dst) on success,
285 284
  *          -size_needed on error
285
+ *
286 286
  * WARNING: the output string is not 0-term
287 287
  */
288
-inline static int base16_enc(unsigned char* src, int slen,
289
-							 unsigned char*  dst, int dlen)
288
+inline static int base16_enc(unsigned char* src, int slen, unsigned char*  dst, int dlen)
290 289
 {
291 290
 	unsigned int* p;
292 291
 	unsigned char* end;
... ...
@@ -454,10 +453,11 @@ inline static int base16_enc(unsigned char* src, int slen,
454 453
 #else /* BASE16_READ_WHOLE_INTS */
455 454
 
456 455
 
457
-/* params: 
458
- * returns: size used from the output buffer (dst) on success,
456
+/*!
457
+ * \return : size used from the output buffer (dst) on success,
459 458
  *          -size_needed on error
460
- * WARNING: the output string is not 0-term
459
+ *
460
+ * \note WARNING: the output string is not 0-term
461 461
  */
462 462
 inline static int base16_enc(unsigned char* src, int slen,
463 463
 							 unsigned char*  dst, int dlen)
... ...
@@ -479,8 +479,7 @@ inline static int base16_enc(unsigned char* src, int slen,
479 479
 
480 480
 #endif /* BASE16_READ_WHOLE_INTS */
481 481
 
482
-inline static int base16_dec(unsigned char* src, int slen,
483
-							 unsigned char* dst, int dlen)
482
+inline static int base16_dec(unsigned char* src, int slen, unsigned char* dst, int dlen)
484 483
 {
485 484
 	unsigned char* end;
486 485
 	int osize;
... ...
@@ -498,8 +497,8 @@ inline static int base16_dec(unsigned char* src, int slen,
498 497
 
499 498
 
500 499
 
501
-/* helper internal function: encodes v (6 bits value)
502
- * returns char ascii encoding on success and 0xff on error
500
+/*! \brief helper internal function: encodes v (6 bits value)
501
+ * \return char ascii encoding on success and 0xff on error
503 502
  * (value out of range) */
504 503
 inline static unsigned char base64_enc_char(unsigned char v)
505 504
 {
... ...
@@ -519,8 +518,8 @@ inline static unsigned char base64_enc_char(unsigned char v)
519 518
 	return 0xff;
520 519
 }
521 520
 
522
-/* helper internal function: decodes a base64 "digit",
523
- * returns value on success (0-63) and 0xff on error (invalid)*/
521
+/*! \brief helper internal function: decodes a base64 "digit",
522
+ * \return value on success (0-63) and 0xff on error (invalid)*/
524 523
 inline static unsigned base64_dec_char(unsigned char v)
525 524
 {
526 525
 	switch(v){
... ...
@@ -557,10 +556,11 @@ inline static unsigned base64_dec_char(unsigned char v)
557 556
 
558 557
 
559 558
 #ifdef BASE64_LOOKUP_8K
560
-/* params: 
561
- * returns: size used from the output buffer (dst) on success ((slen+2)/3*4)
559
+/*!
560
+ * \return : size used from the output buffer (dst) on success ((slen+2)/3*4)
562 561
  *          -size_needed on error
563
- * WARNING: the output string is not 0-term
562
+ *
563
+ * \note WARNING: the output string is not 0-term
564 564
  */
565 565
 inline static int base64_enc(unsigned char* src, int slen,
566 566
 							unsigned char* dst,  int dlen)
... ...
@@ -614,10 +614,10 @@ inline static int base64_enc(unsigned char* src, int slen,
614 614
 	return osize;
615 615
 }
616 616
 #else /*BASE64_LOOKUP_8K*/
617
-/* params: 
618
- * returns: size used from the output buffer (dst) on success ((slen+2)/3*4)
617
+/*! \brief Convert to base64
618
+ * \return size used from the output buffer (dst) on success ((slen+2)/3*4)
619 619
  *          -size_needed on error
620
- * WARNING: the output string is not 0-term
620
+ * \note WARNING: the output string is not 0-term
621 621
  */
622 622
 inline static int base64_enc(unsigned char* src, int slen,
623 623
 							unsigned char* dst,  int dlen)
... ...
@@ -655,10 +655,10 @@ inline static int base64_enc(unsigned char* src, int slen,
655 655
 
656 656
 
657 657
 
658
-/* params: 
659
- * returns: size used from the output buffer (dst) on success (max: slen/4*3)
658
+/*! \brief
659
+ * \return size used from the output buffer (dst) on success (max: slen/4*3)
660 660
  *          -size_needed on error or 0 on bad base64 encoded string
661
- * WARNING: the output string is not 0-term
661
+ * \note WARNING: the output string is not 0-term
662 662
  */
663 663
 inline static int base64_dec(unsigned char* src, int slen,
664 664
 							unsigned char* dst,  int dlen)
... ...
@@ -721,13 +721,12 @@ inline static int base64_dec(unsigned char* src, int slen,
721 721
 
722 722
 
723 723
 
724
-/*
725
- * same as base64_enc but with a different alphabet, that allows simpler and
724
+/*! \brief
725
+ * same as \ref base64_enc() but with a different alphabet, that allows simpler and
726 726
  *  faster enc/dec
727
- * params: 
728
- * returns: size used from the output buffer (dst) on success ((slen+2)/3*4)
727
+ * \return size used from the output buffer (dst) on success ((slen+2)/3*4)
729 728
  *          -size_needed on error
730
- * WARNING: the alphabet includes ":;<>?@[]\`", so it might not be suited
729
+ * \note WARNING: the alphabet includes ":;<>?@[]\`", so it might not be suited
731 730
  *  in all cases (e.g. encoding something in a sip uri).
732 731
  */
733 732
 inline static int q_base64_enc(unsigned char* src, int slen,
... ...
@@ -769,14 +768,13 @@ inline static int q_base64_enc(unsigned char* src, int slen,
769 768
 
770 769
 
771 770
 
772
-/*
773
- * same as base64_enc but with a different alphabet, that allows simpler and
771
+/*! \brief
772
+ * same as \ref base64_enc() but with a different alphabet, that allows simpler and
774 773
  *  faster enc/dec
775
- * params: 
776
- * params: 
777
- * returns: size used from the output buffer (dst) on success (max: slen/4*3)
774
+ *
775
+ * \return size used from the output buffer (dst) on success (max: slen/4*3)
778 776
  *          -size_needed on error or 0 on bad base64 encoded string
779
- * WARNING: the output string is not 0-term
777
+ * \note WARNING: the output string is not 0-term
780 778
  */
781 779
 inline static int q_base64_dec(unsigned char* src, int slen,
782 780
 							unsigned char* dst,  int dlen)
... ...
@@ -15,19 +15,25 @@
15 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18
-/*
18
+/*!
19
+ * \file
20
+ * \brief SIP-router core :: bit scan operations
21
+ * \ingroup core
22
+ * Module: \ref core
23
+ *
19 24
  *  bit scan operations
20
- *  int bit_scan_forward(unsigned long v)   - returns the index of the first
25
+ *
26
+ *  - int bit_scan_forward(unsigned long v)   - returns the index of the first
21 27
  *                                          set bit (undefined value if v==0)
22
- *  int bit_scan_forward32(unsigned int v)   - returns the index of the first
28
+ *  - int bit_scan_forward32(unsigned int v)   - returns the index of the first
23 29
  *                                          set bit (undefined value if v==0)
24
- *  int bit_scan_forward64(long long v)      - returns the index of the first
30
+ *  - int bit_scan_forward64(long long v)      - returns the index of the first
25 31
  *                                          set bit (undefined value if v==0)
26
- *  int bit_scan_reverse(unsigned long v)   - returns the index of the last
32
+ *  - int bit_scan_reverse(unsigned long v)   - returns the index of the last
27 33
  *                                          set bit (undefined value if v==0)
28
- *  int bit_scan_reverse32(unsigned int v)  - returns the index of the last
34
+ *  - int bit_scan_reverse32(unsigned int v)  - returns the index of the last
29 35
  *                                          set bit (undefined value if v==0)
30
- *  int bit_scan_reverse64(long long v)     - returns the index of the last
36
+ *  - int bit_scan_reverse64(long long v)     - returns the index of the last
31 37
  *                                          set bit (undefined value if v==0)
32 38
  *
33 39
  * Config defines:   CC_GCC_LIKE_ASM  - the compiler support gcc style
... ...
@@ -46,7 +52,7 @@
46 52
 
47 53
 #include <limits.h>
48 54
 
49
-/* fix __CPU_i386 -> __CPU_x86 */
55
+/*! \brief fix __CPU_i386 -> __CPU_x86 */
50 56
 #if defined __CPU_i386 && ! defined __CPU_x86
51 57
 #define __CPU_x86
52 58
 #endif
... ...
@@ -59,7 +65,7 @@
59 65
 #endif
60 66
 
61 67
 
62
-/* set default bitscan versions, depending on the architecture
68
+/*! \brief set default bitscan versions, depending on the architecture
63 69
  * In general the order is  asm, debruijn, br, slow for bit_scan_forward
64 70
  *  and asm, br, slow, debruijn for bit_scan_reverse. */
65 71
 #ifdef BIT_SCAN_ASM
... ...
@@ -127,15 +133,15 @@
127 133
 #endif /* __CPU_XXX */
128 134
 
129 135
 
130
-/* try to use the right version for bit_scan_forward(unisgned long l)
136
+/*! \brief try to use the right version for bit_scan_forward(unisgned long l)
131 137
  */
132 138
 #if (defined (ULONG_MAX) && ULONG_MAX > 4294967295) || defined LP64
133
-/* long is 64 bits */
139
+/*! \brief long is 64 bits */
134 140
 #define bit_scan_forward(l)	bit_scan_forward64((unsigned long long)(l))
135 141
 #define bit_scan_reverse(l)	bit_scan_reverse64((unsigned long long)(l))
136 142
 
137 143
 #else
138
-/* long is 32 bits */
144
+/*! \brief long is 32 bits */
139 145
 #define bit_scan_forward(l)	bit_scan_forward32((l))
140 146
 #define bit_scan_reverse(l)	bit_scan_reverse32((l))
141 147
 #endif
... ...
@@ -145,7 +151,7 @@
145 151
 
146 152
 #ifdef BIT_SCAN_DEBRUIJN
147 153
 
148
-/* use a de Bruijn sequence to get the index of the set bit for a number
154
+/*! \brief use a de Bruijn sequence to get the index of the set bit for a number
149 155
  *  of the form 2^k (DEBRUIJN_HASH32() and DEBRUIJN_HASH64()).
150 156
  *  bit_scan_forward & bit_scan_reverse would need first to convert
151 157
  *  the argument to 2^k (where k is the first set bit or last set bit index)-
... ...
@@ -3,19 +3,14 @@
3 3
  *
4 4
  * Copyright (C) 2007 iptelorg GmbH
5 5
  *
6
- * This file is part of ser, a free SIP server.
6
+ * This file is part of SIP-router, a free SIP server.
7 7
  *
8
- * ser is free software; you can redistribute it and/or modify
8
+ * SIP-router is free software; you can redistribute it and/or modify
9 9
  * it under the terms of the GNU General Public License as published by
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18
- * ser is distributed in the hope that it will be useful,
13
+ * SIP-router is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 16
  * GNU General Public License for more details.
... ...
@@ -31,7 +26,7 @@
31 26
  */
32 27
 /*!
33 28
  * \file
34
- * \brief SIP-router core :: 
29
+ * \brief SIP-router core ::  Core configuration
35 30
  * \ingroup core
36 31
  * Module: \ref core
37 32
  */
... ...
@@ -53,56 +48,56 @@
53 48
 #include "cfg_core.h"
54 49
 
55 50
 struct cfg_group_core default_core_cfg = {
56
-	L_WARN, 	/*  print only msg. < L_WARN */
57
-	LOG_DAEMON,	/* log_facility -- see syslog(3) */
58
-	L_DBG,  /* memdbg */
51
+	L_WARN, 	/*!<  print only msg. < L_WARN */
52
+	LOG_DAEMON,	/*!< log_facility -- see syslog(3) */
53
+	L_DBG,  /*!< memdbg */
59 54
 #ifdef USE_DST_BLACKLIST
60 55
 	/* blacklist */
61
-	0, /* dst blacklist is disabled by default */
56
+	0, /*!< dst blacklist is disabled by default */
62 57
 	DEFAULT_BLST_TIMEOUT,
63 58
 	DEFAULT_BLST_MAX_MEM,
64 59
 #endif
65 60
 	/* resolver */
66 61
 #ifdef USE_IPV6
67
-	1,  /* dns_try_ipv6 -- on by default */
62
+	1,  /*!< dns_try_ipv6 -- on by default */
68 63
 #else
69
-	0,  /* dns_try_ipv6 -- off, if no ipv6 support */
64
+	0,  /*!< dns_try_ipv6 -- off, if no ipv6 support */
70 65
 #endif
71
-	0,  /* dns_try_naptr -- off by default */
72
-	30,  /* udp transport preference (for naptr) */
73
-	20,  /* tcp transport preference (for naptr) */
74
-	10,  /* tls transport preference (for naptr) */
75
-	20,  /* sctp transport preference (for naptr) */
76
-	-1, /* dns_retr_time */
77
-	-1, /* dns_retr_no */
78
-	-1, /* dns_servers_no */
79
-	1,  /* dns_search_list */
80
-	1,  /* dns_search_fmatch */
81
-	0,  /* dns_reinit */
66
+	0,  /*!< dns_try_naptr -- off by default */
67
+	30,  /*!< udp transport preference (for naptr) */
68
+	20,  /*!< tcp transport preference (for naptr) */
69
+	10,  /*!< tls transport preference (for naptr) */
70
+	20,  /*!< sctp transport preference (for naptr) */
71
+	-1, /*!< dns_retr_time */
72
+	-1, /*!< dns_retr_no */
73
+	-1, /*!< dns_servers_no */
74
+	1,  /*!< dns_search_list */
75
+	1,  /*!< dns_search_fmatch */
76
+	0,  /*!< dns_reinit */
82 77
 	/* DNS cache */
83 78
 #ifdef USE_DNS_CACHE
84
-	1,  /* use_dns_cache -- on by default */
85
-	0,  /* dns_cache_flags */
86
-	0,  /* use_dns_failover -- off by default */
87
-	0,  /* dns_srv_lb -- off by default */
88
-	DEFAULT_DNS_NEG_CACHE_TTL, /* neg. cache ttl */
89
-	DEFAULT_DNS_CACHE_MIN_TTL, /* minimum ttl */
90
-	DEFAULT_DNS_CACHE_MAX_TTL, /* maximum ttl */
91
-	DEFAULT_DNS_MAX_MEM, /* dns_cache_max_mem */
92
-	0, /* dns_cache_del_nonexp -- delete only expired entries by default */
79
+	1,  /*!< use_dns_cache -- on by default */
80
+	0,  /*!< dns_cache_flags */
81
+	0,  /*!< use_dns_failover -- off by default */
82
+	0,  /*!< dns_srv_lb -- off by default */
83
+	DEFAULT_DNS_NEG_CACHE_TTL, /*!< neg. cache ttl */
84
+	DEFAULT_DNS_CACHE_MIN_TTL, /*!< minimum ttl */
85
+	DEFAULT_DNS_CACHE_MAX_TTL, /*!< maximum ttl */
86
+	DEFAULT_DNS_MAX_MEM, /*!< dns_cache_max_mem */
87
+	0, /*!< dns_cache_del_nonexp -- delete only expired entries by default */
93 88
 #endif
94 89
 #ifdef PKG_MALLOC
95
-	0, /* mem_dump_pkg */
90
+	0, /*!< mem_dump_pkg */
96 91
 #endif
97 92
 #ifdef SHM_MEM
98
-	0, /* mem_dump_shm */
93
+	0, /*!< mem_dump_shm */
99 94
 #endif
100
-	DEFAULT_MAX_WHILE_LOOPS, /* max_while_loops */
101
-	0, /* udp_mtu (disabled by default) */
102
-	0, /* udp_mtu_try_proto -> default disabled */
103
-	0,  /* force_rport */
104
-	L_DBG, /* memlog */
105
-	1 /* mem_summary -flags: 0 off, 1 shm/pkg_status, 2 shm/pkg_sums */
95
+	DEFAULT_MAX_WHILE_LOOPS, /*!< max_while_loops */
96
+	0, /*!< udp_mtu (disabled by default) */
97
+	0, /*!< udp_mtu_try_proto -> default disabled */
98
+	0,  /*!< force_rport */
99
+	L_DBG, /*!< memlog */
100
+	1 /*!< mem_summary -flags: 0 off, 1 shm/pkg_status, 2 shm/pkg_sums */
106 101
 };
107 102
 
108 103
 void	*core_cfg = &default_core_cfg;
... ...
@@ -36,6 +36,14 @@
36 36
  * -------
37 37
  *  2007-12-03	Initial version (Miklos)
38 38
  */
39
+/*!
40
+ * \file
41
+ * \brief SIP-router core :: Core configuration
42
+ * \ingroup core
43
+ *
44
+ * Module: \ref core
45
+ */
46
+
39 47
 
40 48
 #ifndef _CFG_CORE_H
41 49
 #define _CFG_CORE_H
... ...
@@ -44,15 +52,16 @@
44 52
 
45 53
 extern void	*core_cfg;
46 54
 
55
+/*! \brief configuration default values */
47 56
 struct cfg_group_core {
48 57
 	int	debug;
49 58
 	int	log_facility;
50
-	int memdbg; /** < log level for memory debugging messages */
59
+	int memdbg; /*!< log level for memory debugging messages */
51 60
 #ifdef USE_DST_BLACKLIST
52 61
 	/* blacklist */
53
-	int	use_dst_blacklist; /* 1 if blacklist is enabled */
54
-	unsigned int	blst_timeout; /* blacklist entry ttl */
55
-	unsigned int	blst_max_mem; /* maximum memory used for the
62
+	int	use_dst_blacklist; /*!< 1 if blacklist is enabled */
63
+	unsigned int	blst_timeout; /*!< blacklist entry ttl */
64
+	unsigned int	blst_max_mem; /*!< maximum memory used for the
56 65
 					blacklist entries */
57 66
 #endif
58 67
 	/* resolver */
... ...
@@ -87,11 +96,11 @@ struct cfg_group_core {
87 96
 	int mem_dump_shm;
88 97
 #endif
89 98
 	int max_while_loops;
90
-	int udp_mtu; /**< maximum send size for udp, if > try another protocol*/
91
-	int udp_mtu_try_proto; /**< if packet> udp_mtu, try proto (e.g. TCP) */
92
-	int force_rport; /**< if set rport will always be forced*/
93
-	int memlog; /** < log level for memory status/summary info */
94
-	int mem_summary; /**< display memory status/summary info on exit */
99
+	int udp_mtu; /*!< maximum send size for udp, if > try another protocol*/
100
+	int udp_mtu_try_proto; /*!< if packet> udp_mtu, try proto (e.g. TCP) */
101
+	int force_rport; /*!< if set rport will always be forced*/
102
+	int memlog; /*!< log level for memory status/summary info */
103
+	int mem_summary; /*!< display memory status/summary info on exit */
95 104
 };
96 105
 
97 106
 extern struct cfg_group_core default_core_cfg;
... ...
@@ -25,12 +25,41 @@
25 25
  * \file
26 26
  * \brief SIP-router core :: 
27 27
  * \ingroup core
28
+ *
28 29
  * Module: \ref core
30
+ *
31
+ * See \ref ConfigEngine
32
+ *
33
+ * \page ConfigEngine
34
+ * In file \ref cfg_parser.c 
35
+ * Configuration examples
36
+ * - \ref ConfigExample1
37
+ * - \ref ConfigExample2
38
+ * - \ref ConfigExample3
39
+ * - \ref ConfigExample4
40
+ * - \ref ConfigExample5
41
+ * - \ref ConfigExample6
42
+ * - \ref ConfigExample7
43
+ * - \ref ConfigExample8
44
+ *
45
+ * <b>Run-time Allocated Destination Variables</b>
46
+ * - the destination variable pointers in arrays are assigned at compile time
47
+ * - The address of variables allocated on the heap (typically in dynamically allocated
48
+ *   structures) is not know and thus we need to assign NULL initially and change the pointer
49
+ *   at runtime.
50
+ *   (provide an example).
51
+ *
52
+ * <b>Built-in parsing functions</b>
53
+ *
54
+ * *_val functions parse the whole option body (including =)
55
+ */
56
+
29 57
  */
30 58
 
31 59
 
32
-/** Example 1: Options without values
60
+/*! \page ConfigExample1  Configuration engine Example 1: Options without values
33 61
  *
62
+\verbatim
34 63
  *	str file = STR_STATIC_INIT("test.cfg");
35 64
  *	cfg_parser_t* parser;
36 65
  *	int feature_a = 0, feature_b = 0;
... ...
@@ -56,17 +85,21 @@
56 85
  *	}
57 86
  *
58 87
  *	cfg_parser_close(parser);
88
+\endverbatim
59 89
  */
60 90
 
61
-/** Example 2: Options with integer values
91
+/*! \page ConfigExample2  Configuration engine Example 2: Options with integer values
92
+\verbatim
62 93
  * 	cfg_option_t options[] = {
63 94
  *		{"max_number",   .param = &max_number,   .f = cfg_parse_int_val },
64 95
  *		{"extra_checks", .param = &extra_checks, .f = cfg_parse_bool_val},
65 96
  *		{0}
66 97
  *	};
98
+\endverbatim
67 99
  */
68 100
 
69
-/** Example 3: Enum options
101
+/*! \page ConfigExample3 Configuration engine Example 3: Enum options
102
+\verbatim
70 103
  * int scope;
71 104
  *
72 105
  *	cfg_option_t scopes[] = {
... ...
@@ -83,10 +116,12 @@
83 116
  *		{"scope", .param = scopes, .f = cfg_parse_enum_val},
84 117
  *		{0}
85 118
  *	};
119
+\endverbatim
86 120
  */
87 121
 
88
-/** Example 4: Options with string values
89
- * 	str filename = STR_NULL;
122
+/*! \page ConfigExample4 Configuration engine Example 4: Options with string values
123
+\verbatim
124
+* 	str filename = STR_NULL;
90 125
  *
91 126
  *	cfg_option_t options[] = {
92 127
  *		{"filename", .param = &filename, .f = cfg_parse_str_val},
... ...
@@ -97,37 +132,27 @@
97 132
  *   by a subsequent call
98 133
  * - There are flags to tell the function to copy the resuting string in a pkg, shm, glibc,
99 134
  *   or static buffers
135
+\endverbatim
100 136
  */
101 137
 
102
-/** Example 5: Custom value parsing
138
+/*! \page ConfigExample5 Configuration engine Example 5: Custom value parsing
103 139
  * TBD
104 140
  */
105 141
 
106
-/** Example 6: Parsing Sections
142
+/*! \page ConfigExample6 Configuration engine Example 6: Parsing Sections
107 143
  * TBD
108 144
  */
109 145
 
110
-/** Example 7: Default Options
146
+/*! \page ConfigExample7 Configuration engine Example 7: Default Options
111 147
  * TBD
112 148
  */
113 149
 
114
-/** Example 8: Memory management of strings
115
- * - Data types with fixed size are easy, they can be copied into a pre-allocated memory
150
+/*! \page ConfigExample8 Configuration engine Example 8: Memory management of strings
151
+ *
152
+ * Data types with fixed size are easy, they can be copied into a pre-allocated memory
116 153
  * buffer, strings cannot because their length is unknown.
117 154
  */
118 155
 
119
-/** Run-time Allocated Destination Variables
120
- * - the destination variable pointers in arrays are assigned at compile time
121
- * - The address of variables allocated on the heap (typically in dynamically allocated
122
- *   structures) is not know and thus we need to assign NULL initially and change the pointer
123
- *   at runtime.
124
- *   (provide an example).
125
- */
126
-
127
-/** Built-in parsing functions
128
- * *_val functions parse the whole option body (including =)
129
- */
130
-
131 156
 #include "cfg_parser.h"
132 157
 
133 158
 #include "mem/mem.h"
... ...
@@ -142,20 +167,20 @@
142 167
 #include <libgen.h>
143 168
 
144 169
 
145
-/* The states of the lexical scanner */
170
+/*! \brief The states of the lexical scanner */
146 171
 enum st {
147
-	ST_S,  /**< Begin */
148
-	ST_A,  /**< Alphanumeric */
149
-	ST_AE, /**< Alphanumeric escaped */
150
-	ST_Q,  /**< Quoted */
151
-	ST_QE, /**< Quoted escaped */
152
-	ST_C,  /**< Comment */
153
-	ST_CE, /**< Comment escaped */
154
-	ST_E,  /**< Escaped */
172
+	ST_S,  /*!< Begin */
173
+	ST_A,  /*!< Alphanumeric */
174
+	ST_AE, /*!< Alphanumeric escaped */
175
+	ST_Q,  /*!< Quoted */
176
+	ST_QE, /*!< Quoted escaped */
177
+	ST_C,  /*!< Comment */
178
+	ST_CE, /*!< Comment escaped */
179
+	ST_E,  /*!< Escaped */
155 180
 };
156 181
 
157 182
 
158
-/* Test for alphanumeric characters */
183
+/*! \brief Test for alphanumeric characters */
159 184
 #define IS_ALPHA(c) \
160 185
     (((c) >= 'a' && (c) <= 'z') || \
161 186
      ((c) >= 'A' && (c) <= 'Z') || \
... ...
@@ -163,7 +188,7 @@ enum st {
163 188
      (c) == '_')
164 189
 
165 190
 
166
-/* Test for delimiter characters */
191
+/*! \brief Test for delimiter characters */
167 192
 #define IS_DELIM(c) \
168 193
     ((c) == '=' || \
169 194
      (c) == ':' || \
... ...
@@ -188,7 +213,7 @@ enum st {
188 213
      (c) == '\'')
189 214
 
190 215
 
191
-/* Whitespace characters */
216
+/*! \brief Whitespace characters */
192 217
 #define IS_WHITESPACE(c) ((c) == ' ' || (c) == '\t' || (c) == '\r') 
193 218
 #define IS_QUOTE(c)      ((c) == '\"')  /* Quote characters */
194 219
 #define IS_COMMENT(c)    ((c) == '#')   /* Characters that start comments */
... ...
@@ -196,9 +221,8 @@ enum st {
196 221
 #define IS_EOL(c)        ((c) == '\n')  /* End of line */
197 222
 
198 223
 
199
-/*
200
- * Append character to the value of current
201
- * token
224
+/*! \brief
225
+ * Append character to the value of current token
202 226
  */
203 227
 #define PUSH(c)                            \
204 228
     if (token->val.len >= MAX_TOKEN_LEN) { \
... ...
@@ -213,7 +237,7 @@ enum st {
213 237
     token->val.s[token->val.len++] = (c);
214 238
 
215 239
 
216
-/*
240
+/*! \brief
217 241
  * Return current token from the lexical analyzer
218 242
  */
219 243
 #define RETURN(c)               \
... ...
@@ -224,7 +248,7 @@ enum st {
224 248
     return 0;
225 249
 
226 250
 
227
-/*
251
+/*! \brief
228 252
  * Get next character and update counters
229 253
  */
230 254
 #define READ_CHAR      \
... ...
@@ -21,6 +21,15 @@
21 21
  * with this program; if not, write to the Free Software Foundation, Inc., 
22 22
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 23
  */
24
+/*!
25
+ * \file
26
+ * \brief SIP-router core :: Standalone Configuration File Parser
27
+ *
28
+ * \ingroup core
29
+ * Module: \ref core
30
+ *
31
+ * See \ref ConfigEngine
32
+ */
24 33
 
25 34
 #ifndef _CFG_PARSER_H
26 35
 #define _CFG_PARSER_H
... ...
@@ -28,23 +37,24 @@
28 37
 #include "str.h"
29 38
 #include <stdio.h>
30 39
 
31
-#define MAX_TOKEN_LEN 512 /**< Token names cannot be longer than this value */
40
+#define MAX_TOKEN_LEN 512 /*!< Token names cannot be longer than this value */
32 41
 
33 42
 
43
+/*! \brief Configuration flags */
34 44
 typedef enum cfg_flags {
35
-	/** Extended tokens can contain also delimiters, in addition to
45
+	/*! \brief Extended tokens can contain also delimiters, in addition to
36 46
 	 * alpha-numeric characters, this is used on the righ side of assignments
37 47
 	 * where no quotes are used.
38 48
 	 */
39 49
 	CFG_EXTENDED_ALPHA = (1 << 0),
40 50
 
41
-	/** The parser performs case-insensitive comparisons of token strings by
51
+	/*! \brief The parser performs case-insensitive comparisons of token strings by
42 52
 	 * default. The parser will use case-sensitive comparison instead if this
43 53
 	 * flag is set.
44 54
 	 */
45 55
 	CFG_CASE_SENSITIVE = (1 << 1), 
46 56
 
47
-	/** This is a flag that can be set in the last element of cfg_option
57
+	/*! \brief This is a flag that can be set in the last element of cfg_option
48 58
 	 * arrays (this is the one with 0 as token name). When this flag is set
49 59
 	 * then the value or parsing function of the element will be used for
50 60
 	 * options that do not match any other element in the array.
... ...
@@ -52,30 +62,30 @@ typedef enum cfg_flags {
52 62
 	CFG_DEFAULT = (1 << 2),
53 63
 
54 64
 
55
-	/** When this flag is set then the name of the options is a prefix and all
65
+	/*! \brief When this flag is set then the name of the options is a prefix and all
56 66
 	 * options that have the same prefix will be matched by this entry.
57 67
 	 */
58 68
 	CFG_PREFIX = (1 << 3),
59 69
 
60
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
70
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
61 71
 	 * pkg_malloc, if the destination varaiable contains a pointer to a buffer
62 72
 	 * already then it will be freed with pkg_free first.
63 73
 	 */
64 74
 	CFG_STR_PKGMEM = (1 << 4),
65 75
 
66
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
76
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
67 77
 	 * shm_malloc, if the destination variable contains a pointer to a buffer
68 78
 	 * already then it will be freed with shm_free first.
69 79
 	 */
70 80
 	CFG_STR_SHMMEM = (1 << 5),
71 81
 
72
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
82
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
73 83
 	 * malloc, if the destination variable contains a pointer to a buffer
74 84
 	 * already then it will be freed with free first.
75 85
 	 */
76 86
 	CFG_STR_MALLOC = (1 << 6),
77 87
 
78
-	/** The result of cfg_parse_str_val will be copied into a pre-allocated
88
+	/*! \brief The result of cfg_parse_str_val will be copied into a pre-allocated
79 89
 	 * buffer with a fixed size, a pointer to str variable which contains the
80 90
 	 * buffer and its size is passed to the function in parameter 'param'.
81 91
 	 */
... ...
@@ -91,14 +101,14 @@ enum cfg_token_type {
91 101
 };
92 102
 
93 103
 
94
-/** Structure representing a lexical token */
104
+/*! \brief Structure representing a lexical token */
95 105
 typedef struct cfg_token {
96 106
 	char buf [MAX_TOKEN_LEN];
97
-	int type;  /**< Token type */
98
-	str val;   /**< Token value */
99
-	struct {   /**< Position of first and last character of token in file */
100
-		int line; /**< The starting/ending line of the token */
101
-		int col;  /**< The starting/ending column of the token */
107
+	int type;  /*!< Token type */
108
+	str val;   /*!< Token value */
109
+	struct {   /*!< Position of first and last character of token in file */
110
+		int line; /*!< The starting/ending line of the token */
111
+		int col;  /*!< The starting/ending column of the token */
102 112
 	} start, end;
103 113
 } cfg_token_t;
104 114
 
... ...
@@ -109,31 +119,32 @@ typedef int (*cfg_func_f)(void* param, struct cfg_parser* st,
109 119
 						  unsigned int flags);
110 120
 
111 121
 
112
-/** Token mapping structure.
122
+/*! \brief Token mapping structure.
123
+ *
113 124
  * This structure is used to map tokens to values or function calls. Arrays of
114 125
  * such structures are typically provided by the caller of the parser.
115 126
  */
116 127
 typedef struct cfg_option {
117
-	char* name;    /**< Token name */
128
+	char* name;    /*!< Token name */
118 129
 	unsigned int flags;
119
-	void* param;   /**< Pointer to the destination variable */
120
-	int val;       /**< Value */
121
-	cfg_func_f f;  /**< Parser function to be called */
130
+	void* param;   /*!< Pointer to the destination variable */
131
+	int val;       /*!< Value */
132
+	cfg_func_f f;  /*!< Parser function to be called */
122 133
 } cfg_option_t;
123 134
 
124 135
 
125
-/* Parser state */
136
+/*! \brief Parser state */
126 137
 typedef struct cfg_parser {
127
-	FILE* f;                 /**< Handle of the currently open file */
128
-	char* file;              /**< Current file name */
129
-	int line;                /**< Current line */
130
-	int col;                 /**< Column index */
131
-	struct cfg_option* options; /**< Array of supported options */
138
+	FILE* f;                 /*!< Handle of the currently open file */
139
+	char* file;              /*!< Current file name */
140
+	int line;                /*!< Current line */
141
+	int col;                 /*!< Column index */
142
+	struct cfg_option* options; /*!< Array of supported options */
132 143
 	struct {
133
-		cfg_func_f parser;   /**< Section parser function */
134
-		void* param;         /**< Parameter value for the parser function */
144
+		cfg_func_f parser;   /*!< Section parser function */
145
+		void* param;         /*!< Parameter value for the parser function */
135 146
 	} section;
136
-	struct cfg_token* cur_opt; /**< Current option */
147
+	struct cfg_token* cur_opt; /*!< Current option */
137 148
 } cfg_parser_t;
138 149
 
139 150
 
... ...
@@ -151,7 +162,7 @@ void cfg_parser_close(struct cfg_parser* st);
151 162
 
152 163
 struct cfg_option* cfg_lookup_token(struct cfg_option* options, str* token);
153 164
 
154
-/** Interface to the lexical scanner */
165
+/*! ! \briefInterface to the lexical scanner */
155 166
 int cfg_get_token(struct cfg_token* token, struct cfg_parser* st, unsigned int flags);
156 167
 
157 168
 /* Commonly needed parser functions */
... ...
@@ -160,13 +171,13 @@ int cfg_eat_equal(struct cfg_parser* st, unsigned int flags);
160 171
 
161 172
 int cfg_eat_eol(struct cfg_parser* st, unsigned int flags);
162 173
 
163
-/* Parse section identifier of form [section]. The function expects parameter
174
+/*! \brief Parse section identifier of form [section]. The function expects parameter
164 175
  * param to be of type (str*). The result string is allocated using pkg_malloc
165 176
  * and is zero terminated. To free the memory use pkg_free(((str*)param)->s)
166 177
  */
167 178
 int cfg_parse_section(void* param, struct cfg_parser* st, unsigned int flags);
168 179
 
169
-/* Parse string parameter value, either quoted or unquoted */
180
+/*! \brief Parse string parameter value, either quoted or unquoted */
170 181
 int cfg_parse_str_opt(void* param, struct cfg_parser* st, unsigned int flags);
171 182
 
172 183
 int cfg_parse_str(void* param, struct cfg_parser* st, unsigned int flags);
... ...
@@ -175,12 +186,12 @@ int cfg_parse_enum_opt(void* param, struct cfg_parser* st, unsigned int flags);
175 186
 
176 187
 int cfg_parse_enum(void* param, struct cfg_parser* st, unsigned int flags);
177 188
 
178
-/* Parser integer parameter value */
189
+/*! \brief Parser integer parameter value */
179 190
 int cfg_parse_int_opt(void* param, struct cfg_parser* st, unsigned int flags);
180 191
 
181 192
 int cfg_parse_int(void* param, struct cfg_parser* st, unsigned int flags);
182 193
 
183
-/* Parse boolean parameter value */
194
+/*! \brief Parse boolean parameter value */
184 195
 int cfg_parse_bool_opt(void* param, struct cfg_parser* st, unsigned int flags);
185 196
 
186 197
 int cfg_parse_bool(void* param, struct cfg_parser* st, unsigned int flags);
... ...
@@ -27,6 +27,14 @@
27 27
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
28 28
  */
29 29
 
30
+/*!
31
+ * \file
32
+ * \brief SIP-router core :: circular list maintenance macros
33
+ *
34
+ * \ingroup core
35
+ * Module: \ref core
36
+ */
37
+
30 38
 /* History:
31 39
  * --------
32 40
  *  2005-08-08  created by andrei
... ...
@@ -44,9 +52,10 @@
44 52
 
45 53
 
46 54
 
47
-/* adds an entire sublist { s,e } (including s & e )
55
+/*! \brief adds an entire sublist { s,e } (including s & e )
48 56
  * after head
49
- * WARNING: clist_insert_sublist(head, n, n->prev) won't work,
57
+ *
58
+ * \note WARNING: clist_insert_sublist(head, n, n->prev) won't work,
50 59
  *          same for clist_insert_sublist(head, n->next, n)
51 60
  *  (macro!), use  e=n->prev; clist_insert_sublist(head, n, e, ...)
52 61
  *  instead!
... ...
@@ -61,8 +70,9 @@
61 70
 
62 71
 
63 72
 
64
-/* appends an entire sublist { s,e } (including s & e )
73
+/*! \brief appends an entire sublist { s,e } (including s & e )
65 74
  * at the end of the list
75
+ *
66 76
  * WARNING: clist_append_sublist(head, n, n->prev, ...) won't work,
67 77
  *  (macro!), use  e=n->prev; clist_append_sublist(head, n, e, ...)
68 78
  *  instead!
... ...
@@ -78,7 +88,7 @@
78 88
 
79 89
 
80 90
 
81
-/* remove sublist { s,e } (including s & e )
91
+/*! \brief remove sublist { s,e } (including s & e )
82 92
  * always, if start is the beginning of the list use
83 93
  * clist_rm_sublist(head->next, e, next, prev )
84 94
  * WARNING: clist_rm_sublist(n, n->prev, ...) won't work,
... ...
@@ -92,29 +102,29 @@
92 102
 
93 103
 
94 104
 
95
-/* insert after (head) */
105
+/*! \brief insert after (head) */
96 106
 #define clist_insert(head, c, next, prev) \
97 107
 	clist_insert_sublist(head, c, c, next, prev)
98 108
 
99 109
 
100 110
 
101
-/* append at the end of the list (head->prev) */
111
+/*! \brief  append at the end of the list (head->prev) */
102 112
 #define clist_append(head, c, next, prev) \
103 113
 	clist_append_sublist(head, c, c, next, prev)
104 114
 
105 115
 
106 116
 
107
-/* remove and element */
117
+/*! \brief  remove and element */
108 118
 #define clist_rm(c, next, prev) \
109 119
 	clist_rm_sublist(c, c, next, prev)
110 120
 
111 121
 
112 122
 
113
-/* iterate on a clist */
123
+/*! \brief  iterate on a clist */
114 124
 #define clist_foreach(head, v, dir) \
115 125
 	for((v)=(head)->dir; (v)!=(void*)(head); (v)=(v)->dir)
116 126
 
117
-/* iterate on a clist, safe version (requires an extra bak. var)
127
+/*! \brief  iterate on a clist, safe version (requires an extra bak. var)
118 128
  * (it allows removing of the current element) */
119 129
 #define clist_foreach_safe(head, v, bak,  dir) \
120 130
 	for((v)=(head)->dir, (bak)=(v)->dir; (v)!=(void*)(head); \
... ...
@@ -15,26 +15,35 @@
15 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18
-/*
19
- * compiler specific optimizations:
20
- * --------------------------------
18
+/*!
19
+ * \file
20
+ * \brief SIP-router core :: Compiler specific optimizations
21
+ * \see \ref CompilerOptions
22
+ *
23
+ * \ingroup core
24
+ * Module: \ref core
21 25
  *
22
- *   likely(expr)         - branch predicition optimization - is more likely
26
+ * \page CompilerOptions compiler specific optimizations:
27
+ *
28
+\verbatim
29
+ *   - likely(expr)         - branch predicition optimization - is more likely
23 30
  *                          that expr value will be 1 so optimize for this 
24 31
  *                          case.
25 32
  *                          Example: if (likely(p!=NULL)) {... }
26
- *   unlikely(expr)       - branch prediction optimization - is unlikely that 
33
+ *   - unlikely(expr)       - branch prediction optimization - is unlikely that 
27 34
  *                          expr will be true, so optimize for this case
28
- *   prefetch(addr)        - will prefetch addr. for reading
29
- *   prefetch_w(addr)      - will prefetch addr. for writing
30
- *   prefetch_loc_r(addr, loc) - prefetch for reading, data at addr has
35
+ *   - prefetch(addr)        - will prefetch addr. for reading
36
+ *   - prefetch_w(addr)      - will prefetch addr. for writing
37
+ *   - prefetch_loc_r(addr, loc) - prefetch for reading, data at addr has
31 38
  *                                no temporal locality (loc==0), a short
32 39
  *                                degree of temporal locality (loc==1), 
33 40
  *                                moderate (loc==2) or high (loc==3).
34 41
  *                                prefetch(addr) is equiv. to 
35 42
  *                                prefetch_loc_r(addr, 3).
36 43
  *  prefetch_loc_w(addr, loc) - like above but for writing.
44
+\endverbatim
37 45
  */
46
+
38 47
 /* 
39 48
  * History:
40 49
  * --------
... ...
@@ -3,19 +3,14 @@
3 3
  *
4 4
  * Copyright (C) 2001-2003 FhG Fokus
5 5
  *
6
- * This file is part of ser, a free SIP server.
6
+ * This file is part of SIP-router, a free SIP server.
7 7
  *
8
- * ser is free software; you can redistribute it and/or modify
8
+ * SIP-router is free software; you can redistribute it and/or modify
9 9
  * it under the terms of the GNU General Public License as published by
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18
- * ser is distributed in the hope that it will be useful,
13
+ * SIP-router is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 16
  * GNU General Public License for more details.
... ...
@@ -32,6 +27,15 @@
32 27
  *
33 28
  */
34 29
 
30
+/*!
31
+ * \file
32
+ * \brief SIP-router core :: Configuration options
33
+ *
34
+ * These settings are settable by the user before compilation
35
+ *
36
+ * \ingroup core
37
+ * Module: \ref core
38
+ */
35 39
 
36 40
 
37 41
 
... ...
@@ -40,38 +44,34 @@
40 44
 
41 45
 #include "types.h"
42 46
 
43
-/* default sip port if none specified */
44
-#define SIP_PORT  5060
45
-#define SIPS_PORT 5061
47
+#define SIP_PORT  5060 /*!< default SIP port if none specified */
48
+#define SIPS_PORT 5061 /*!< default SIP port for TLS if none specified */
46 49
 
47 50
 #define CFG_FILE CFG_DIR NAME ".cfg"
48 51
 
49
-#define TLS_PKEY_FILE "cert.pem" 
50
-#define TLS_CERT_FILE "cert.pem"
51
-#define TLS_CA_FILE 0 /* no CA list file by default */
52
+#define TLS_PKEY_FILE "cert.pem" 	/*!< The certificate private key file */
53
+#define TLS_CERT_FILE "cert.pem"	/*!< The certificate file */
54
+#define TLS_CA_FILE 0			/*!< no CA list file by default */
52 55
 
53 56
 
54
-/* maximum number of addresses on which we will listen */
55
-#define MAX_LISTEN 16
57
+#define MAX_LISTEN 16			/*!< maximum number of addresses on which we will listen */
56 58
 
57
-/* default number of child processes started */
58
-#define CHILD_NO    8
59
+#define CHILD_NO    8			/*!< default number of child processes started */
59 60
 
60
-#define RT_NO 2 /* routing tables number */
61
-#define FAILURE_RT_NO RT_NO /* on_failure routing tables number */
62
-#define ONREPLY_RT_NO RT_NO /* on_reply routing tables number */
63
-#define BRANCH_RT_NO RT_NO /* branch_route routing tables number */
64
-#define ONSEND_RT_NO 1  /* onsend_route routing tables number */
65
-#define EVENT_RT_NO RT_NO /* event_route routing tables number */
66
-#define DEFAULT_RT 0 /* default routing table */
61
+#define RT_NO 2 			/*!< routing tables number */
62
+#define FAILURE_RT_NO RT_NO 		/*!< on_failure routing tables number */
63
+#define ONREPLY_RT_NO RT_NO 		/*!< on_reply routing tables number */
64
+#define BRANCH_RT_NO RT_NO 		/*!< branch_route routing tables number */
65
+#define ONSEND_RT_NO 1  		/*!< onsend_route routing tables number */
66
+#define EVENT_RT_NO RT_NO 		/*!< event_route routing tables number */
67
+#define DEFAULT_RT 0 			/*!< default routing table */
67 68
 
68
-#define MAX_REC_LEV 100 /* maximum number of recursive calls */
69
-#define ROUTE_MAX_REC_LEV 100 /* maximum number of recursive calls
70
-							   for route()*/
69
+#define MAX_REC_LEV 100 		/*!< maximum number of recursive calls */
70
+#define ROUTE_MAX_REC_LEV 100 		/*!< maximum number of recursive calls for route()*/
71 71
 
72
-#define MAX_URI_SIZE 1024	/* used when rewriting URIs */
72
+#define MAX_URI_SIZE 1024		/*!< Max URI size used when rewriting URIs */
73 73
 
74
-#define MAX_PATH_SIZE 256 /* Maximum length of path header buffer */
74
+#define MAX_PATH_SIZE 256 		/*!< Maximum length of path header buffer */
75 75
 
76 76
 #define MY_VIA "Via: SIP/2.0/UDP "
77 77
 #define MY_VIA_LEN (sizeof(MY_VIA) - 1)
... ...
@@ -140,62 +140,52 @@
140 140
 
141 141
 #define SRV_MAX_PREFIX_LEN SRV_TLS_PREFIX_LEN
142 142
 
143
-/*used only if PKG_MALLOC is defined*/
144
-#define PKG_MEM_POOL_SIZE 4*1024*1024
143
+#define PKG_MEM_POOL_SIZE 4*1024*1024		/*!< used only if PKG_MALLOC is defined*/
145 144
 
146
-/*used if SH_MEM is defined*/
147
-#define SHM_MEM_SIZE 32
145
+#define SHM_MEM_SIZE 32				/*!< used if SH_MEM is defined*/
148 146
 
149 147
 
150 148
 /* dimensioning buckets in q_malloc */
151
-/* size of the size2bucket table; everything beyond that asks for
149
+/*! \brief size of the size2bucket table; everything beyond that asks for
152 150
    a variable-size kilo-bucket
153 151
  */
154 152
 #define MAX_FIXED_BLOCK         3072
155
-/* distance of kilo-buckets */
156
-#define BLOCK_STEP                      512
157
-/* maximum number of possible buckets */
158
-#define MAX_BUCKET		15
153
+#define BLOCK_STEP              512		/*!< distance of kilo-buckets */
154
+#define MAX_BUCKET		15		/*!< maximum number of possible buckets */
159 155
 
160
-/* receive buffer size -- preferably set low to
156
+/*! \brief receive buffer size -- preferably set low to
161 157
    avoid terror of excessively huge messages; they are
162 158
    useless anyway
163 159
 */
164 160
 #define BUF_SIZE 65535
165 161
 
166
-/* forwarding  -- Via buffer dimensioning */
167
-#define MAX_VIA_LINE_SIZE	240
168
-#define MAX_RECEIVED_SIZE	57
169
-#define MAX_RPORT_SIZE		13
162
+#define MAX_VIA_LINE_SIZE	240	/*!< forwarding  -- Via buffer dimensioning */
163
+#define MAX_RECEIVED_SIZE	57	/*!< forwarding  -- Via buffer dimensioning - Received header */
164
+#define MAX_RPORT_SIZE		13	/*!< forwarding  -- Via buffer dimensioning - Rport */
170 165
 
171
-/* maximum number of branches per transaction */
172
-#define MAX_BRANCHES    12
166
+#define MAX_BRANCHES    	12	/*!< maximum number of branches per transaction */
173 167
 
174
-/* max length of the text of fifo 'print' command */
175
-#define MAX_PRINT_TEXT 256
168
+#define MAX_PRINT_TEXT 		256	/*!< max length of the text of fifo 'print' command */
176 169
 
177
-/* maximum length of Contact header field in redirection replies */
178
-#define MAX_REDIRECTION_LEN 512
170
+#define MAX_REDIRECTION_LEN	512	/*!< maximum length of Contact header field in redirection replies */
179 171
 
180
-/* used by FIFO statistics in module to terminate line;
172
+/*! \brief used by FIFO statistics in module to terminate line;
181 173
    extra whitespaces are used to overwrite remainders of
182 174
    previous line if longer than current one
183 175
 */
184 176
 #define CLEANUP_EOL "      \n"
185 177
 
186
-/* magic cookie for transaction matching as defined in RFC3261 */
187
-#define MCOOKIE "z9hG4bK"
178
+#define MCOOKIE "z9hG4bK"		/*!< magic cookie for transaction matching as defined in RFC3261 */
188 179
 #define MCOOKIE_LEN (sizeof(MCOOKIE)-1)
189
-/* Maximum length of values appended to Via-branch parameter */
180
+/*! \brief Maximum length of values appended to Via-branch parameter */
190 181
 #define MAX_BRANCH_PARAM_LEN  (MCOOKIE_LEN+8 /*int2hex*/ + 1 /*sep*/ + \
191 182
 								MD5_LEN /* max(int2hex, MD5_LEN) */ \
192 183
 								+ 1 /*sep*/ + 8 /*int2hex*/ + \
193 184
 								1 /*extra space, needed by t_calc_branch*/)
194 185
 
195
-#define DEFAULT_SER_KILL_TIMEOUT 60 /* seconds */
186
+#define DEFAULT_SER_KILL_TIMEOUT 60 	/*!< Kill timeout : seconds */
196 187
 
197
-/* maximum path length */
198
-#define PATH_MAX_GUESS	1024
188
+#define PATH_MAX_GUESS	1024		/*!< maximum path length */
199 189
 
200 190
 #ifdef OPENSER_MOD_INTERFACE
201 191
 	#define DEFAULT_DB_URL "mysql://openser:openserrw@localhost/openser"
... ...
@@ -209,21 +199,18 @@
209 199
 	#define DEFAULT_RODB_URL_LEN (sizeof(DEFAULT_RODB_URL) - 1)
210 200
 #endif
211 201
 
212
-/* table holding versions of other ser tables */
213
-#define VERSION_TABLE "version"
214
-#define VERSION_COLUMN "table_version"
215
-#define TABLENAME_COLUMN "table_name"
202
+#define VERSION_TABLE "version"			/*!< table holding versions of other ser tables */
203
+#define VERSION_COLUMN "table_version"		/*!< Column holding version number in version table */
204
+#define TABLENAME_COLUMN "table_name"		/*!< Column holding module name in version table */
216 205
 
217
-/* minimum packet size; smaller packets will be dropped silently */
218
-#define MIN_UDP_PACKET        32
206
+#define MIN_UDP_PACKET        32		/*!< minimum UDP packet size; smaller packets will be dropped silently */
219 207
 
220
-#define MIN_SCTP_PACKET  MIN_UDP_PACKET 
208
+#define MIN_SCTP_PACKET  MIN_UDP_PACKET 	/*!< minimum size of SCTP packet */
221 209
 
222
-#define DEFAULT_RADIUS_CONFIG "/usr/local/etc/radiusclient/radiusclient.conf"
210
+#define DEFAULT_RADIUS_CONFIG "/usr/local/etc/radiusclient/radiusclient.conf"	/*!< Default FreeRadius configuration file */
223 211
 
224 212
 #define DEFAULT_DID "_default"
225 213
 
226
-/*  maximum allowed iterations for a while (to catch runaways) */
227
-#define DEFAULT_MAX_WHILE_LOOPS 100
214
+#define DEFAULT_MAX_WHILE_LOOPS 100		/*!< Maximum allowed iterations for a while (to catch runaways) */
228 215
 
229 216
 #endif
... ...
@@ -3,19 +3,14 @@
3 3
  *
4 4
  * Copyright (C) 2005 iptelorg GmbH
5 5
  *
6
- * This file is part of ser, a free SIP server.
6
+ * This file is part of SIP-router, a free SIP server.
7 7
  *
8
- * ser is free software; you can redistribute it and/or modify
8
+ * SIP-router is free software; you can redistribute it and/or modify
9 9
  * it under the terms of the GNU General Public License as published by
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18
- * ser is distributed in the hope that it will be useful,
13
+ * SIP-router is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 16
  * GNU General Public License for more details.
... ...
@@ -24,6 +19,7 @@
24 19
  * along with this program; if not, write to the Free Software
25 20
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 21
  */
22
+
27 23
 /*!
28 24
  * \file
29 25
  * \brief SIP-router core :: 
... ...
@@ -25,6 +25,13 @@
25