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 38
 #ifndef __atomic_ops_init_h
39 39
 #define __atomic_ops_init_h
40 40
 
41
-/* init atomic ops */
41
+/*! \brief init atomic ops */
42 42
 int init_atomic_ops();
43
-/* destroy atomic ops (e.g. frees the locks, if locks are used) */
43
+/*! \brief destroy atomic ops (e.g. frees the locks, if locks are used) */
44 44
 void destroy_atomic_ops();
45 45
 
46 46
 #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 65
  *  for some interesting tests and ideeas).
66 66
  *
67 67
  *  Test results for 40 bytes  (typical ser nounce) in average cpu cycles:
68
+<verbatim>
68 69
  *                    lookup   lookup_large lookup8k no-lookup
69 70
  *  base16_enc           211/231  218/199      -       1331
70 71
  *  base16_dec           252/251  236          -       1226
... ...
@@ -73,22 +70,23 @@
73 73
  *  q_base64_enc         -                              288
74 74
  *  q_base64_dec         -                              281
75 75
  *  (see test/basex.txt for more results)
76
+</verbatim>
76 77
  *
77 78
  * Defines:
78
- *  BASE64_LOOKUP_TABLE/NO_BASE64_LOOKUP_TABLE - use (default)/don't use
79
+ *  - BASE64_LOOKUP_TABLE/NO_BASE64_LOOKUP_TABLE : use (default)/don't use
79 80
  *     small lookup tables for conversions (faster in general).
80
- *  BASE64_LOOKUP_LARGE    - use large lookup tables (2560 bytes for 
81
+ *  - BASE64_LOOKUP_LARGE    : use large lookup tables (2560 bytes for 
81 82
  *    encoding and 256 bytes for decoding; without it 64 bytes are used for
82 83
  *    encoding and 85 bytes for decoding.
83
- *  BASE64_LOOKUP_8K - use even larger lookup tables (8K for encoding and
84
+ *  - BASE64_LOOKUP_8K : use even larger lookup tables (8K for encoding and
84 85
  *    256 for decoding); also try to write 2 bytes at a time (short) if
85 86
  *    the destination is 2 byte aligned
86 87
  *
87
- *  BASE16_LOOKUP_TABLE/NO_BASE16_LOOKUP_TABLE - use (default)/don't use
88
+ *  - BASE16_LOOKUP_TABLE/NO_BASE16_LOOKUP_TABLE : use (default)/don't use
88 89
  *     small lookup tables for conversions (faster in general).
89
- *  BASE16_LOOKUP_LARGE  - use large lookup tables (512 bytes for 
90
+ *  - BASE16_LOOKUP_LARGE  : use large lookup tables (512 bytes for 
90 91
  *    encoding and 256 bytes for decoding
91
- *  BASE16_READ_WHOLE_INTS - read an int at a time
92
+ *  - BASE16_READ_WHOLE_INTS : read an int at a time
92 93
  *
93 94
  * History:
94 95
  * --------
... ...
@@ -129,7 +127,7 @@
129 129
 	defined BASE64_LOOKUP_8K
130 130
 #include "endianness.h"
131 131
 
132
-/* aligns p to a type* pointer, type must have a 2^k size */
132
+/*! \brief aligns p to a type* pointer, type must have a 2^k size */
133 133
 #define ALIGN_POINTER(p, type) \
134 134
 	((type*) ((long)((char*)(p)+sizeof(type)-1)&~(long)(sizeof(type)-1)))
135 135
 
... ...
@@ -141,7 +139,7 @@
141 141
 #ifdef BASE16_LOOKUP_TABLE
142 142
 
143 143
 #ifdef BASE16_LOOKUP_LARGE
144
-/* use large tables: 512 for lookup and 256 for decode */
144
+/*! \brief use large tables: 512 for lookup and 256 for decode */
145 145
 
146 146
 extern unsigned char _bx_hexdig_hi[256];
147 147
 extern unsigned char _bx_hexdig_low[256];
... ...
@@ -154,7 +152,7 @@ extern unsigned char _bx_unhexdig256[256];
154 154
 #define UNHEX(h)	_bx_unhexdig256[(h)]
155 155
 
156 156
 #else /* BASE16_LOOKUP_LARGE */
157
-/* use small tabes: 16 bytes for lookup and 32 for decode */
157
+/*! \brief use small tabes: 16 bytes for lookup and 32 for decode */
158 158
 
159 159
 extern unsigned char _bx_hexdig[16+1];
160 160
 
... ...
@@ -254,39 +252,40 @@ extern unsigned char _bx_ub64[0x54+1];
254 254
 
255 255
 
256 256
 
257
-/* lenght needed for encoding l bytes */
257
+/*! \brief lenght needed for encoding l bytes */
258 258
 #define base16_enc_len(l) (l*2)
259
-/* maximum lenght needed for decoding l bytes */
259
+/*! \brief maximum lenght needed for decoding l bytes */
260 260
 #define base16_max_dec_len(l) (l/2)
261
-/* actual space needed for decoding a string b of size l */
261
+/*! \brief actual space needed for decoding a string b of size l */
262 262
 #define base16_dec_len(b, l) base16_max_dec_len(l)
263
-/* minimum valid source len for decoding */
263
+/*! \brief minimum valid source len for decoding */
264 264
 #define base16_dec_min_len() 2
265
-/* minimum valid source len for encoding */
265
+/*! \brief minimum valid source len for encoding */
266 266
 #define base16_enc_min_len() 0
267 267
 
268
-/* space needed for encoding l bytes */
268
+/*! \brief space needed for encoding l bytes */
269 269
 #define base64_enc_len(l) (((l)+2)/3*4)
270
-/* maximum space needed for encoding l bytes */
270
+/*! \brief maximum space needed for encoding l bytes */
271 271
 #define base64_max_dec_len(l) ((l)/4*3)
272
-/* actual space needed for decoding a string b of size l, l>=4 */
272
+/*! \brief actual space needed for decoding a string b of size l, l>=4 */
273 273
 #define base64_dec_len(b, l) \
274 274
 	(base64_max_dec_len(l)-((b)[(l)-2]=='=') -((b)[(l)-1]=='='))
275
-/* minimum valid source len for decoding */
275
+/*! \brief minimum valid source len for decoding */
276 276
 #define base64_dec_min_len() 4
277
-/* minimum valid source len for encoding */
277
+/*! \brief minimum valid source len for encoding */
278 278
 #define base64_enc_min_len() 0
279 279
 
280 280
 
281 281
 #ifdef BASE16_READ_WHOLE_INTS
282 282
 
283
-/* params: 
284
- * returns: size used from the output buffer (dst) on success,
283
+/*! 
284
+ * \params: 
285
+ * \return: size used from the output buffer (dst) on success,
285 286
  *          -size_needed on error
287
+ *
286 288
  * WARNING: the output string is not 0-term
287 289
  */
288
-inline static int base16_enc(unsigned char* src, int slen,
289
-							 unsigned char*  dst, int dlen)
290
+inline static int base16_enc(unsigned char* src, int slen, unsigned char*  dst, int dlen)
290 291
 {
291 292
 	unsigned int* p;
292 293
 	unsigned char* end;
... ...
@@ -454,10 +453,11 @@ inline static int base16_enc(unsigned char* src, int slen,
454 454
 #else /* BASE16_READ_WHOLE_INTS */
455 455
 
456 456
 
457
-/* params: 
458
- * returns: size used from the output buffer (dst) on success,
457
+/*!
458
+ * \return : size used from the output buffer (dst) on success,
459 459
  *          -size_needed on error
460
- * WARNING: the output string is not 0-term
460
+ *
461
+ * \note WARNING: the output string is not 0-term
461 462
  */
462 463
 inline static int base16_enc(unsigned char* src, int slen,
463 464
 							 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 498
 
499 499
 
500 500
 
501
-/* helper internal function: encodes v (6 bits value)
502
- * returns char ascii encoding on success and 0xff on error
501
+/*! \brief helper internal function: encodes v (6 bits value)
502
+ * \return char ascii encoding on success and 0xff on error
503 503
  * (value out of range) */
504 504
 inline static unsigned char base64_enc_char(unsigned char v)
505 505
 {
... ...
@@ -519,8 +518,8 @@ inline static unsigned char base64_enc_char(unsigned char v)
519 519
 	return 0xff;
520 520
 }
521 521
 
522
-/* helper internal function: decodes a base64 "digit",
523
- * returns value on success (0-63) and 0xff on error (invalid)*/
522
+/*! \brief helper internal function: decodes a base64 "digit",
523
+ * \return value on success (0-63) and 0xff on error (invalid)*/
524 524
 inline static unsigned base64_dec_char(unsigned char v)
525 525
 {
526 526
 	switch(v){
... ...
@@ -557,10 +556,11 @@ inline static unsigned base64_dec_char(unsigned char v)
557 557
 
558 558
 
559 559
 #ifdef BASE64_LOOKUP_8K
560
-/* params: 
561
- * returns: size used from the output buffer (dst) on success ((slen+2)/3*4)
560
+/*!
561
+ * \return : size used from the output buffer (dst) on success ((slen+2)/3*4)
562 562
  *          -size_needed on error
563
- * WARNING: the output string is not 0-term
563
+ *
564
+ * \note WARNING: the output string is not 0-term
564 565
  */
565 566
 inline static int base64_enc(unsigned char* src, int slen,
566 567
 							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 769
 
770 770
 
771 771
 
772
-/*
773
- * same as base64_enc but with a different alphabet, that allows simpler and
772
+/*! \brief
773
+ * same as \ref base64_enc() but with a different alphabet, that allows simpler and
774 774
  *  faster enc/dec
775
- * params: 
776
- * params: 
777
- * returns: size used from the output buffer (dst) on success (max: slen/4*3)
775
+ *
776
+ * \return size used from the output buffer (dst) on success (max: slen/4*3)
778 777
  *          -size_needed on error or 0 on bad base64 encoded string
779
- * WARNING: the output string is not 0-term
778
+ * \note WARNING: the output string is not 0-term
780 779
  */
781 780
 inline static int q_base64_dec(unsigned char* src, int slen,
782 781
 							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 46
 
47 47
 #include <limits.h>
48 48
 
49
-/* fix __CPU_i386 -> __CPU_x86 */
49
+/*! \brief fix __CPU_i386 -> __CPU_x86 */
50 50
 #if defined __CPU_i386 && ! defined __CPU_x86
51 51
 #define __CPU_x86
52 52
 #endif
... ...
@@ -59,7 +65,7 @@
59 59
 #endif
60 60
 
61 61
 
62
-/* set default bitscan versions, depending on the architecture
62
+/*! \brief set default bitscan versions, depending on the architecture
63 63
  * In general the order is  asm, debruijn, br, slow for bit_scan_forward
64 64
  *  and asm, br, slow, debruijn for bit_scan_reverse. */
65 65
 #ifdef BIT_SCAN_ASM
... ...
@@ -127,15 +133,15 @@
127 127
 #endif /* __CPU_XXX */
128 128
 
129 129
 
130
-/* try to use the right version for bit_scan_forward(unisgned long l)
130
+/*! \brief try to use the right version for bit_scan_forward(unisgned long l)
131 131
  */
132 132
 #if (defined (ULONG_MAX) && ULONG_MAX > 4294967295) || defined LP64
133
-/* long is 64 bits */
133
+/*! \brief long is 64 bits */
134 134
 #define bit_scan_forward(l)	bit_scan_forward64((unsigned long long)(l))
135 135
 #define bit_scan_reverse(l)	bit_scan_reverse64((unsigned long long)(l))
136 136
 
137 137
 #else
138
-/* long is 32 bits */
138
+/*! \brief long is 32 bits */
139 139
 #define bit_scan_forward(l)	bit_scan_forward32((l))
140 140
 #define bit_scan_reverse(l)	bit_scan_reverse32((l))
141 141
 #endif
... ...
@@ -145,7 +151,7 @@
145 145
 
146 146
 #ifdef BIT_SCAN_DEBRUIJN
147 147
 
148
-/* use a de Bruijn sequence to get the index of the set bit for a number
148
+/*! \brief use a de Bruijn sequence to get the index of the set bit for a number
149 149
  *  of the form 2^k (DEBRUIJN_HASH32() and DEBRUIJN_HASH64()).
150 150
  *  bit_scan_forward & bit_scan_reverse would need first to convert
151 151
  *  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 31
  */
32 32
 /*!
33 33
  * \file
34
- * \brief SIP-router core :: 
34
+ * \brief SIP-router core ::  Core configuration
35 35
  * \ingroup core
36 36
  * Module: \ref core
37 37
  */
... ...
@@ -53,56 +48,56 @@
53 53
 #include "cfg_core.h"
54 54
 
55 55
 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 */
56
+	L_WARN, 	/*!<  print only msg. < L_WARN */
57
+	LOG_DAEMON,	/*!< log_facility -- see syslog(3) */
58
+	L_DBG,  /*!< memdbg */
59 59
 #ifdef USE_DST_BLACKLIST
60 60
 	/* blacklist */
61
-	0, /* dst blacklist is disabled by default */
61
+	0, /*!< dst blacklist is disabled by default */
62 62
 	DEFAULT_BLST_TIMEOUT,
63 63
 	DEFAULT_BLST_MAX_MEM,
64 64
 #endif
65 65
 	/* resolver */
66 66
 #ifdef USE_IPV6
67
-	1,  /* dns_try_ipv6 -- on by default */
67
+	1,  /*!< dns_try_ipv6 -- on by default */
68 68
 #else
69
-	0,  /* dns_try_ipv6 -- off, if no ipv6 support */
69
+	0,  /*!< dns_try_ipv6 -- off, if no ipv6 support */
70 70
 #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 */
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 */
82 82
 	/* DNS cache */
83 83
 #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 */
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 */
93 93
 #endif
94 94
 #ifdef PKG_MALLOC
95
-	0, /* mem_dump_pkg */
95
+	0, /*!< mem_dump_pkg */
96 96
 #endif
97 97
 #ifdef SHM_MEM
98
-	0, /* mem_dump_shm */
98
+	0, /*!< mem_dump_shm */
99 99
 #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 */
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 */
106 106
 };
107 107
 
108 108
 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 44
 
45 45
 extern void	*core_cfg;
46 46
 
47
+/*! \brief configuration default values */
47 48
 struct cfg_group_core {
48 49
 	int	debug;
49 50
 	int	log_facility;
50
-	int memdbg; /** < log level for memory debugging messages */
51
+	int memdbg; /*!< log level for memory debugging messages */
51 52
 #ifdef USE_DST_BLACKLIST
52 53
 	/* 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
54
+	int	use_dst_blacklist; /*!< 1 if blacklist is enabled */
55
+	unsigned int	blst_timeout; /*!< blacklist entry ttl */
56
+	unsigned int	blst_max_mem; /*!< maximum memory used for the
56 57
 					blacklist entries */
57 58
 #endif
58 59
 	/* resolver */
... ...
@@ -87,11 +96,11 @@ struct cfg_group_core {
87 87
 	int mem_dump_shm;
88 88
 #endif
89 89
 	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 */
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 */
95 95
 };
96 96
 
97 97
 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 56
  *	}
57 57
  *
58 58
  *	cfg_parser_close(parser);
59
+\endverbatim
59 60
  */
60 61
 
61
-/** Example 2: Options with integer values
62
+/*! \page ConfigExample2  Configuration engine Example 2: Options with integer values
63
+\verbatim
62 64
  * 	cfg_option_t options[] = {
63 65
  *		{"max_number",   .param = &max_number,   .f = cfg_parse_int_val },
64 66
  *		{"extra_checks", .param = &extra_checks, .f = cfg_parse_bool_val},
65 67
  *		{0}
66 68
  *	};
69
+\endverbatim
67 70
  */
68 71
 
69
-/** Example 3: Enum options
72
+/*! \page ConfigExample3 Configuration engine Example 3: Enum options
73
+\verbatim
70 74
  * int scope;
71 75
  *
72 76
  *	cfg_option_t scopes[] = {
... ...
@@ -83,10 +116,12 @@
83 83
  *		{"scope", .param = scopes, .f = cfg_parse_enum_val},
84 84
  *		{0}
85 85
  *	};
86
+\endverbatim
86 87
  */
87 88
 
88
-/** Example 4: Options with string values
89
- * 	str filename = STR_NULL;
89
+/*! \page ConfigExample4 Configuration engine Example 4: Options with string values
90
+\verbatim
91
+* 	str filename = STR_NULL;
90 92
  *
91 93
  *	cfg_option_t options[] = {
92 94
  *		{"filename", .param = &filename, .f = cfg_parse_str_val},
... ...
@@ -97,37 +132,27 @@
97 97
  *   by a subsequent call
98 98
  * - There are flags to tell the function to copy the resuting string in a pkg, shm, glibc,
99 99
  *   or static buffers
100
+\endverbatim
100 101
  */
101 102
 
102
-/** Example 5: Custom value parsing
103
+/*! \page ConfigExample5 Configuration engine Example 5: Custom value parsing
103 104
  * TBD
104 105
  */
105 106
 
106
-/** Example 6: Parsing Sections
107
+/*! \page ConfigExample6 Configuration engine Example 6: Parsing Sections
107 108
  * TBD
108 109
  */
109 110
 
110
-/** Example 7: Default Options
111
+/*! \page ConfigExample7 Configuration engine Example 7: Default Options
111 112
  * TBD
112 113
  */
113 114
 
114
-/** Example 8: Memory management of strings
115
- * - Data types with fixed size are easy, they can be copied into a pre-allocated memory
115
+/*! \page ConfigExample8 Configuration engine Example 8: Memory management of strings
116
+ *
117
+ * Data types with fixed size are easy, they can be copied into a pre-allocated memory
116 118
  * buffer, strings cannot because their length is unknown.
117 119
  */
118 120
 
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 121
 #include "cfg_parser.h"
132 122
 
133 123
 #include "mem/mem.h"
... ...
@@ -142,20 +167,20 @@
142 142
 #include <libgen.h>
143 143
 
144 144
 
145
-/* The states of the lexical scanner */
145
+/*! \brief The states of the lexical scanner */
146 146
 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 */
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 */
155 155
 };
156 156
 
157 157
 
158
-/* Test for alphanumeric characters */
158
+/*! \brief Test for alphanumeric characters */
159 159
 #define IS_ALPHA(c) \
160 160
     (((c) >= 'a' && (c) <= 'z') || \
161 161
      ((c) >= 'A' && (c) <= 'Z') || \
... ...
@@ -163,7 +188,7 @@ enum st {
163 163
      (c) == '_')
164 164
 
165 165
 
166
-/* Test for delimiter characters */
166
+/*! \brief Test for delimiter characters */
167 167
 #define IS_DELIM(c) \
168 168
     ((c) == '=' || \
169 169
      (c) == ':' || \
... ...
@@ -188,7 +213,7 @@ enum st {
188 188
      (c) == '\'')
189 189
 
190 190
 
191
-/* Whitespace characters */
191
+/*! \brief Whitespace characters */
192 192
 #define IS_WHITESPACE(c) ((c) == ' ' || (c) == '\t' || (c) == '\r') 
193 193
 #define IS_QUOTE(c)      ((c) == '\"')  /* Quote characters */
194 194
 #define IS_COMMENT(c)    ((c) == '#')   /* Characters that start comments */
... ...
@@ -196,9 +221,8 @@ enum st {
196 196
 #define IS_EOL(c)        ((c) == '\n')  /* End of line */
197 197
 
198 198
 
199
-/*
200
- * Append character to the value of current
201
- * token
199
+/*! \brief
200
+ * Append character to the value of current token
202 201
  */
203 202
 #define PUSH(c)                            \
204 203
     if (token->val.len >= MAX_TOKEN_LEN) { \
... ...
@@ -213,7 +237,7 @@ enum st {
213 213
     token->val.s[token->val.len++] = (c);
214 214
 
215 215
 
216
-/*
216
+/*! \brief
217 217
  * Return current token from the lexical analyzer
218 218
  */
219 219
 #define RETURN(c)               \
... ...
@@ -224,7 +248,7 @@ enum st {
224 224
     return 0;
225 225
 
226 226
 
227
-/*
227
+/*! \brief
228 228
  * Get next character and update counters
229 229
  */
230 230
 #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 28
 #include "str.h"
29 29
 #include <stdio.h>
30 30
 
31
-#define MAX_TOKEN_LEN 512 /**< Token names cannot be longer than this value */
31
+#define MAX_TOKEN_LEN 512 /*!< Token names cannot be longer than this value */
32 32
 
33 33
 
34
+/*! \brief Configuration flags */
34 35
 typedef enum cfg_flags {
35
-	/** Extended tokens can contain also delimiters, in addition to
36
+	/*! \brief Extended tokens can contain also delimiters, in addition to
36 37
 	 * alpha-numeric characters, this is used on the righ side of assignments
37 38
 	 * where no quotes are used.
38 39
 	 */
39 40
 	CFG_EXTENDED_ALPHA = (1 << 0),
40 41
 
41
-	/** The parser performs case-insensitive comparisons of token strings by
42
+	/*! \brief The parser performs case-insensitive comparisons of token strings by
42 43
 	 * default. The parser will use case-sensitive comparison instead if this
43 44
 	 * flag is set.
44 45
 	 */
45 46
 	CFG_CASE_SENSITIVE = (1 << 1), 
46 47
 
47
-	/** This is a flag that can be set in the last element of cfg_option
48
+	/*! \brief This is a flag that can be set in the last element of cfg_option
48 49
 	 * arrays (this is the one with 0 as token name). When this flag is set
49 50
 	 * then the value or parsing function of the element will be used for
50 51
 	 * options that do not match any other element in the array.
... ...
@@ -52,30 +62,30 @@ typedef enum cfg_flags {
52 52
 	CFG_DEFAULT = (1 << 2),
53 53
 
54 54
 
55
-	/** When this flag is set then the name of the options is a prefix and all
55
+	/*! \brief When this flag is set then the name of the options is a prefix and all
56 56
 	 * options that have the same prefix will be matched by this entry.
57 57
 	 */
58 58
 	CFG_PREFIX = (1 << 3),
59 59
 
60
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
60
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
61 61
 	 * pkg_malloc, if the destination varaiable contains a pointer to a buffer
62 62
 	 * already then it will be freed with pkg_free first.
63 63
 	 */
64 64
 	CFG_STR_PKGMEM = (1 << 4),
65 65
 
66
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
66
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
67 67
 	 * shm_malloc, if the destination variable contains a pointer to a buffer
68 68
 	 * already then it will be freed with shm_free first.
69 69
 	 */
70 70
 	CFG_STR_SHMMEM = (1 << 5),
71 71
 
72
-	/** The result of cfg_parse_str_val will be in a buffer allocated by
72
+	/*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
73 73
 	 * malloc, if the destination variable contains a pointer to a buffer
74 74
 	 * already then it will be freed with free first.
75 75
 	 */
76 76
 	CFG_STR_MALLOC = (1 << 6),
77 77
 
78
-	/** The result of cfg_parse_str_val will be copied into a pre-allocated
78
+	/*! \brief The result of cfg_parse_str_val will be copied into a pre-allocated
79 79
 	 * buffer with a fixed size, a pointer to str variable which contains the
80 80
 	 * buffer and its size is passed to the function in parameter 'param'.
81 81
 	 */
... ...
@@ -91,14 +101,14 @@ enum cfg_token_type {
91 91
 };
92 92
 
93 93
 
94
-/** Structure representing a lexical token */
94
+/*! \brief Structure representing a lexical token */
95 95
 typedef struct cfg_token {
96 96
 	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 */
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 */
102 102
 	} start, end;
103 103
 } cfg_token_t;
104 104
 
... ...
@@ -109,31 +119,32 @@ typedef int (*cfg_func_f)(void* param, struct cfg_parser* st,
109 109
 						  unsigned int flags);
110 110
 
111 111
 
112
-/** Token mapping structure.
112
+/*! \brief Token mapping structure.
113
+ *
113 114
  * This structure is used to map tokens to values or function calls. Arrays of
114 115
  * such structures are typically provided by the caller of the parser.
115 116
  */
116 117
 typedef struct cfg_option {
117
-	char* name;    /**< Token name */
118
+	char* name;    /*!< Token name */
118 119
 	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 */
120
+	void* param;   /*!< Pointer to the destination variable */
121
+	int val;       /*!< Value */
122
+	cfg_func_f f;  /*!< Parser function to be called */
122 123
 } cfg_option_t;
123 124
 
124 125
 
125
-/* Parser state */
126
+/*! \brief Parser state */
126 127
 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 */
128
+	FILE* f;                 /*!< Handle of the currently open file */
129
+	char* file;              /*!< Current file name */
130
+	int line;                /*!< Current line */
131
+	int col;                 /*!< Column index */
132
+	struct cfg_option* options; /*!< Array of supported options */
132 133
 	struct {
133
-		cfg_func_f parser;   /**< Section parser function */
134
-		void* param;         /**< Parameter value for the parser function */
134
+		cfg_func_f parser;   /*!< Section parser function */
135
+		void* param;         /*!< Parameter value for the parser function */
135 136
 	} section;
136
-	struct cfg_token* cur_opt; /**< Current option */
137
+	struct cfg_token* cur_opt; /*!< Current option */
137 138
 } cfg_parser_t;
138 139
 
139 140
 
... ...
@@ -151,7 +162,7 @@ void cfg_parser_close(struct cfg_parser* st);
151 151
 
152 152
 struct cfg_option* cfg_lookup_token(struct cfg_option* options, str* token);
153 153
 
154
-/** Interface to the lexical scanner */
154
+/*! ! \briefInterface to the lexical scanner */
155 155
 int cfg_get_token(struct cfg_token* token, struct cfg_parser* st, unsigned int flags);
156 156
 
157 157
 /* Commonly needed parser functions */
... ...
@@ -160,13 +171,13 @@ int cfg_eat_equal(struct cfg_parser* st, unsigned int flags);
160 160
 
161 161
 int cfg_eat_eol(struct cfg_parser* st, unsigned int flags);
162 162
 
163
-/* Parse section identifier of form [section]. The function expects parameter
163
+/*! \brief Parse section identifier of form [section]. The function expects parameter
164 164
  * param to be of type (str*). The result string is allocated using pkg_malloc
165 165
  * and is zero terminated. To free the memory use pkg_free(((str*)param)->s)
166 166
  */
167 167
 int cfg_parse_section(void* param, struct cfg_parser* st, unsigned int flags);
168 168
 
169
-/* Parse string parameter value, either quoted or unquoted */
169
+/*! \brief Parse string parameter value, either quoted or unquoted */
170 170
 int cfg_parse_str_opt(void* param, struct cfg_parser* st, unsigned int flags);
171 171
 
172 172
 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 175
 
176 176
 int cfg_parse_enum(void* param, struct cfg_parser* st, unsigned int flags);
177 177
 
178
-/* Parser integer parameter value */
178
+/*! \brief Parser integer parameter value */
179 179
 int cfg_parse_int_opt(void* param, struct cfg_parser* st, unsigned int flags);
180 180
 
181 181
 int cfg_parse_int(void* param, struct cfg_parser* st, unsigned int flags);
182 182
 
183
-/* Parse boolean parameter value */
183
+/*! \brief Parse boolean parameter value */
184 184
 int cfg_parse_bool_opt(void* param, struct cfg_parser* st, unsigned int flags);
185 185
 
186 186
 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 44
 
45 45
 
46 46
 
47
-/* adds an entire sublist { s,e } (including s & e )
47
+/*! \brief adds an entire sublist { s,e } (including s & e )
48 48
  * after head
49
- * WARNING: clist_insert_sublist(head, n, n->prev) won't work,
49
+ *
50
+ * \note WARNING: clist_insert_sublist(head, n, n->prev) won't work,
50 51
  *          same for clist_insert_sublist(head, n->next, n)
51 52
  *  (macro!), use  e=n->prev; clist_insert_sublist(head, n, e, ...)
52 53
  *  instead!
... ...
@@ -61,8 +70,9 @@
61 61
 
62 62
 
63 63
 
64
-/* appends an entire sublist { s,e } (including s & e )
64
+/*! \brief appends an entire sublist { s,e } (including s & e )
65 65
  * at the end of the list
66
+ *
66 67
  * WARNING: clist_append_sublist(head, n, n->prev, ...) won't work,
67 68
  *  (macro!), use  e=n->prev; clist_append_sublist(head, n, e, ...)
68 69
  *  instead!
... ...
@@ -78,7 +88,7 @@
78 78
 
79 79
 
80 80
 
81
-/* remove sublist { s,e } (including s & e )
81
+/*! \brief remove sublist { s,e } (including s & e )
82 82
  * always, if start is the beginning of the list use
83 83
  * clist_rm_sublist(head->next, e, next, prev )
84 84
  * WARNING: clist_rm_sublist(n, n->prev, ...) won't work,
... ...
@@ -92,29 +102,29 @@
92 92
 
93 93
 
94 94
 
95
-/* insert after (head) */
95
+/*! \brief insert after (head) */
96 96
 #define clist_insert(head, c, next, prev) \
97 97
 	clist_insert_sublist(head, c, c, next, prev)
98 98
 
99 99
 
100 100
 
101
-/* append at the end of the list (head->prev) */
101
+/*! \brief  append at the end of the list (head->prev) */
102 102
 #define clist_append(head, c, next, prev) \
103 103
 	clist_append_sublist(head, c, c, next, prev)
104 104
 
105 105
 
106 106
 
107
-/* remove and element */
107
+/*! \brief  remove and element */
108 108
 #define clist_rm(c, next, prev) \
109 109
 	clist_rm_sublist(c, c, next, prev)
110 110
 
111 111
 
112 112
 
113
-/* iterate on a clist */
113
+/*! \brief  iterate on a clist */
114 114
 #define clist_foreach(head, v, dir) \
115 115
 	for((v)=(head)->dir; (v)!=(void*)(head); (v)=(v)->dir)
116 116
 
117
-/* iterate on a clist, safe version (requires an extra bak. var)
117
+/*! \brief  iterate on a clist, safe version (requires an extra bak. var)
118 118
  * (it allows removing of the current element) */
119 119
 #define clist_foreach_safe(head, v, bak,  dir) \
120 120
 	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 32
  *
33 33
  */
34 34
 
35
+/*!
36
+ * \file
37
+ * \brief SIP-router core :: Configuration options
38
+ *
39
+ * These settings are settable by the user before compilation
40
+ *
41
+ * \ingroup core
42
+ * Module: \ref core
43
+ */
35 44
 
36 45
 
37 46
 
... ...
@@ -40,38 +44,34 @@
40 40
 
41 41
 #include "types.h"
42 42
 
43
-/* default sip port if none specified */
44
-#define SIP_PORT  5060
45
-#define SIPS_PORT 5061
43
+#define SIP_PORT  5060 /*!< default SIP port if none specified */
44
+#define SIPS_PORT 5061 /*!< default SIP port for TLS if none specified */
46 45
 
47 46
 #define CFG_FILE CFG_DIR NAME ".cfg"
48 47
 
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 */
48
+#define TLS_PKEY_FILE "cert.pem" 	/*!< The certificate private key file */
49
+#define TLS_CERT_FILE "cert.pem"	/*!< The certificate file */
50
+#define TLS_CA_FILE 0			/*!< no CA list file by default */
52 51
 
53 52
 
54
-/* maximum number of addresses on which we will listen */
55
-#define MAX_LISTEN 16
53
+#define MAX_LISTEN 16			/*!< maximum number of addresses on which we will listen */
56 54
 
57
-/* default number of child processes started */
58
-#define CHILD_NO    8
55
+#define CHILD_NO    8			/*!< default number of child processes started */
59 56
 
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 */
57
+#define RT_NO 2 			/*!< routing tables number */
58
+#define FAILURE_RT_NO RT_NO 		/*!< on_failure routing tables number */
59
+#define ONREPLY_RT_NO RT_NO 		/*!< on_reply routing tables number */
60
+#define BRANCH_RT_NO RT_NO 		/*!< branch_route routing tables number */
61
+#define ONSEND_RT_NO 1  		/*!< onsend_route routing tables number */
62
+#define EVENT_RT_NO RT_NO 		/*!< event_route routing tables number */
63
+#define DEFAULT_RT 0 			/*!< default routing table */
67 64
 
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()*/
65
+#define MAX_REC_LEV 100 		/*!< maximum number of recursive calls */
66
+#define ROUTE_MAX_REC_LEV 100 		/*!< maximum number of recursive calls for route()*/
71 67
 
72
-#define MAX_URI_SIZE 1024	/* used when rewriting URIs */
68
+#define MAX_URI_SIZE 1024		/*!< Max URI size used when rewriting URIs */
73 69
 
74
-#define MAX_PATH_SIZE 256 /* Maximum length of path header buffer */
70
+#define MAX_PATH_SIZE 256 		/*!< Maximum length of path header buffer */
75 71
 
76 72
 #define MY_VIA "Via: SIP/2.0/UDP "
77 73
 #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 209
 	#define DEFAULT_RODB_URL_LEN (sizeof(DEFAULT_RODB_URL) - 1)
210 210
 #endif
211 211
 
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"
212
+#define VERSION_TABLE "version"			/*!< table holding versions of other ser tables */
213
+#define VERSION_COLUMN "table_version"		/*!< Column holding version number in version table */
214
+#define TABLENAME_COLUMN "table_name"		/*!< Column holding module name in version table */
216 215
 
217
-/* minimum packet size; smaller packets will be dropped silently */
218
-#define MIN_UDP_PACKET        32
216
+#define MIN_UDP_PACKET        32		/*!< minimum UDP packet size; smaller packets will be dropped silently */
219 217
 
220
-#define MIN_SCTP_PACKET  MIN_UDP_PACKET 
218
+#define MIN_SCTP_PACKET  MIN_UDP_PACKET 	/*!< minimum size of SCTP packet */
221 219
 
222
-#define DEFAULT_RADIUS_CONFIG "/usr/local/etc/radiusclient/radiusclient.conf"
220
+#define DEFAULT_RADIUS_CONFIG "/usr/local/etc/radiusclient/radiusclient.conf"	/*!< Default FreeRadius configuration file */
223 221
 
224 222
 #define DEFAULT_DID "_default"
225 223
 
226
-/*  maximum allowed iterations for a while (to catch runaways) */
227
-#define DEFAULT_MAX_WHILE_LOOPS 100
224
+#define DEFAULT_MAX_WHILE_LOOPS 100		/*!< Maximum allowed iterations for a while (to catch runaways) */
228 225
 
229 226
 #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 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
+
27 28
 /*!
28 29
  * \file
29 30
  * \brief SIP-router core :: 
... ...
@@ -25,6 +25,13 @@
25 25
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA