Browse code

- some doxygen extensions

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

Henning Westerholt authored on 10/10/2008 08:49:48
Showing 4 changed files
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * List of registered domains
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -52,16 +50,17 @@
52 50
 #include "ul_mod.h"
53 51
 
54 52
 
55
-/*! \brief
56
- * List of all registered domains
53
+/*!
54
+ * \brief Global list of all registered domains
57 55
  */
58 56
 dlist_t* root = 0;
59 57
 
60 58
 
61
-/*! \brief
62
- * Find domain with the given name
63
- * \return 0 if the domain was found
64
- * and 1 of not
59
+/*!
60
+ * \brief Find domain with the given name
61
+ * \param _n domain name
62
+ * \param _d pointer to domain
63
+ * \return 0 if the domain was found and 1 of not
65 64
  */
66 65
 static inline int find_dlist(str* _n, dlist_t** _d)
67 66
 {
... ...
@@ -82,7 +81,16 @@ static inline int find_dlist(str* _n, dlist_t** _d)
82 81
 }
83 82
 
84 83
 
85
-
84
+/*!
85
+ * \brief Get all contacts from the database, in partitions if wanted
86
+ * \see get_all_ucontacts
87
+ * \param buf target buffer
88
+ * \param len length of buffer
89
+ * \param flags contact flags
90
+ * \param part_idx part index
91
+ * \param part_max maximal part
92
+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure
93
+ */
86 94
 static inline int get_all_db_ucontacts(void *buf, int len, unsigned int flags,
87 95
 								unsigned int part_idx, unsigned int part_max)
88 96
 {
... ...
@@ -240,7 +248,16 @@ static inline int get_all_db_ucontacts(void *buf, int len, unsigned int flags,
240 248
 }
241 249
 
242 250
 
243
-
251
+/*!
252
+ * \brief Get all contacts from the memory, in partitions if wanted
253
+ * \see get_all_ucontacts
254
+ * \param buf target buffer
255
+ * \param len length of buffer
256
+ * \param flags contact flags
257
+ * \param part_idx part index
258
+ * \param part_max maximal part
259
+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure
260
+ */
244 261
 static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,
245 262
 								unsigned int part_idx, unsigned int part_max)
246 263
 {
... ...
@@ -344,9 +361,11 @@ static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,
344 361
 
345 362
 
346 363
 
347
-/*! \brief
364
+/*!
365
+ * \brief Get all contacts from the database, in partitions if wanted
366
+ *
348 367
  * Return list of all contacts for all currently registered
349
- * users in all domains. Caller must provide buffer of
368
+ * users in all domains. The caller must provide buffer of
350 369
  * sufficient length for fitting all those contacts. In the
351 370
  * case when buffer was exhausted, the function returns
352 371
  * estimated amount of additional space needed, in this
... ...
@@ -366,6 +385,13 @@ static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,
366 385
  * +------------+----------+-----+------+-----+
367 386
  * |000000000000|
368 387
  * +------------+
388
+ *
389
+ * \param buf target buffer
390
+ * \param len length of buffer
391
+ * \param flags contact flags
392
+ * \param part_idx part index
393
+ * \param part_max maximal part
394
+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure
369 395
  */
370 396
 int get_all_ucontacts(void *buf, int len, unsigned int flags,
371 397
 								unsigned int part_idx, unsigned int part_max)
... ...
@@ -378,12 +404,12 @@ int get_all_ucontacts(void *buf, int len, unsigned int flags,
378 404
 
379 405
 
380 406
 
381
-/*! \brief
382
- * Create a new domain structure
407
+/*!
408
+ * \brief Create a new domain structure
383 409
  * \return 0 if everything went OK, otherwise value < 0 is returned
384 410
  *
385 411
  * \note The structure is NOT created in shared memory so the
386
- * function must be called before ser forks if it should
412
+ * function must be called before the server forks if it should
387 413
  * be available to all processes
388 414
  */
389 415
 static inline int new_dlist(str* _n, dlist_t** _d)
... ...
@@ -424,11 +450,15 @@ static inline int new_dlist(str* _n, dlist_t** _d)
424 450
 }
425 451
 
426 452
 
427
-/*! \brief
428
- * Function registers a new domain with usrloc
429
- * if the domain exists, pointer to existing structure
430
- * will be returned, otherwise a new domain will be
431
- * created
453
+/*!
454
+ * \brief Registers a new domain with usrloc
455
+ *
456
+ * Function registers a new domain with usrloc.
457
+ * If the domain exists, a pointer to existing structure
458
+ * will be returned, otherwise a new domain will be created
459
+ * \param _n domain name
460
+ * \param _d pointer to domain
461
+ * \return 0 on success, -1 on failure
432 462
  */
433 463
 int register_udomain(const char* _n, udomain_t** _d)
434 464
 {
... ...
@@ -487,8 +517,8 @@ err:
487 517
 }
488 518
 
489 519
 
490
-/*! \brief
491
- * Free all allocated memory
520
+/*!
521
+ * \brief Free all allocated memory for domains
492 522
  */
493 523
 void free_all_udomains(void)
494 524
 {
... ...
@@ -505,8 +535,8 @@ void free_all_udomains(void)
505 535
 }
506 536
 
507 537
 
508
-/*! \brief
509
- * Just for debugging
538
+/*!
539
+ * \brief Just for debugging
510 540
  */
511 541
 void print_all_udomains(FILE* _f)
512 542
 {
... ...
@@ -523,8 +553,9 @@ void print_all_udomains(FILE* _f)
523 553
 }
524 554
 
525 555
 
526
-/*! \brief
527
- *  Loops through all domains summing up the number of users. 
556
+/*!
557
+ * \brief Loops through all domains summing up the number of users
558
+ * \return the number of users, could be zero
528 559
  */
529 560
 unsigned long get_number_of_users(void)
530 561
 {
... ...
@@ -544,8 +575,9 @@ unsigned long get_number_of_users(void)
544 575
 }
545 576
 
546 577
 
547
-/*! \brief
548
- * Run timer handler of all domains
578
+/*!
579
+ * \brief Run timer handler of all domains
580
+ * \return 0 if all timer return 0, != 0 otherwise
549 581
  */
550 582
 int synchronize_all_udomains(void)
551 583
 {
... ...
@@ -566,8 +598,11 @@ int synchronize_all_udomains(void)
566 598
 }
567 599
 
568 600
 
569
-/*! \brief
570
- * Find a particular domain
601
+/*!
602
+ * \brief Find a particular domain, small wrapper around find_dlist
603
+ * \param _d domain name
604
+ * \param _p pointer to domain if found
605
+ * \return 1 if domain was found, 0 otherwise
571 606
  */
572 607
 int find_domain(str* _d, udomain_t** _p)
573 608
 {
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * List of registered domains
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -34,7 +32,6 @@
34 32
  */
35 33
 
36 34
 
37
-
38 35
 #ifndef DLIST_H
39 36
 #define DLIST_H
40 37
 
... ...
@@ -43,13 +40,13 @@
43 40
 #include "../../str.h"
44 41
 
45 42
 
46
-/*
43
+/*!
47 44
  * List of all domains registered with usrloc
48 45
  */
49 46
 typedef struct dlist {
50
-	str name;            /* Name of the domain (null terminated) */
51
-	udomain_t* d;        /* Payload */
52
-	struct dlist* next;  /* Next element in the list */
47
+	str name;            /*!< Name of the domain (null terminated) */
48
+	udomain_t* d;        /*!< Payload */
49
+	struct dlist* next;  /*!< Next element in the list */
53 50
 } dlist_t;
54 51
 
55 52
 
... ...
@@ -1,8 +1,6 @@
1
-/* 
1
+/*
2 2
  * $Id$ 
3 3
  *
4
- * Hash table collision slot related functions
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -33,11 +31,15 @@
33 31
 
34 32
 #include "hslot.h"
35 33
 
34
+/*! number of locks */
36 35
 int ul_locks_no=4;
36
+/*! global list of locks */
37 37
 gen_lock_set_t* ul_locks=0;
38 38
 
39
-/*! \brief
40
- * Initialize locks
39
+
40
+/*!
41
+ * \brief Initialize locks for the hash table
42
+ * \param 0 on success, -1 on failure
41 43
  */
42 44
 int ul_init_locks(void)
43 45
 {
... ...
@@ -66,6 +68,9 @@ int ul_init_locks(void)
66 68
 }
67 69
 
68 70
 
71
+/*!
72
+ * \brief Unlock all locks on the list
73
+ */
69 74
 void ul_unlock_locks(void)
70 75
 {
71 76
 	unsigned int i;
... ...
@@ -83,6 +88,9 @@ void ul_unlock_locks(void)
83 88
 }
84 89
 
85 90
 
91
+/*!
92
+ * \param Destroy all locks on the list
93
+ */
86 94
 void ul_destroy_locks(void)
87 95
 {
88 96
 	if (ul_locks !=0){
... ...
@@ -92,19 +100,31 @@ void ul_destroy_locks(void)
92 100
 }
93 101
 
94 102
 #ifndef GEN_LOCK_T_PREFERED
103
+/*!
104
+ * \brief Lock a lock with a certain index
105
+ * \param idx lock index
106
+ */
95 107
 void ul_lock_idx(int idx)
96 108
 {
97 109
 	lock_set_get(ul_locks, idx);
98 110
 }
99 111
 
112
+
113
+/*!
114
+ * \brief Release a lock with a certain index
115
+ * \param idx lock index
116
+ */
100 117
 void ul_release_idx(int idx)
101 118
 {
102 119
 	lock_set_release(ul_locks, idx);
103 120
 }
104 121
 #endif
105 122
 
106
-/*
107
- * Initialize cache slot structure
123
+/*!
124
+ * \brief Initialize cache slot structure
125
+ * \param _d domain for the hash slot
126
+ * \param _s hash slot
127
+ * \param n used to get the slot number (modulo number or locks)
108 128
  */
109 129
 int init_slot(struct udomain* _d, hslot_t* _s, int n)
110 130
 {
... ...
@@ -122,8 +142,9 @@ int init_slot(struct udomain* _d, hslot_t* _s, int n)
122 142
 }
123 143
 
124 144
 
125
-/*! \brief
126
- * Deinitialize given slot structure
145
+/*!
146
+ * \brief Deinitialize given slot structure
147
+ * \param _s hash slot
127 148
  */
128 149
 void deinit_slot(hslot_t* _s)
129 150
 {
... ...
@@ -142,8 +163,10 @@ void deinit_slot(hslot_t* _s)
142 163
 }
143 164
 
144 165
 
145
-/*! \brief
146
- * Add an element to an slot's linked list
166
+/*!
167
+ * \brief Add an element to an slot's linked list
168
+ * \param _s hash slot
169
+ * \param _r added record
147 170
  */
148 171
 void slot_add(hslot_t* _s, struct urecord* _r)
149 172
 {
... ...
@@ -159,8 +182,10 @@ void slot_add(hslot_t* _s, struct urecord* _r)
159 182
 }
160 183
 
161 184
 
162
-/*! \brief
163
- * Remove an element from slot linked list
185
+/*!
186
+ * \brief Remove an element from slot linked list
187
+ * \param _s hash slot
188
+ * \param _r removed record
164 189
  */
165 190
 void slot_rem(hslot_t* _s, struct urecord* _r)
166 191
 {
... ...
@@ -1,8 +1,6 @@
1
-/* 
1
+/*
2 2
  * $Id$ 
3 3
  *
4
- * Usrloc hash table collision slot
5
- *
6 4
  * Copyright (C) 2001-2003 FhG Fokus
7 5
  *
8 6
  * This file is part of Kamailio, a free SIP server.