a bunch of small refactorings in the dialog module
[sip-router] / modules_k / dialog / dlg_handlers.h
1 /*
2  * $Id$
3  *
4  * Copyright (C) 2006 Voice System SRL
5  *
6  * This file is part of Kamailio, a free SIP server.
7  *
8  * Kamailio is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version
12  *
13  * Kamailio is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License 
19  * along with this program; if not, write to the Free Software 
20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21  *
22  * History:
23  * --------
24  * 2006-04-14  initial version (bogdan)
25  * 2007-03-06  syncronized state machine added for dialog state. New tranzition
26  *             design based on events; removed num_1xx and num_2xx (bogdan)
27  */
28
29
30 /*!
31  * \file
32  * \brief Functions related to dialog handling
33  * \ingroup dialog
34  * Module: \ref dialog
35  */
36
37 #ifndef _DIALOG_DLG_HANDLERS_H_
38 #define _DIALOG_DLG_HANDLERS_H_
39
40 #include "../../parser/msg_parser.h"
41 #include "../../str.h"
42 #include "../../pvar.h"
43 #include "../../modules/tm/t_hooks.h"
44 #include "dlg_timer.h"
45
46 #define MAX_DLG_RR_PARAM_NAME 32
47
48 /* values for the sequential match mode */
49 #define SEQ_MATCH_STRICT_ID  0
50 #define SEQ_MATCH_FALLBACK   1
51 #define SEQ_MATCH_NO_ID      2
52
53
54 /*!
55  * \brief Initialize the dialog handlers
56  * \param rr_param_p added record-route parameter
57  * \param dlg_flag_p dialog flag
58  * \param timeout_avp_p AVP for timeout setting
59  * \param default_timeout_p default timeout
60  * \param seq_match_mode_p matching mode
61  */
62 void init_dlg_handlers(char *rr_param, int dlg_flag,
63                 pv_spec_t *timeout_avp, int default_timeout,
64                 int seq_match_mode);
65
66
67 /*!
68  * \brief Shutdown operation of the module
69  */
70 void destroy_dlg_handlers(void);
71
72
73 /*!
74  * \brief Parse SIP message and populate leg informations
75  *
76  * Parse SIP message and populate leg informations. 
77  * \param dlg the dialog to add cseq, contact & record_route
78  * \param msg sip message
79  * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
80  * \return 0 on success, -1 on failure
81  * \note for a request: get record route in normal order, for a reply get
82  * in reverse order, skipping the ones from the request and the proxies' own
83  */
84 int populate_leg_info( struct dlg_cell *dlg, struct sip_msg *msg,
85         struct cell* t, unsigned int leg, str *tag);
86
87
88 /*!
89  * \brief Function that is registered as TM callback and called on requests
90  * \param t transaction, used to created the dialog
91  * \param type type of the entered callback
92  * \param param saved dialog structure in the callback
93  */
94 void dlg_onreq(struct cell* t, int type, struct tmcb_params *param);
95
96
97 /*!
98  * \brief Function that is registered as RR callback for dialog tracking
99  * 
100  * Function that is registered as RR callback for dialog tracking. It
101  * sets the appropriate events after the SIP method and run the state
102  * machine to update the dialog state. It updates then the saved
103  * dialogs and also the statistics.
104  * \param req SIP request
105  * \param route_params record-route parameter
106  * \param param unused
107  */
108 void dlg_onroute(struct sip_msg* req, str *rr_param, void *param);
109
110
111 /*!
112  * \brief Timer function that removes expired dialogs, run timeout route
113  * \param tl dialog timer list
114  */
115 void dlg_ontimeout( struct dlg_tl *tl);
116
117
118 /*!
119  * \brief Create a new dialog from a sip message
120  *
121  * Create a new dialog from a SIP message, register a callback
122  * to keep track of the dialog with help of the tm module.
123  * This function is either called from the request callback, or
124  * from the dlg_manage function in the configuration script.
125  * \see dlg_onreq
126  * \see w_dlg_manage
127  * \param msg SIP message
128  * \param t transaction
129  * \return 0 on success, -1 on failure
130  */ 
131 int dlg_new_dialog(struct sip_msg *msg, struct cell *t);
132
133
134 /*!
135  * \brief Function that returns the dialog lifetime as pseudo-variable
136  * \param msg SIP message
137  * \param param pseudo-variable parameter
138  * \param res pseudo-variable result
139  * \return 0 on success, -1 on failure
140  */
141 int pv_get_dlg_lifetime(struct sip_msg *msg, pv_param_t *param,
142                 pv_value_t *res);
143
144
145 /*!
146  * \brief Function that returns the dialog state as pseudo-variable
147  * \param msg SIP message
148  * \param param pseudo-variable parameter
149  * \param res pseudo-variable result
150  * \return 0 on success, -1 on failure
151  */
152 int pv_get_dlg_status(struct sip_msg *msg, pv_param_t *param,
153                 pv_value_t *res);
154
155
156 /*!
157  * \brief Dummy callback just to keep the compiler happy
158  * \param t unused
159  * \param type unused
160  * \param param unused
161  */
162 void dlg_tmcb_dummy(struct cell* t, int type, struct tmcb_params *param);
163
164 #endif