[SR-Dev] git:master: complete doxygen documentation for dlg_hash header and implementation

[Henning Westerholt]

Module: sip-router
Branch: master
Commit: f666a4e53f79843f82b867c5dd4ce64e100feb82
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=f666a4e53f79843f82b867c5dd4ce64e100feb82

Author: Henning Westerholt <henning.westerholt at 1und1.de>
Committer: Henning Westerholt <henning.westerholt at 1und1.de>
Date:   Sun May  3 20:02:10 2009 +0200

complete doxygen documentation for dlg_hash header and implementation

---

 modules_k/dialog/dlg_hash.c |   48 +++++++++++++++++++++++++++--
 modules_k/dialog/dlg_hash.h |   72 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+), 3 deletions(-)

diff --git a/modules_k/dialog/dlg_hash.c b/modules_k/dialog/dlg_hash.c
index e7f9522..a699e72 100644
--- a/modules_k/dialog/dlg_hash.c
+++ b/modules_k/dialog/dlg_hash.c
@@ -42,6 +42,14 @@
  *             CONFIRMED_NA due delayed "200 OK" (bogdan)
  */
 
+
+/*!
+ * \file
+ * \brief Functions related to dialog creation and searching
+ * \ingroup dialog
+ * Module: \ref dialog
+ */
+
 #include <stdlib.h>
 #include <string.h>
 
@@ -450,7 +458,11 @@ struct dlg_cell* get_dlg( str *callid, str *ftag, str *ttag, unsigned int *dir)
 }
 
 
-
+/*!
+ * \brief Link a dialog structure
+ * \param dlg dialog
+ * \param n extra increments for the reference counter
+ */
 void link_dlg(struct dlg_cell *dlg, int n)
 {
 	struct dlg_entry *d_entry;
@@ -477,7 +489,12 @@ void link_dlg(struct dlg_cell *dlg, int n)
 }
 
 
-
+/*!
+ * \brief Unlink a dialog from the list without locking
+ * \see unref_dlg_unsafe
+ * \param d_entry unlinked entry
+ * \param dlg unlinked dialog
+ */
 inline void unlink_unsafe_dlg(struct dlg_entry *d_entry,
 		struct dlg_cell *dlg)
 {
@@ -496,6 +513,12 @@ inline void unlink_unsafe_dlg(struct dlg_entry *d_entry,
 }
 
 
+/*!
+ * \brief Refefence a dialog with locking
+ * \see ref_dlg_unsafe
+ * \param dlg dialog
+ * \param cnt increment for the reference counter
+ */
 void ref_dlg(struct dlg_cell *dlg, unsigned int cnt)
 {
 	struct dlg_entry *d_entry;
@@ -508,6 +531,12 @@ void ref_dlg(struct dlg_cell *dlg, unsigned int cnt)
 }
 
 
+/*!
+ * \brief Unreference a dialog with locking
+ * \see unref_dlg_unsafe
+ * \param dlg dialog
+ * \param cnt decrement for the reference counter
+ */
 void unref_dlg(struct dlg_cell *dlg, unsigned int cnt)
 {
 	struct dlg_entry *d_entry;
@@ -535,8 +564,21 @@ static inline void log_next_state_dlg(const int event, const struct dlg_cell *dl
 }
 
 
+/*!
+ * \brief Update a dialog state according a event and the old state
+ *
+ * This functions implement the main state machine that update a dialog
+ * state according a processed event and the current state. If necessary
+ * it will delete the processed dialog. The old and new state are also
+ * saved for reference.
+ * \param dlg updated dialog
+ * \param event current event
+ * \param old_state old dialog state
+ * \param new_state new dialog state
+ * \param unref set to 1 when the dialog was deleted, 0 otherwise
+ */
 void next_state_dlg(struct dlg_cell *dlg, int event,
-								int *old_state, int *new_state, int *unref)
+		int *old_state, int *new_state, int *unref)
 {
 	struct dlg_entry *d_entry;
 
diff --git a/modules_k/dialog/dlg_hash.h b/modules_k/dialog/dlg_hash.h
index 197f222..e717a2b 100644
--- a/modules_k/dialog/dlg_hash.h
+++ b/modules_k/dialog/dlg_hash.h
@@ -34,6 +34,12 @@
  *             CONFIRMED_NA due delayed "200 OK" (bogdan)
  */
 
+/*!
+ * \file
+ * \brief Functions and definitions related to dialog creation and searching
+ * \ingroup dialog
+ * Module: \ref dialog
+ */
 
 #ifndef _DIALOG_DLG_HASH_H_
 #define _DIALOG_DLG_HASH_H_
@@ -126,17 +132,37 @@ struct dlg_table
 	gen_lock_set_t     *locks;	/*!< lock table */
 };
 
+
 /*! global dialog table */
 extern struct dlg_table *d_table;
 /*! point to the current dialog */
 extern struct dlg_cell  *current_dlg_pointer;
 
+
+/*!
+ * \brief Set a dialog lock
+ * \param _table dialog table
+ * \param _entry locked entry
+ */
 #define dlg_lock(_table, _entry) \
 		lock_set_get( (_table)->locks, (_entry)->lock_idx);
+
+
+/*!
+ * \brief Release a dialog lock
+ * \param _table dialog table
+ * \param _entry locked entry
+ */
 #define dlg_unlock(_table, _entry) \
 		lock_set_release( (_table)->locks, (_entry)->lock_idx);
 
 
+/*!
+ * \brief Unlink a dialog from the list without locking
+ * \see unref_dlg_unsafe
+ * \param d_entry unlinked entry
+ * \param dlg unlinked dialog
+ */
 inline void unlink_unsafe_dlg(struct dlg_entry *d_entry, struct dlg_cell *dlg);
 
 
@@ -146,6 +172,12 @@ inline void unlink_unsafe_dlg(struct dlg_entry *d_entry, struct dlg_cell *dlg);
  */
 inline void destroy_dlg(struct dlg_cell *dlg);
 
+
+/*!
+ * \brief Reference a dialog without locking
+ * \param _dlg dialog
+ * \param _cnt increment for the reference counter
+ */
 #define ref_dlg_unsafe(_dlg,_cnt)     \
 	do { \
 		(_dlg)->ref += (_cnt); \
@@ -153,6 +185,12 @@ inline void destroy_dlg(struct dlg_cell *dlg);
 			(_dlg),(_cnt),(_dlg)->ref); \
 	}while(0)
 
+
+/*!
+ * \brief Unreference a dialog without locking
+ * \param _dlg dialog
+ * \param _cnt decrement for the reference counter
+ */
 #define unref_dlg_unsafe(_dlg,_cnt,_d_entry)   \
 	do { \
 		(_dlg)->ref -= (_cnt); \
@@ -252,12 +290,46 @@ struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id);
  */
 struct dlg_cell* get_dlg(str *callid, str *ftag, str *ttag, unsigned int *dir);
 
+
+/*!
+ * \brief Link a dialog structure
+ * \param dlg dialog
+ * \param n extra increments for the reference counter
+ */
 void link_dlg(struct dlg_cell *dlg, int n);
 
+
+/*!
+ * \brief Unreference a dialog with locking
+ * \see unref_dlg_unsafe
+ * \param dlg dialog
+ * \param cnt decrement for the reference counter
+ */
 void unref_dlg(struct dlg_cell *dlg, unsigned int cnt);
 
+
+/*!
+ * \brief Refefence a dialog with locking
+ * \see ref_dlg_unsafe
+ * \param dlg dialog
+ * \param cnt increment for the reference counter
+ */
 void ref_dlg(struct dlg_cell *dlg, unsigned int cnt);
 
+
+/*!
+ * \brief Update a dialog state according a event and the old state
+ *
+ * This functions implement the main state machine that update a dialog
+ * state according a processed event and the current state. If necessary
+ * it will delete the processed dialog. The old and new state are also
+ * saved for reference.
+ * \param dlg updated dialog
+ * \param event current event
+ * \param old_state old dialog state
+ * \param new_state new dialog state
+ * \param unref set to 1 when the dialog was deleted, 0 otherwise
+ */
 void next_state_dlg(struct dlg_cell *dlg, int event,
 		int *old_state, int *new_state, int *unref);