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

Module: sip-router Branch: master Commit: f666a4e53f79843f82b867c5dd4ce64e100feb82 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=f666a4e… Author: Henning Westerholt &lt;henning.westerholt(a)1und1.de&gt; Committer: Henning Westerholt &lt;henning.westerholt(a)1und1.de&gt; 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);