- per new dialog callback, called each time a new UAS (DLG_CB_UAS) or UAC
[sip-router] / modules / tm / t_hooks.h
1 /*
2  * $Id$
3  *
4  * Copyright (C) 2001-2003 FhG Fokus
5  *
6  * This file is part of ser, a free SIP server.
7  *
8  * ser 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  * For a license to use the ser software under conditions
14  * other than those described here, or to purchase support for this
15  * software, please contact iptel.org by e-mail at the following addresses:
16  *    info@iptel.org
17  *
18  * ser is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software
25  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26  *
27  * History:
28  * --------
29  * 2003-03-16 : backwards-compatibility callback names introduced (jiri)
30  * 2003-03-06 : old callbacks renamed, new one introduced (jiri)
31  * 2003-12-04 : global callbacks moved into transaction callbacks;
32  *              multiple events per callback added; single list per
33  *              transaction for all its callbacks (bogdan)
34  * 2007-03-14   added *_SENT callbacks (andrei)
35  * 2007-03-17   added TMCB_NEG_ACK_IN, TMCB_REQ_RETR_IN & 
36  *               TMCB_LOCAL_RESPONSE_IN (andrei)
37  * 2007-03-23   added TMCB_LOCAL_REQUEST_IN (andrei)
38  */
39
40
41 #ifndef _HOOKS_H
42 #define _HOOKS_H
43
44 #include "defs.h"
45
46 /* if defined support for ONSEND callbacks will be added and
47  * the tmcb_params structure will get some additional members */
48 /*
49 #define TMCB_ONSEND
50 */
51 #ifdef TMCB_ONSEND
52 #include "../../ip_addr.h" /* dest_info */
53 #endif
54
55 struct sip_msg;
56 struct cell;
57
58 #define TMCB_REQUEST_IN_N       0
59 #define TMCB_RESPONSE_IN_N      1
60 #define TMCB_E2EACK_IN_N        2
61 #define TMCB_REQUEST_FWDED_N    3
62 #define TMCB_RESPONSE_FWDED_N   4
63 #define TMCB_ON_FAILURE_RO_N    5
64 #define TMCB_ON_FAILURE_N       6
65 #define TMCB_RESPONSE_OUT_N     7
66 #define TMCB_LOCAL_COMPLETED_N  8
67 #define TMCB_LOCAL_RESPONSE_OUT_N 9
68 #define TMCB_ACK_NEG_IN_N       10
69 #define TMCB_REQ_RETR_IN_N      11
70 #define TMCB_LOCAL_RESPONSE_IN_N 12
71 #define TMCB_LOCAL_REQUEST_IN_N  13
72 #define TMCB_DLG_N              14
73 #ifdef TMCB_ONSEND
74 #define TMCB_REQUEST_SENT_N     15
75 #define TMCB_RESPONSE_SENT_N    16
76 #define TMCB_MAX_N              16
77 #else
78 #define TMCB_MAX_N              14
79 #endif
80
81 #define TMCB_REQUEST_IN       (1<<TMCB_REQUEST_IN_N)
82 #define TMCB_RESPONSE_IN      (1<<TMCB_RESPONSE_IN_N)
83 #define TMCB_E2EACK_IN        (1<<TMCB_E2EACK_IN_N)
84 #define TMCB_REQUEST_FWDED    (1<<TMCB_REQUEST_FWDED_N)
85 #define TMCB_RESPONSE_FWDED   (1<<TMCB_RESPONSE_FWDED_N)
86 #define TMCB_ON_FAILURE_RO    (1<<TMCB_ON_FAILURE_RO_N)
87 #define TMCB_ON_FAILURE       (1<<TMCB_ON_FAILURE_N)
88 #define TMCB_RESPONSE_OUT     (1<<TMCB_RESPONSE_OUT_N)
89 #define TMCB_LOCAL_COMPLETED  (1<<TMCB_LOCAL_COMPLETED_N)
90 #define TMCB_LOCAL_RESPONSE_OUT (1<<TMCB_LOCAL_RESPONSE_OUT_N)
91 #define TMCB_ACK_NEG_IN       (1<<TMCB_ACK_NEG_IN_N)
92 #define TMCB_REQ_RETR_IN      (1<<TMCB_REQ_RETR_IN_N)
93 #define TMCB_LOCAL_RESPONSE_IN (1<<TMCB_LOCAL_RESPONSE_IN_N)
94 #define TMCB_LOCAL_REQUEST_IN (1<<TMCB_LOCAL_REQUEST_IN_N)
95 #define TMCB_DLG              (1<<TMCB_DLG_N)
96 #ifdef TMCB_ONSEND
97 #define TMCB_REQUEST_SENT      (1<<TMCB_REQUEST_SENT_N)
98 #define TMCB_RESPONSE_SENT     (1<<TMCB_RESPONSE_SENT_N)
99 #endif
100 #define TMCB_MAX              ((1<<(TMCB_MAX_N+1))-1)
101
102
103 /*
104  *  Caution: most of the callbacks work with shmem-ized messages
105  *  which you can no more change (e.g., lumps are fixed). Most
106  *  reply-processing callbacks are also called from a mutex,
107  *  which may cause deadlock if you are not careful. Also, reply
108  *  callbacks may pass the value of FAKED_REPLY messages, which
109  *  is a non-dereferencable pointer indicating that no message
110  *  was received and a timer hit instead.
111  *
112  *  All callbacks excepting the TMCB_REQUEST_IN are associates to a
113  *  transaction. It means they will be run only when the event will hint
114  *  the transaction the callbacks were register for.
115  *  TMCB_REQUEST_IN is a global callback - it means it will be run for
116  *  all transactions.
117  *
118  *
119  *  Callback description:
120  *  ---------------------
121  *
122  * TMCB_REQUEST_IN -- a brand-new request was received and is
123  * about to establish transaction; it is not yet cloned and
124  * lives in pkg mem -- your last chance to mangle it before
125  * it gets shmem-ized (then, it's read-only); it's called from
126  * HASH_LOCK, so be careful. It is guaranteed not to be
127  * a retransmission. The transactional context is mostly
128  * incomplete -- this callback is called in very early stage
129  * before the message is shmem-ized (so that you can work
130  * with it).
131  * It's safe to install other TMCB callbacks from here.
132  * Note: this callback MUST be installed before forking
133  * (the req_in_tmcb_hl callback list does not live in shmem and has no access
134  * protection), i.e., at best from mod_init functions.
135  *
136  * Note: all the other callbacks MUST be installed before or immediately after
137  *  the transaction is created (they must not be installed from any place 
138  *  where the transaction callbacks can be run or added simultaneously with 
139  *  the add operation). Another safe way of installing them is to hold the
140  *  REPLY lock prior to adding a callback.
141  *  In general it's not safe to register callbacks from other TMCB callbacks,
142  *  unless the contrary is explicitly stated in the TMCB callback description.
143  *  For example a good place for installing them is from a TMCB_REQUEST_IN 
144  *  callback.
145  *
146  * TMCB_RESPONSE_IN -- a brand-new reply was received which matches
147  * an existing non-local transaction. It may or may not be a retransmission.
148  * No lock is held here (yet).
149  * It's unsafe to register other TMCB callbacks.
150  *
151  *  TMCB_RESPONSE_OUT -- a final reply was sent out (either local
152  *  or proxied) -- there is nothing more you can change from
153  *  the callback, it is good for accounting-like uses. No lock is held.
154  *  It's unsafe to registers other callbacks to the current transaction from
155  *   the TMCB_RESPONSE_OUT callback.
156  *  Known BUGS: it's called also for provisional replies for relayed replies.
157  *  For local replies it's called only for the final reply.
158  *    
159  *    Note: the message passed to callback may also have
160  *    value FAKED_REPLY (like other reply callbacks) which
161  *    indicates a pseudo_reply caused by a timer. Check for
162  *    this value before deferring -- you will cause a segfault
163  *    otherwise. Check for t->uas.request validity too if you
164  *    need it ... locally initiated UAC transactions set it to 0.
165  *
166  *    Also note, that reply callbacks are not called if a transaction
167  *    is dropped silently. That's the case when noisy_ctimer is
168  *    disabled (by default) and C-timer hits. The proxy server then
169  *    drops state silently, doesn't use callbacks and expects the
170  *    transaction to complete statelessly.
171  *
172  *  TMCB_ON_FAILURE_RO -- called on receipt of a reply or timer;
173  *  it means all branches completed with a failure; the callback
174  *  function MUST not change anything in the transaction (READONLY)
175  *  that's a chance for doing ACC or stuff like this
176  *
177  *  TMCB_ON_FAILURE -- called on receipt of a reply or timer;
178  *  it means all branches completed with a failure; that's
179  *  a chance for example to add new transaction branches.
180  *  WARNING: the REPLY lock is held.
181  *  It is safe to add more callbacks from here.
182  *
183  *  TMCB_RESPONSE_FWDED -- called when a reply is about to be
184  *  forwarded; it is called after a message is received but before
185  *  a message is sent out: it is called when the decision is
186  *  made to forward a reply; it is parametrized by pkg message
187  *  which caused the transaction to complete (which is not
188  *  necessarily the same which will be forwarded). As forwarding
189  *  has not been executed and may fail, there is no guarantee
190  *  a reply will be successfully sent out at this point of time.
191  *
192  *     Note: TMCB_ON_FAILURE and TMCB_REPLY_FWDED are
193  *     called from reply mutex which is used to deterministically
194  *     process multiple replies received in parallel. A failure
195  *     to set the mutex again or stay too long in the callback
196  *     may result in deadlock.
197  *
198  *     Note: the reply callbacks will not be evoked if "silent
199  *     C-timer hits". That's a feature to clean transactional
200  *     state from a proxy quickly -- transactions will then
201  *     complete statelessly. If you wish to disable this
202  *     feature, either set the global option "noisy_ctimer"
203  *     to 1, or set t->noisy_ctimer for selected transaction.
204  *
205  *  TMCB_E2EACK_IN -- called when an ACK belonging to a proxied
206  *  INVITE transaction completed with 200 arrived. Note that
207  *  because it can be only dialog-wise matched, only the first
208  *  transaction occurrence will be matched with spirals. If
209  *  record-routing is not enabled, you will never receive the
210  *  ACK and the callback will be never triggered. In general it's called only
211  *   for the first ACK but it can be also called multiple times 
212  *   quasi-simultaneously if multiple ACK copies arrive in parallel or if
213  *   ACKs with different (never seen before) to-tags are received.
214  *
215  *  TMCB_REQUEST_FWDED -- request is being forwarded out. It is
216  *  called before a message is forwarded, when the corresponding branch
217  *   is created (it's called for each branch) and it is your last
218  *  chance to change its shape. It can also be called from the failure
219  *   router (via t_relay/t_forward_nonack) and in this case the REPLY lock 
220  *   will be held.
221  *  It's unsafe to register other TMCB callbacks (except if it it's called
222  * from the failure route).
223  *
224  *  TMCB_LOCAL_COMPLETED -- final reply for localy initiated
225  *  transaction arrived. Message may be FAKED_REPLY. Can be called multiple
226  *  times, no lock is held.
227  *  It's unsafe to register other TMCB callbacks (unless this is protected
228  *  by the reply lock).
229  *
230  *  TMCB_LOCAL_REPONSE_OUT -- provisional reply for localy initiated 
231  *  transaction. The message may be a FAKED_REPLY and the callback might be 
232  *  called multiple time quasi-simultaneously. No lock is held.
233  *  It's unsafe to register other TMCB callbacks.
234  *
235  *  TMCB_NEG_ACK_IN -- an ACK to a negative reply was received, thus ending
236  *  the transaction (this happens only when the final reply sent by tm is 
237  *  negative). The callback might be called simultaneously. No lock is held.
238  *
239  *  TMCB_REQ_RETR_IN -- a retransmitted request was received. This callback
240  *   might be called simultaneously. No lock is held.
241  *
242  * TMCB_LOCAL_RESPONSE_IN -- a brand-new reply was received which matches
243  * an existing local transaction (like TMCB_RESPONSE_IN but for local 
244  * transactions). It may or may not be a retransmission.
245  * No lock is held here (yet). It's unsafe to register other TMCB callbacks.
246  *
247  * TMCB_LOCAL_REQUEST_IN -- like TMCB_REQUEST_IN but for locally generated 
248  * request (e.g. via fifo/rpc):  a brand-new local request was 
249  * received/generated and a transaction for it is about to be created.
250  * It's called from HASH_LOCK, so be careful. It is guaranteed not to be
251  * a retransmission. The transactional context is mostly
252  * incomplete -- this callback is called in very early stage
253  * before the message is shmem-ized (so that you can work
254  * with it).
255  * It's safe to install other TMCB callbacks from here.
256  * Note: this callback MUST be installed before forking
257  * (the local_req_in_tmcb_hl callback list does not live in shmem and has no 
258  * access protection), i.e., at best from mod_init functions.
259  *
260  *
261  *  All of the following callbacks are called immediately after or before 
262  *  sending a message. All of them are read-only (no change can be made to
263  * the message). These callbacks use the t_rbuf, send_buf, dst, is_retr
264  *  and the code members of the tmcb_params structure.
265  *  For a request code is <=0. code values can be TYPE_LOCAL_ACK for an ACK 
266  *  generated by ser, TYPE_LOCAL_CANCEL for a CANCEL generated by ser 
267  *  and TYPE_REQUEST for all the other requests or requests generated via 
268  *  t_uac.
269  *   For a reply the code is the response status (which is always >0, e.g. 200,
270  *   408, a.s.o).
271  *  Note: - these callbacks can be used only if TMCB_ONSEND is defined.
272  *        - the callbacks will be called sometimes with the REPLY lock held
273  *          and sometimes without it, so trying to acquire the REPLY lock
274  *          from these callbacks could lead to deadlocks (avoid it unless
275  *           you really know what you're doing).
276  *
277  *  TMCB_REQUEST_SENT (present only if TMCB_ONSEND is defined) -- called 
278  *  each time a request was sent (even for retransmissions), it includes 
279  *  local and forwarded request, ser generated CANCELs and ACKs. The 
280  *  tmcb_params structure will have the t_rbuf, dst, send_buf and is_retr
281  *  members  filled.
282  *  This callback is "read-only", the message was already sent and no changes
283  *  are allowed.
284  *  Note: send_buf can be different from t_rbuf->buffer for ACKs (in this
285  *   case t_rbuf->buf will contain the last request sent on the branch and
286  *   its destination). The same goes for t_rbuf->dst and tmcb->dst for local 
287  *   transactions ACKs to 2xxs.
288  *
289  *  TMCB_RESPONSE_SENT  (present only if TMCB_ONSEND is defined) -- called 
290  *  each time a response was sent (even for retransmissions). The tmcb_params
291  *   structure will have t_rbuf set to the reply retransmission buffer and
292  *   send_buf set to the data sent (in this case it will always be the same 
293  *   with t_rbuf->buf). is_retr will also be set if the reply is retransmitted
294  *   by ser.
295  *  This callback is "read-only", the message was already sent and no changes
296  *  are allowed.
297  *
298
299         the callback's param MUST be in shared memory and will
300         NOT be freed by TM; you must do it yourself from the
301         callback function if necessary.
302 */
303
304
305 /* pack structure with all params passed to callback function */
306 struct tmcb_params {
307         struct sip_msg* req;
308         struct sip_msg* rpl;
309         void **param;
310 #ifdef TMCB_ONSEND
311         struct retr_buf* t_rbuf; /* transaction retr. buf., all the information
312                                                                  regarding destination, data that is/was
313                                                                  actually sent on the net, branch a.s.o is
314                                                                  inside */
315         struct dest_info* dst; /* destination */
316         str send_buf; /* what was/will be sent on the net, used for ACKs
317                                         (which don't have a retr_buf). */
318         short is_retr; /* set if this is a _ser_ retransmission (but not if
319                                          if it's a "forwarded" retr., like a retr. 200 Ok for 
320                                          example) */
321         unsigned short branch;
322         /* could also be: send_buf, dst, branch */
323 #endif
324         int code;
325 };
326
327 /* callback function prototype */
328 typedef void (transaction_cb) (struct cell* t, int type, struct tmcb_params*);
329 /* register callback function prototype */
330 typedef int (*register_tmcb_f)(struct sip_msg* p_msg, struct cell *t,
331                 int cb_types, transaction_cb f, void *param);
332
333
334 struct tm_callback {
335         int id;                      /* id of this callback - useless */
336         int types;                   /* types of events that trigger the callback*/
337         transaction_cb* callback;    /* callback function */
338         void *param;                 /* param to be passed to callback function */
339         struct tm_callback* next;
340 };
341
342 struct tmcb_head_list {
343         struct tm_callback *first;
344         int reg_types;
345 };
346
347
348 extern struct tmcb_head_list*  req_in_tmcb_hl;
349 extern struct tmcb_head_list*  local_req_in_tmcb_hl;
350
351
352 #define has_tran_tmcbs(_T_, _types_) \
353         ( ((_T_)->tmcb_hl.reg_types)|(_types_) )
354 #define has_reqin_tmcbs() \
355         ( req_in_tmcb_hl->first!=0 )
356 #define has_local_reqin_tmcbs() \
357         ( local_req_in_tmcb_hl->first!=0 )
358
359
360 int init_tmcb_lists();
361
362 void destroy_tmcb_lists();
363
364
365 /* register a callback for several types of events */
366 int register_tmcb( struct sip_msg* p_msg, struct cell *t, int types,
367                                                                                         transaction_cb f, void *param );
368
369 /* inserts a callback into the a callback list */
370 int insert_tmcb(struct tmcb_head_list *cb_list, int types,
371                                                                         transaction_cb f, void *param );
372
373 /* run all transaction callbacks for an event type */
374 void run_trans_callbacks( int type , struct cell *trans,
375                                                 struct sip_msg *req, struct sip_msg *rpl, int code );
376 /* helper function */
377 void run_trans_callbacks_internal(struct tmcb_head_list* cb_lst, int type,
378                                                                         struct cell *trans, 
379                                                                         struct tmcb_params *params);
380 /* run all REQUEST_IN callbacks */
381 void run_reqin_callbacks( struct cell *trans, struct sip_msg *req, int code );
382 void run_local_reqin_callbacks( struct cell *trans, struct sip_msg *req, 
383                 int code );
384
385 #ifdef TMCB_ONSEND
386 void run_onsend_callbacks(int type, struct retr_buf* rbuf, int retr);
387 void run_onsend_callbacks2(int type , struct retr_buf* rbuf, char* buf,
388                                                         int buf_len, struct dest_info* dst, int code);
389 #endif
390
391 #endif