@@ -29,6 +29,11 @@

  *            (bogdan)

  */

+/*! \file

+ *  \brief USRLOC - List of registered domains

+ *  \ingroup usrloc

+ */

+

 #include "dlist.h"

 #include <stdlib.h>	       /* abort */

@@ -45,15 +50,15 @@

 #include "ul_mod.h"

-/*

+/*! \brief

  * List of all registered domains

  */

 dlist_t* root = 0;

-/*

+/*! \brief

  * Find domain with the given name

- * Returns 0 if the domain was found

+ * \return 0 if the domain was found

  * and 1 of not

  */

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

@@ -337,7 +342,7 @@ static inline int get_all_mem_ucontacts(void *buf, int len, unsigned int flags,

-/*

+/*! \brief

  * Return list of all contacts for all currently registered

  * users in all domains. Caller must provide buffer of

  * sufficient length for fitting all those contacts. In the

@@ -371,12 +376,11 @@ int get_all_ucontacts(void *buf, int len, unsigned int flags,

-/*

+/*! \brief

  * Create a new domain structure

- * Returns 0 if everything went OK, otherwise value < 0

- * is returned

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

  *

- * The structure is NOT created in shared memory so the

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

  * function must be called before ser forks if it should

  * be available to all processes

  */

@@ -418,7 +422,7 @@ 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

@@ -481,7 +485,7 @@ err:

 }

-/*

+/*! \brief

  * Free all allocated memory

  */

 void free_all_udomains(void)

@@ -499,7 +503,7 @@ void free_all_udomains(void)

 }

-/*

+/*! \brief

  * Just for debugging

  */

 void print_all_udomains(FILE* _f)

@@ -517,7 +521,9 @@ void print_all_udomains(FILE* _f)

 }

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

+/*! \brief

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

+ */

 unsigned long get_number_of_users(void)

 {

 	int numberOfUsers = 0;

@@ -536,7 +542,7 @@ unsigned long get_number_of_users(void)

 }

-/*

+/*! \brief

  * Run timer handler of all domains

  */

 int synchronize_all_udomains(void)

@@ -558,7 +564,7 @@ int synchronize_all_udomains(void)

 }

-/*

+/*! \brief

  * Find a particular domain

  */

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

@@ -28,6 +28,12 @@

  *            (bogdan)

  */

+/*! \file

+ *  \brief USRLOC - List of registered domains

+ *  \ingroup usrloc

+ */

+

+

 #ifndef DLIST_H

 #define DLIST_H

@@ -71,13 +77,13 @@ void free_all_udomains(void);

 void print_all_udomains(FILE* _f);

-/*

+/*! \brief

  * Called from timer

  */

 int synchronize_all_udomains(void);

-/*

+/*! \brief

  * Get contacts to all registered users

  */

 typedef int  (*get_all_ucontacts_t) (void* buf, int len, unsigned int flags,

@@ -90,7 +96,7 @@ int get_all_ucontacts(void *, int, unsigned int,

 unsigned long get_number_of_users();

-/*

+/*! \brief

  * Find a particular domain

  */

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

@@ -22,13 +22,19 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/*! \file

+ *  \brief USRLOC - Hash table collision slot related functions

+ *  \ingroup usrloc

+ */

+

+

 #include "hslot.h"

 int ul_locks_no=4;

 gen_lock_set_t* ul_locks=0;

-/*

+/*! \brief

  * Initialize locks

  */

 int ul_init_locks(void)

@@ -114,7 +120,7 @@ int init_slot(struct udomain* _d, hslot_t* _s, int n)

 }

-/*

+/*! \brief

  * Deinitialize given slot structure

  */

 void deinit_slot(hslot_t* _s)

@@ -134,7 +140,7 @@ void deinit_slot(hslot_t* _s)

 }

-/*

+/*! \brief

  * Add an element to an slot's linked list

  */

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

@@ -151,7 +157,7 @@ void slot_add(hslot_t* _s, struct urecord* _r)

 }

-/*

+/*! \brief

  * Remove an element from slot linked list

  */

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

@@ -22,6 +22,12 @@

  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  */

+/*! \file

+ *  \brief USRLOC - Hash table collision slot related functions

+ *  \ingroup usrloc

+ */

+

+

 #ifndef HSLOT_H

 #define HSLOT_H

@@ -37,36 +43,36 @@ struct urecord;

 typedef struct hslot {

-	int n;                  /* Number of elements in the collision slot */

-	struct urecord* first;  /* First element in the list */

-	struct urecord* last;   /* Last element in the list */

-	struct udomain* d;      /* Domain we belong to */

+	int n;                  /*!< Number of elements in the collision slot */

+	struct urecord* first;  /*!< First element in the list */

+	struct urecord* last;   /*!< Last element in the list */

+	struct udomain* d;      /*!< Domain we belong to */

 #ifdef GEN_LOCK_T_PREFERED

-	gen_lock_t *lock;       /* Lock for hash entry - fastlock */

+	gen_lock_t *lock;       /*!< Lock for hash entry - fastlock */

 #else

-	int lockidx;            /* Lock index for hash entry - the rest*/

+	int lockidx;            /*!< Lock index for hash entry - the rest*/

 #endif

 } hslot_t;

-/*

+/*! \brief

  * Initialize slot structure

  */

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

-/*

+/*! \brief

  * Deinitialize given slot structure

  */

 void deinit_slot(hslot_t* _s);

-/*

+/*! \brief

  * Add an element to slot linked list

  */

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

-/*

+/*! \brief

  * Remove an element from slot linked list

  */

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

@@ -28,7 +28,10 @@

  * 2004-06-07 updated to the new DB api (andrei)

  */

-

+/*! \file

+ *  \brief USRLOC - Usrloc contact structure

+ *  \ingroup usrloc

+ */

 #include "ucontact.h"

 #include <string.h>             /* memcpy */

@@ -44,11 +47,10 @@

 #include "ucontact.h"

-/*

+/*! \brief

  * Create a new contact structure

  */

-ucontact_t* new_ucontact(str* _dom, str* _aor, str* _contact,

-														ucontact_info_t* _ci)

+ucontact_t* new_ucontact(str* _dom, str* _aor, str* _contact, ucontact_info_t* _ci)

 {

 	ucontact_t *c;

@@ -96,7 +98,7 @@ error:

-/*

+/*! \brief

  * Free all memory associated with given contact structure

  */

 void free_ucontact(ucontact_t* _c)

@@ -111,7 +113,7 @@ void free_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Print contact, for debugging purposes only

  */

 void print_ucontact(FILE* _f, ucontact_t* _c)

@@ -164,7 +166,7 @@ void print_ucontact(FILE* _f, ucontact_t* _c)

 }

-/*

+/*! \brief

  * Update ucontact structure in memory

  */

 int mem_update_ucontact(ucontact_t* _c, ucontact_info_t* _ci)

@@ -225,7 +227,7 @@ int mem_update_ucontact(ucontact_t* _c, ucontact_info_t* _ci)

 /* ================ State related functions =============== */

-/*

+/*! \brief

  * Update state of the contact

  */

 void st_update_ucontact(ucontact_t* _c)

@@ -259,10 +261,9 @@ void st_update_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Update state of the contact

- * Returns 1 if the contact should be

- * delete from memory immediately,

+ * \return 1 if the contact should be deleted from memory immediately,

  * 0 otherwise

  */

 int st_delete_ucontact(ucontact_t* _c)

@@ -301,10 +302,10 @@ int st_delete_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Called when the timer is about to delete

- * an expired contact, this routine returns

- * 1 if the contact should be removed from

+ * an expired contact. 

+ * \return 1 if the contact should be removed from

  * the database and 0 otherwise

  */

 int st_expired_ucontact(ucontact_t* _c)

@@ -331,7 +332,7 @@ int st_expired_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Called when the timer is about flushing the contact,

  * updates contact state and returns 1 if the contact

  * should be inserted, 2 if update and 0 otherwise

@@ -368,7 +369,7 @@ int st_flush_ucontact(ucontact_t* _c)

 /* ============== Database related functions ================ */

-/*

+/*! \brief

  * Insert contact into the database

  */

 int db_insert_ucontact(ucontact_t* _c)

@@ -504,7 +505,7 @@ int db_insert_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Update contact in the database

  */

 int db_update_ucontact(ucontact_t* _c)

@@ -633,7 +634,7 @@ int db_update_ucontact(ucontact_t* _c)

 }

-/*

+/*! \brief

  * Delete contact from the database

  */

 int db_delete_ucontact(ucontact_t* _c)

@@ -749,7 +750,7 @@ static inline void update_contact_pos(struct urecord* _r, ucontact_t* _c)

 }

-/*

+/*! \brief

  * Update ucontact with new values

  */

 int update_ucontact(struct urecord* _r, ucontact_t* _c, ucontact_info_t* _ci)

@@ -28,6 +28,11 @@

  *             instead of UDP package (bogdan)

  */

+/*! \file

+ *  \brief USRLOC - Usrloc contact structure

+ *  \ingroup usrloc

+ */

+

 #ifndef UCONTACT_H

 #define UCONTACT_H

@@ -40,42 +45,46 @@

+/*! \brief States for in-memory contacts in regards to contact storage handler (db, in-memory, ldap etc) */

 typedef enum cstate {

-	CS_NEW,        /* New contact - not flushed yet */

-	CS_SYNC,       /* Synchronized contact with the database */

-	CS_DIRTY       /* Update contact - not flushed yet */

+	CS_NEW,        /*!< New contact - not flushed yet */

+	CS_SYNC,       /*!< Synchronized contact with the database */

+	CS_DIRTY       /*!< Update contact - not flushed yet */

 } cstate_t;

-/*

+/*! \brief

  * Flags that can be associated with a Contact

  */

 typedef enum flags {

-	FL_NONE        = 0,          /* No flags set */

-	FL_MEM         = 1 << 0,     /* Update memory only */

-	FL_ALL         = (int)0xFFFFFFFF  /* All flags set */

+	FL_NONE        = 0,          /*!< No flags set */

+	FL_MEM         = 1 << 0,     /*!< Update memory only */

+	FL_ALL         = (int)0xFFFFFFFF  /*!< All flags set */

 } flags_t;

+/*! \brief

+ * Main structure for handling of registered Contact: data 

+ */

 typedef struct ucontact {

-	str* domain;            /* Pointer to domain name (NULL terminated) */

-	str* aor;               /* Pointer to the AOR string in record structure*/

-	str c;                  /* Contact address */

-	str received;           /* IP+port+protocol we recved the REGISTER from */

-	str path;               /* Path header */

-	time_t expires;         /* expires parameter */

-	qvalue_t q;             /* q parameter */

-	str callid;             /* Call-ID header field */

-	int cseq;               /* CSeq value */

-	cstate_t state;         /* State of the contact */

-	unsigned int flags;     /* Various flags (NAT, ping type, etc) */

-	unsigned int cflags;    /* custom contact flags (from script) */

-	str user_agent;         /* User-Agent header field */

-	struct socket_info *sock; /* received soket */

-	time_t last_modified;   /* when the record was last modified */

-	unsigned int methods;   /* Supported methods */

-	struct ucontact* next;  /* Next contact in the linked list */

-	struct ucontact* prev;  /* Previous contact in the linked list */

+	str* domain;            /*!< Pointer to domain name (NULL terminated) */

+	str* aor;               /*!< Pointer to the AOR string in record structure*/

+	str c;                  /*!< Contact address */

+	str received;           /*!< IP+port+protocol we received the REGISTER from */

+	str path;               /*!< Path header */

+	time_t expires;         /*!< Expires parameter */

+	qvalue_t q;             /*!< q parameter */

+	str callid;             /*!< Call-ID header field of registration */

+	int cseq;               /*!< CSeq value */

+	cstate_t state;         /*!< State of the contact (\ref cstate) */

+	unsigned int flags;     /*!< Various flags (NAT, ping type, etc) */

+	unsigned int cflags;    /*!< Custom contact flags (from script) */

+	str user_agent;         /*!< User-Agent header field */

+	struct socket_info *sock; /*!< received socket */

+	time_t last_modified;   /*!< When the record was last modified */

+	unsigned int methods;   /*!< Supported methods */

+	struct ucontact* next;  /*!< Next contact in the linked list */

+	struct ucontact* prev;  /*!< Previous contact in the linked list */

 } ucontact_t;

 typedef struct ucontact_info {

@@ -93,7 +102,7 @@ typedef struct ucontact_info {

 	time_t last_modified;

 } ucontact_info_t;

-/*

+/*! \brief

  * ancient time used for marking the contacts forced to expired

  */

 #define UL_EXPIRED_TIME 10

@@ -104,26 +113,26 @@ typedef struct ucontact_info {

 #define VALID_CONTACT(c, t)   ((c->expires>t) || (c->expires==0))

-/*

+/*! \brief

  * Create a new contact structure

  */

 ucontact_t* new_ucontact(str* _dom, str* _aor, str* _contact,

 		ucontact_info_t* _ci);

-/*

+/*! \brief

  * Free all memory associated with given contact structure

  */

 void free_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Print contact, for debugging purposes only

  */

 void print_ucontact(FILE* _f, ucontact_t* _c);

-/*

+/*! \brief

  * Update existing contact in memory with new values

  */

 int mem_update_ucontact(ucontact_t* _c, ucontact_info_t *_ci);

@@ -132,14 +141,14 @@ int mem_update_ucontact(ucontact_t* _c, ucontact_info_t *_ci);

 /* ===== State transition functions - for write back cache scheme ======== */

-/*

+/*! \brief

  * Update state of the contact if we

  * are using write-back scheme

  */

 void st_update_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Update state of the contact if we

  * are using write-back scheme

  * Returns 1 if the contact should be

@@ -149,7 +158,7 @@ void st_update_ucontact(ucontact_t* _c);

 int st_delete_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Called when the timer is about to delete

  * an expired contact, this routine returns

  * 1 if the contact should be removed from

@@ -158,7 +167,7 @@ int st_delete_ucontact(ucontact_t* _c);

 int st_expired_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Called when the timer is about flushing the contact,

  * updates contact state and returns 1 if the contact

  * should be inserted, 2 if updated and 0 otherwise

@@ -169,19 +178,19 @@ int st_flush_ucontact(ucontact_t* _c);

 /* ==== Database related functions ====== */

-/*

+/*! \brief

  * Insert contact into the database

  */

 int db_insert_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Update contact in the database

  */

 int db_update_ucontact(ucontact_t* _c);

-/*

+/*! \brief

  * Delete contact from the database

  */

 int db_delete_ucontact(ucontact_t* _c);

@@ -191,7 +200,7 @@ int db_delete_ucontact(ucontact_t* _c);

 struct urecord;

-/*

+/*! \brief

  * Update ucontact with new values

  */

 typedef int (*update_ucontact_t)(struct urecord* _r, ucontact_t* _c,

@@ -29,6 +29,11 @@

  *   

  */

+/*! \file

+ *  \brief USRLOC - 

+ *  \ingroup usrloc

+ */

+

 #include "udomain.h"

 #include <string.h>

 #include "../../parser/parse_methods.h"

@@ -66,7 +71,7 @@ static char *build_stat_name( str* domain, char *var_name)

 #endif

-/*

+/*! \brief

  * Create a new domain structure

  * _n is pointer to str representing

  * name of the domain, the string is

@@ -138,7 +143,7 @@ error0:

 }

-/*

+/*! \brief

  * Free all memory allocated for

  * the domain

  */

@@ -158,8 +163,8 @@ void free_udomain(udomain_t* _d)

 }

-/*

- * Returns a statis dummy urecord for temporary usage

+/*! \brief

+ * Returns a static dummy urecord for temporary usage

  */

 static inline void get_static_urecord(udomain_t* _d, str* _aor,

 														struct urecord** _r)

@@ -173,7 +178,7 @@ static inline void get_static_urecord(udomain_t* _d, str* _aor,

 }

-/*

+/*! \brief

  * Just for debugging

  */

 void print_udomain(FILE* _f, udomain_t* _d)

@@ -205,7 +210,7 @@ void print_udomain(FILE* _f, udomain_t* _d)

 }

-/*

+/*! \brief

  * expects 12 rows (contact, expirs, q, callid, cseq, flags, 

  *   ua, received, path, socket, methods, last_modified)

  */

@@ -474,7 +479,7 @@ error:

 }

-/*

+/*! \brief

  * loads from DB all contacts for an AOR

  */

 urecord_t* db_load_urecord(db_con_t* _c, udomain_t* _d, str *_aor)

@@ -611,7 +616,7 @@ int db_timer_udomain(udomain_t* _d)

 }

-/* performs a dummy query just to see if DB is ok */

+/*! \brief performs a dummy query just to see if DB is ok */

 int testdb_udomain(db_con_t* con, udomain_t* d)

 {

 	db_key_t key[1], col[1];

@@ -640,7 +645,7 @@ int testdb_udomain(db_con_t* con, udomain_t* d)

 }

-/*

+/*! \brief

  * Insert a new record into domain

  */

 int mem_insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

@@ -659,7 +664,7 @@ int mem_insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

 }

-/*

+/*! \brief

  * Remove a record from domain

  */

 void mem_delete_urecord(udomain_t* _d, struct urecord* _r)

@@ -703,7 +708,7 @@ int mem_timer_udomain(udomain_t* _d)

 }

-/*

+/*! \brief

  * Get lock

  */

 void lock_udomain(udomain_t* _d, str* _aor)

@@ -722,7 +727,7 @@ void lock_udomain(udomain_t* _d, str* _aor)

 }

-/*

+/*! \brief

  * Release lock

  */

 void unlock_udomain(udomain_t* _d, str* _aor)

@@ -739,7 +744,7 @@ void unlock_udomain(udomain_t* _d, str* _aor)

 	}

 }

-/*

+/*! \brief

  * Get lock

  */

 void lock_ulslot(udomain_t* _d, int i)

@@ -753,7 +758,7 @@ void lock_ulslot(udomain_t* _d, int i)

 }

-/*

+/*! \brief

  * Release lock

  */

 void unlock_ulslot(udomain_t* _d, int i)

@@ -768,7 +773,7 @@ void unlock_ulslot(udomain_t* _d, int i)

-/*

+/*! \brief

  * Create and insert a new record

  */

 int insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

@@ -785,7 +790,7 @@ int insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

 }

-/*

+/*! \brief

  * Obtain a urecord pointer if the urecord exists in domain

  */

 int get_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

@@ -821,7 +826,7 @@ int get_urecord(udomain_t* _d, str* _aor, struct urecord** _r)

 }

-/*

+/*! \brief

  * Delete a urecord from domain

  */

 int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r)

@@ -28,6 +28,11 @@

  */

+/*! \file

+ *  \brief USRLOC - Usrloc domain structure

+ *  \ingroup usrloc

+ */

+

 #ifndef UDOMAIN_H

 #define UDOMAIN_H

@@ -41,25 +46,25 @@

 #include "hslot.h"

-struct hslot;   /* Hash table slot */

-struct urecord; /* Usrloc record */

+struct hslot;   /*!< Hash table slot */

+struct urecord; /*!< Usrloc record */

-/*

+/*! \brief

  * The structure represents a usrloc domain

  */

 typedef struct udomain {

-	str* name;                 /* Domain name (NULL terminated) */

-	int size;                  /* Hash table size */

-	struct hslot* table;       /* Hash table - array of collision slots */

+	str* name;                 /*!< Domain name (NULL terminated) */

+	int size;                  /*!< Hash table size */

+	struct hslot* table;       /*!< Hash table - array of collision slots */

 	/* statistics */

-	stat_var *users;           /* no of registered users */

-	stat_var *contacts;        /* no of registered contacts */

-	stat_var *expires;         /* no of expires */

+	stat_var *users;           /*!< no of registered users */

+	stat_var *contacts;        /*!< no of registered contacts */

+	stat_var *expires;         /*!< no of expires */

 } udomain_t;

-/*

+/*! \brief

  * Create a new domain structure

  * _n is pointer to str representing

  * name of the domain, the string is

@@ -70,63 +75,63 @@ typedef struct udomain {

 int new_udomain(str* _n, int _s, udomain_t** _d);

-/*

+/*! \brief

  * Free all memory allocated for

  * the domain

  */

 void free_udomain(udomain_t* _d);

-/*

+/*! \brief

  * Just for debugging

  */

 void print_udomain(FILE* _f, udomain_t* _d);

-/*

+/*! \brief

  * Load data from a database

  */

 int preload_udomain(db_con_t* _c, udomain_t* _d);

-/*

+/*! \brief

  * Check the DB validity of a domain

  */

 int testdb_udomain(db_con_t* con, udomain_t* d);

-/*

+/*! \brief

  * Timer handler for given domain (db_only)

  */

 int db_timer_udomain(udomain_t* _d);

-/*

+/*! \brief

  * Timer handler for given domain

  */

 int mem_timer_udomain(udomain_t* _d);

-/*

+/*! \brief

  * Insert record into domain

  */

 int mem_insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r);

-/*

+/*! \brief

  * Delete a record

  */

 void mem_delete_urecord(udomain_t* _d, struct urecord* _r);

-/*

+/*! \brief

  * Get lock

  */

 typedef void (*lock_udomain_t)(udomain_t* _d, str *_aor);

 void lock_udomain(udomain_t* _d, str *_aor);

-/*

+/*! \brief

  * Release lock

  */

 typedef void (*unlock_udomain_t)(udomain_t* _d, str *_aor);

@@ -139,21 +144,21 @@ void unlock_ulslot(udomain_t* _d, int i);

 /* ===== module interface ======= */

-/*

+/*! \brief

  * Create and insert a new record

  */

 typedef int (*insert_urecord_t)(udomain_t* _d, str* _aor, struct urecord** _r);

 int insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r);

-/*

+/*! \brief

  * Obtain a urecord pointer if the urecord exists in domain

  */

 typedef int  (*get_urecord_t)(udomain_t* _d, str* _a, struct urecord** _r);

 int get_urecord(udomain_t* _d, str* _aor, struct urecord** _r);

-/*

+/*! \brief

  * Delete a urecord from domain

  */

 typedef int  (*delete_urecord_t)(udomain_t* _d, str* _a, struct urecord* _r);