@@ -1,8 +1,6 @@

 /*

  * $Id$

  *

- * List of registered domains

- *

  * Copyright (C) 2001-2003 FhG Fokus

  *

  * This file is part of Kamailio, a free SIP server.

@@ -52,16 +50,17 @@

 #include "ul_mod.h"

-/*! \brief

- * List of all registered domains

+/*!

+ * \brief Global list of all registered domains

  */

 dlist_t* root = 0;

-/*! \brief

- * Find domain with the given name

- * \return 0 if the domain was found

- * and 1 of not

+/*!

+ * \brief Find domain with the given name

+ * \param _n domain name

+ * \param _d pointer to domain

+ * \return 0 if the domain was found and 1 of not

  */

 static inline int find_dlist(str* _n, dlist_t** _d)

 {

@@ -82,7 +81,16 @@ static inline int find_dlist(str* _n, dlist_t** _d)

 }

-

+/*!

+ * \brief Get all contacts from the database, in partitions if wanted

+ * \see get_all_ucontacts

+ * \param buf target buffer

+ * \param len length of buffer

+ * \param flags contact flags

+ * \param part_idx part index

+ * \param part_max maximal part

+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure

+ */

 static inline int get_all_db_ucontacts(void *buf, int len, unsigned int flags,

 								unsigned int part_idx, unsigned int part_max)

 {

@@ -240,7 +248,16 @@ static inline int get_all_db_ucontacts(void *buf, int len, unsigned int flags,

 }

-

+/*!

+ * \brief Get all contacts from the memory, in partitions if wanted

+ * \see get_all_ucontacts

+ * \param buf target buffer

+ * \param len length of buffer

+ * \param flags contact flags

+ * \param part_idx part index

+ * \param part_max maximal part

+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure

+ */

 static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,

 								unsigned int part_idx, unsigned int part_max)

 {

@@ -344,9 +361,11 @@ static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,

-/*! \brief

+/*!

+ * \brief Get all contacts from the database, in partitions if wanted

+ *

  * Return list of all contacts for all currently registered

- * users in all domains. Caller must provide buffer of

+ * users in all domains. The caller must provide buffer of

  * sufficient length for fitting all those contacts. In the

  * case when buffer was exhausted, the function returns

  * 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,

  * +------------+----------+-----+------+-----+

  * |000000000000|

  * +------------+

+ *

+ * \param buf target buffer

+ * \param len length of buffer

+ * \param flags contact flags

+ * \param part_idx part index

+ * \param part_max maximal part

+ * \return 0 on success, positive if buffer size was not sufficient, negative on failure

  */

 int get_all_ucontacts(void *buf, int len, unsigned int flags,

 								unsigned int part_idx, unsigned int part_max)

@@ -378,12 +404,12 @@ int get_all_ucontacts(void *buf, int len, unsigned int flags,

-/*! \brief

- * Create a new domain structure

+/*!

+ * \brief Create a new domain structure

  * \return 0 if everything went OK, otherwise value < 0 is returned

  *

  * \note The structure is NOT created in shared memory so the

- * function must be called before ser forks if it should

+ * function must be called before the server forks if it should

  * be available to all processes

  */

 static inline int new_dlist(str* _n, dlist_t** _d)

@@ -424,11 +450,15 @@ static inline int new_dlist(str* _n, dlist_t** _d)

 }

-/*! \brief

- * Function registers a new domain with usrloc

- * if the domain exists, pointer to existing structure

- * will be returned, otherwise a new domain will be

- * created

+/*!

+ * \brief Registers a new domain with usrloc

+ *

+ * Function registers a new domain with usrloc.

+ * If the domain exists, a pointer to existing structure

+ * will be returned, otherwise a new domain will be created

+ * \param _n domain name

+ * \param _d pointer to domain

+ * \return 0 on success, -1 on failure

  */

 int register_udomain(const char* _n, udomain_t** _d)

 {

@@ -487,8 +517,8 @@ err:

 }

-/*! \brief

- * Free all allocated memory

+/*!

+ * \brief Free all allocated memory for domains

  */

 void free_all_udomains(void)

 {

@@ -505,8 +535,8 @@ void free_all_udomains(void)

 }

-/*! \brief

- * Just for debugging

+/*!

+ * \brief Just for debugging

  */

 void print_all_udomains(FILE* _f)

 {

@@ -523,8 +553,9 @@ void print_all_udomains(FILE* _f)

 }

-/*! \brief

- *  Loops through all domains summing up the number of users. 

+/*!

+ * \brief Loops through all domains summing up the number of users

+ * \return the number of users, could be zero

  */

 unsigned long get_number_of_users(void)

 {

@@ -544,8 +575,9 @@ unsigned long get_number_of_users(void)

 }

-/*! \brief

- * Run timer handler of all domains

+/*!

+ * \brief Run timer handler of all domains

+ * \return 0 if all timer return 0, != 0 otherwise

  */

 int synchronize_all_udomains(void)

 {

@@ -566,8 +598,11 @@ int synchronize_all_udomains(void)

 }

-/*! \brief

- * Find a particular domain

+/*!

+ * \brief Find a particular domain, small wrapper around find_dlist

+ * \param _d domain name

+ * \param _p pointer to domain if found

+ * \return 1 if domain was found, 0 otherwise

  */

 int find_domain(str* _d, udomain_t** _p)

 {

@@ -1,8 +1,6 @@

 /*

  * $Id$

  *

- * List of registered domains

- *

  * Copyright (C) 2001-2003 FhG Fokus

  *

  * This file is part of Kamailio, a free SIP server.

@@ -34,7 +32,6 @@

  */

-

 #ifndef DLIST_H

 #define DLIST_H

@@ -43,13 +40,13 @@

 #include "../../str.h"

-/*

+/*!

  * List of all domains registered with usrloc

  */

 typedef struct dlist {

-	str name;            /* Name of the domain (null terminated) */

-	udomain_t* d;        /* Payload */

-	struct dlist* next;  /* Next element in the list */

+	str name;            /*!< Name of the domain (null terminated) */

+	udomain_t* d;        /*!< Payload */

+	struct dlist* next;  /*!< Next element in the list */

 } dlist_t;

@@ -1,8 +1,6 @@

-/* 

+/*

  * $Id$ 

  *

- * Hash table collision slot related functions

- *

  * Copyright (C) 2001-2003 FhG Fokus

  *

  * This file is part of Kamailio, a free SIP server.

@@ -33,11 +31,15 @@

 #include "hslot.h"

+/*! number of locks */

 int ul_locks_no=4;

+/*! global list of locks */

 gen_lock_set_t* ul_locks=0;

-/*! \brief

- * Initialize locks

+

+/*!

+ * \brief Initialize locks for the hash table

+ * \param 0 on success, -1 on failure

  */

 int ul_init_locks(void)

 {

@@ -66,6 +68,9 @@ int ul_init_locks(void)

 }

+/*!

+ * \brief Unlock all locks on the list

+ */

 void ul_unlock_locks(void)

 {

 	unsigned int i;

@@ -83,6 +88,9 @@ void ul_unlock_locks(void)

 }

+/*!

+ * \param Destroy all locks on the list

+ */

 void ul_destroy_locks(void)

 {

 	if (ul_locks !=0){

@@ -92,19 +100,31 @@ void ul_destroy_locks(void)

 }

 #ifndef GEN_LOCK_T_PREFERED

+/*!

+ * \brief Lock a lock with a certain index

+ * \param idx lock index

+ */

 void ul_lock_idx(int idx)

 {

 	lock_set_get(ul_locks, idx);

 }

+

+/*!

+ * \brief Release a lock with a certain index

+ * \param idx lock index

+ */

 void ul_release_idx(int idx)

 {

 	lock_set_release(ul_locks, idx);

 }

 #endif

-/*

- * Initialize cache slot structure

+/*!

+ * \brief Initialize cache slot structure

+ * \param _d domain for the hash slot

+ * \param _s hash slot

+ * \param n used to get the slot number (modulo number or locks)

  */

 int init_slot(struct udomain* _d, hslot_t* _s, int n)

 {

@@ -122,8 +142,9 @@ int init_slot(struct udomain* _d, hslot_t* _s, int n)

 }

-/*! \brief

- * Deinitialize given slot structure

+/*!

+ * \brief Deinitialize given slot structure

+ * \param _s hash slot

  */

 void deinit_slot(hslot_t* _s)

 {

@@ -142,8 +163,10 @@ void deinit_slot(hslot_t* _s)

 }

-/*! \brief

- * Add an element to an slot's linked list

+/*!

+ * \brief Add an element to an slot's linked list

+ * \param _s hash slot

+ * \param _r added record

  */

 void slot_add(hslot_t* _s, struct urecord* _r)

 {

@@ -159,8 +182,10 @@ void slot_add(hslot_t* _s, struct urecord* _r)

 }

-/*! \brief

- * Remove an element from slot linked list

+/*!

+ * \brief Remove an element from slot linked list

+ * \param _s hash slot

+ * \param _r removed record

  */

 void slot_rem(hslot_t* _s, struct urecord* _r)

 {

@@ -1,8 +1,6 @@

-/* 

+/*

  * $Id$ 

  *

- * Usrloc hash table collision slot

- *

  * Copyright (C) 2001-2003 FhG Fokus

  *

  * This file is part of Kamailio, a free SIP server.