1 /*
2  * Copyright (C) 2001-2003 FhG Fokus
3  *
4  * This file is part of Kamailio, a free SIP server.
5  *
6  * Kamailio is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version
10  *
11  * Kamailio is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
19  *
20  */
21 
22 
23 #ifndef _HOOKS_H
24 #define _HOOKS_H
25 
26 /* TMCB_ONSEND used to enable certain callback-related features when
27  * ONSEND was set, these days it's always enabled. For compatibility
28  * reasons with modules that check ONSEND, continue to set it
29  * unconditionally*/
30 #define TMCB_ONSEND
31 #include "../../core/ip_addr.h" /* dest_info */
32 
33 struct sip_msg;
34 struct cell;
35 
36 #define TMCB_REQUEST_IN_N       0
37 #define TMCB_RESPONSE_IN_N      1
38 #define TMCB_E2EACK_IN_N        2
39 #define TMCB_REQUEST_PENDING_N  3
40 #define TMCB_REQUEST_FWDED_N    4
41 #define TMCB_RESPONSE_FWDED_N   5
42 #define TMCB_ON_FAILURE_RO_N    6
43 #define TMCB_ON_FAILURE_N       7
44 #define TMCB_REQUEST_OUT_N      8
45 #define TMCB_RESPONSE_OUT_N     9
46 #define TMCB_LOCAL_COMPLETED_N  10
47 #define TMCB_LOCAL_RESPONSE_OUT_N 11
48 #define TMCB_ACK_NEG_IN_N       12
49 #define TMCB_REQ_RETR_IN_N      13
50 #define TMCB_LOCAL_RESPONSE_IN_N 14
51 #define TMCB_LOCAL_REQUEST_IN_N  15
52 #define TMCB_DLG_N              16
53 #define TMCB_DESTROY_N          17  /* called on transaction destroy */
54 #define TMCB_E2ECANCEL_IN_N     18
55 #define TMCB_E2EACK_RETR_IN_N   19
56 #define TMCB_RESPONSE_READY_N	20
57 #define TMCB_DONT_ACK_N         21 /* TM shoudn't ACK a local UAC  */
58 #define TMCB_REQUEST_SENT_N     22
59 #define TMCB_RESPONSE_SENT_N    23
60 #define TMCB_ON_BRANCH_FAILURE_RO_N 24
61 #define TMCB_ON_BRANCH_FAILURE_N 25
62 #define TMCB_MAX_N              25
63 
64 
65 #define TMCB_REQUEST_IN       (1<<TMCB_REQUEST_IN_N)
66 #define TMCB_RESPONSE_IN      (1<<TMCB_RESPONSE_IN_N)
67 #define TMCB_E2EACK_IN        (1<<TMCB_E2EACK_IN_N)
68 #define TMCB_REQUEST_PENDING  (1<<TMCB_REQUEST_PENDING_N)
69 #define TMCB_REQUEST_FWDED    (1<<TMCB_REQUEST_FWDED_N)
70 #define TMCB_RESPONSE_FWDED   (1<<TMCB_RESPONSE_FWDED_N)
71 #define TMCB_ON_FAILURE_RO    (1<<TMCB_ON_FAILURE_RO_N)
72 #define TMCB_ON_FAILURE       (1<<TMCB_ON_FAILURE_N)
73 #define TMCB_REQUEST_OUT      (1<<TMCB_REQUEST_OUT_N)
74 #define TMCB_RESPONSE_OUT     (1<<TMCB_RESPONSE_OUT_N)
75 #define TMCB_LOCAL_COMPLETED  (1<<TMCB_LOCAL_COMPLETED_N)
76 #define TMCB_LOCAL_RESPONSE_OUT (1<<TMCB_LOCAL_RESPONSE_OUT_N)
77 #define TMCB_ACK_NEG_IN       (1<<TMCB_ACK_NEG_IN_N)
78 #define TMCB_REQ_RETR_IN      (1<<TMCB_REQ_RETR_IN_N)
79 #define TMCB_LOCAL_RESPONSE_IN (1<<TMCB_LOCAL_RESPONSE_IN_N)
80 #define TMCB_LOCAL_REQUEST_IN (1<<TMCB_LOCAL_REQUEST_IN_N)
81 #define TMCB_DLG              (1<<TMCB_DLG_N)
82 #define TMCB_DESTROY          (1<<TMCB_DESTROY_N)
83 #define TMCB_E2ECANCEL_IN     (1<<TMCB_E2ECANCEL_IN_N)
84 #define TMCB_E2EACK_RETR_IN   (1<<TMCB_E2EACK_RETR_IN_N)
85 #define TMCB_RESPONSE_READY   (1<<TMCB_RESPONSE_READY_N)
86 #define TMCB_DONT_ACK         (1<<TMCB_DONT_ACK_N)
87 #define TMCB_REQUEST_SENT      (1<<TMCB_REQUEST_SENT_N)
88 #define TMCB_RESPONSE_SENT     (1<<TMCB_RESPONSE_SENT_N)
89 #define TMCB_ON_BRANCH_FAILURE (1<<TMCB_ON_BRANCH_FAILURE_N)
90 #define TMCB_ON_BRANCH_FAILURE_RO (1<<TMCB_ON_BRANCH_FAILURE_RO_N)
91 #define TMCB_MAX              ((1<<(TMCB_MAX_N+1))-1)
92 
93 
94 /*
95  *  Caution: most of the callbacks work with shmem-ized messages
96  *  which you can no more change (e.g., lumps are fixed). Most
97  *  reply-processing callbacks are also called from a mutex,
98  *  which may cause deadlock if you are not careful. Also, reply
99  *  callbacks may pass the value of FAKED_REPLY messages, which
100  *  is a non-dereferencable pointer indicating that no message
101  *  was received and a timer hit instead.
102  *
103  *  All callbacks excepting the TMCB_REQUEST_IN are associates to a
104  *  transaction. It means they will be run only when the event will hint
105  *  the transaction the callbacks were register for.
106  *  TMCB_REQUEST_IN is a global callback - it means it will be run for
107  *  all transactions.
108  *
109  *
110  *  Callback description:
111  *  ---------------------
112  *
113  * TMCB_REQUEST_IN -- a brand-new request was received and is
114  * about to establish transaction; it is not yet cloned and
115  * lives in pkg mem -- your last chance to mangle it before
116  * it gets shmem-ized (then, it's read-only); it's called from
117  * HASH_LOCK, so be careful. It is guaranteed not to be
118  * a retransmission. The transactional context is mostly
119  * incomplete -- this callback is called in very early stage
120  * before the message is shmem-ized (so that you can work
121  * with it).
122  * Note: this callback MUST be installed before forking
123  * (the req_in_tmcb_hl callback list does not live in shmem and has no access
124  * protection), i.e., at best from mod_init functions.
125  *
126  * Note: All the other callbacks can be safely installed when the
127  * transaction already exists, it does not need to be locked.
128  *
129  * TMCB_RESPONSE_IN -- a brand-new reply was received which matches
130  * an existing non-local transaction. It may or may not be a retransmission.
131  * No lock is held here (yet).
132  * Note: for an invite transaction this callback will also catch the reply
133  *  to local cancels (e.g. branch canceled due to fr_inv_timeout). To
134  *  distinguish between the two, one would need to look at the method in
135  *  Cseq (look at t_reply.c:1630 (reply_received()) for an example).
136  *
137  *  TMCB_RESPONSE_OUT -- a final or provisional reply was sent out
138  *  successfully (either a local reply  or a proxied one).
139  *  For final replies is called only for the first one (it's not called
140  *  for retransmissions).
141  *  For non-local replies (proxied) is called also for provisional responses
142  *  (NOTE: this might change and in the future it might be called only
143  *  for final replies --andrei).
144  *  For local replies is called _only_ for the final reply.
145  *  There is nothing more you can change from the callback, it is good for
146  *  accounting-like uses. No lock is held.
147  *  Known oddities: it's called for provisional replies for relayed replies,
148  *  but not for local responses (see NOTE above).
149  *  Note: if the send fails or via cannot be resolved, this callback is
150  *  _not_ called.
151  *  Note: local reply means locally generated reply (via t_reply() & friends)
152  *  and not local transaction.
153  *
154  *    Note: the message passed to the callback may also have
155  *    value FAKED_REPLY (like other reply callbacks) which
156  *    indicates a local reply caused by a timer, calling t_reply() a.s.o.
157 *     Check for this value before deferring -- you will cause a segfault
158  *    otherwise. Check for t->uas.request validity too if you
159  *    need it ... locally initiated UAC transactions set it to 0.
160  *
161  *    Also note, that reply callbacks are not called if a transaction
162  *    is dropped silently. That's the case when noisy_ctimer is
163  *    disabled (by default) and C-timer hits. The proxy server then
164  *    drops state silently, doesn't use callbacks and expects the
165  *    transaction to complete statelessly.
166  *
167  *  TMCB_ON_FAILURE_RO -- called on receipt of a reply or timer;
168  *  it means all branches completed with a failure; the callback
169  *  function MUST not change anything in the transaction (READONLY)
170  *  that's a chance for doing ACC or stuff like this
171  *
172  *  TMCB_ON_FAILURE -- called on receipt of a reply or timer;
173  *  it means all branches completed with a failure; that's
174  *  a chance for example to add new transaction branches.
175  *  WARNING: the REPLY lock is held.
176  *  It is safe to add more callbacks from here.
177  *
178  *  TMCB_RESPONSE_FWDED -- called when a reply is about to be
179  *  forwarded; it is called after a message is received but before
180  *  a message is sent out: it is called when the decision is
181  *  made to forward a reply; it is parametrized by pkg message
182  *  which caused the transaction to complete (which is not
183  *  necessarily the same which will be forwarded). As forwarding
184  *  has not been executed and may fail, there is no guarantee
185  *  a reply will be successfully sent out at this point of time.
186  *
187  *     Note: TMCB_ON_FAILURE and TMCB_REPLY_FWDED are
188  *     called from reply mutex which is used to deterministically
189  *     process multiple replies received in parallel. A failure
190  *     to set the mutex again or stay too long in the callback
191  *     may result in deadlock.
192  *
193  *     Note: the reply callbacks will not be evoked if "silent
194  *     C-timer hits". That's a feature to clean transactional
195  *     state from a proxy quickly -- transactions will then
196  *     complete statelessly. If you wish to disable this
197  *     feature, either set the global option "noisy_ctimer"
198  *     to 1, or set t->noisy_ctimer for selected transaction.
199  *
200  *  TMCB_E2EACK_IN -- called when an ACK belonging to a proxied
201  *  INVITE transaction completed with 200 arrived. Note that
202  *  because it can be only dialog-wise matched, only the first
203  *  transaction occurrence will be matched with spirals. If
204  *  record-routing is not enabled, you will never receive the
205  *  ACK and the callback will be never triggered. In general it's called only
206  *   for the first ACK but it can be also called multiple times
207  *   quasi-simultaneously if multiple ACK copies arrive in parallel or if
208  *   ACKs with different (never seen before) to-tags are received.
209  *
210  *   TMCB_E2EACK_RETR_IN -- like TMCB_E2EACK_IN, but matches retransmissions
211  *   and it's called for every retransmission (but not for the "first" ACK).
212  *
213  *  TMCB_E2ECANCEL_IN -- called when a CANCEL for the INVITE transaction
214  *  for which the callback was registered arrives.
215  *   The transaction parameter will point to the invite transaction (and
216  *   not the cancel) and the request parameter to the CANCEL sip msg.
217  *   Note: the callback should be registered for an INVITE transaction.
218  *
219  *  TMCB_REQUEST_FWDED -- request is being forwarded out. It is
220  *  called before a message is forwarded, when the corresponding branch
221  *   is created (it's called for each branch) and it is your last
222  *  chance to change its shape. It can also be called from the failure
223  *   router (via t_relay/t_forward_nonack) and in this case the REPLY lock
224  *   will be held.
225  *
226  *  TMCB_REQUEST_OUT -- request was sent out successfully.
227  *  There is nothing more you can change from the callback, it is good for
228  *  accounting-like uses.
229  *  Note: if the send fails or via cannot be resolved, this callback is
230  *  _not_ called.
231  *
232  *  TMCB_LOCAL_COMPLETED -- final reply for localy initiated
233  *  transaction arrived. Message may be FAKED_REPLY. Can be called multiple
234  *  times, no lock is held.
235  *
236  *  TMCB_LOCAL_RESPONSE_OUT -- provisional reply for localy initiated
237  *  transaction. The message may be a FAKED_REPLY and the callback might be
238  *  called multiple time quasi-simultaneously. No lock is held.
239  *  Note: depends on tm.pass_provisional_replies.
240  *  Note: the name is very unfortunate and it will probably be changed
241  *   (e.g. TMCB_LOCAL_PROVISIONAL).
242  *
243  *  TMCB_NEG_ACK_IN -- an ACK to a negative reply was received, thus ending
244  *  the transaction (this happens only when the final reply sent by tm is
245  *  negative). The callback might be called simultaneously. No lock is held.
246  *
247  *  TMCB_REQ_RETR_IN -- a retransmitted request was received. This callback
248  *   might be called simultaneously. No lock is held.
249  *
250  * TMCB_LOCAL_RESPONSE_IN -- a brand-new reply was received which matches
251  * an existing local transaction (like TMCB_RESPONSE_IN but for local
252  * transactions). It may or may not be a retransmission.
253  *
254  * TMCB_LOCAL_REQUEST_IN -- like TMCB_REQUEST_IN but for locally generated
255  * request (e.g. via fifo/rpc):  a brand-new local request was
256  * received/generated and a transaction for it is about to be created.
257  * It's called from HASH_LOCK, so be careful. It is guaranteed not to be
258  * a retransmission. The transactional context is mostly
259  * incomplete -- this callback is called in very early stage
260  * before the message is shmem-ized (so that you can work
261  * with it).
262  * It's safe to install other TMCB callbacks from here.
263  * Note: this callback MUST be installed before forking
264  * (the local_req_in_tmcb_hl callback list does not live in shmem and has no
265  * access protection), i.e., at best from mod_init functions.
266  *
267  *
268  *  All of the following callbacks are called immediately after or before
269  *  sending a message. All of them are read-only (no change can be made to
270  * the message). These callbacks use the t_rbuf, send_buf, dst, is_retr
271  *  and the code members of the tmcb_params structure.
272  *  For a request code is <=0. code values can be TYPE_LOCAL_ACK for an ACK
273  *  generated by ser, TYPE_LOCAL_CANCEL for a CANCEL generated by ser
274  *  and TYPE_REQUEST for all the other requests or requests generated via
275  *  t_uac.
276  *   For a reply the code is the response status (which is always >0, e.g. 200,
277  *   408, a.s.o).
278  *        - the callbacks will be called sometimes with the REPLY lock held
279  *          and sometimes without it, so trying to acquire the REPLY lock
280  *          from these callbacks could lead to deadlocks (avoid it unless
281  *           you really know what you're doing).
282  *
283  *  TMCB_REQUEST_SENT -- called each time a request was sent (even for
284  *  retransmissions), it includes local and forwarded request, ser generated
285  *  CANCELs and ACKs. The tmcb_params structure will have the t_rbuf, dst,
286  *  send_buf and is_retr members filled.
287  *  This callback is "read-only", the message was already sent and no changes
288  *  are allowed.
289  *  Note: send_buf can be different from t_rbuf->buffer for ACKs (in this
290  *   case t_rbuf->buf will contain the last request sent on the branch and
291  *   its destination). The same goes for t_rbuf->dst and tmcb->dst for local
292  *   transactions ACKs to 2xxs.
293  *
294  *  TMCB_RESPONSE_SENT -- called each time a response was sent (even for
295  *  retransmissions). The tmcb_params structure will have t_rbuf set to the
296  *  reply retransmission buffer and send_buf set to the data sent (in this case
297  *  it will always be the same with t_rbuf->buf). is_retr will also be set if
298  *  the reply is retransmitted
299  *   by ser.
300  *  This callback is "read-only", the message was already sent and no changes
301  *  are allowed.
302  *
303  *  TMCB_DESTROY -- called when the transaction is destroyed. Everything but
304  *  the cell* parameter (t) and the tmcb are set to 0. Only the param is
305  *  is filled inside TMCB. For dialogs callbacks t is also 0.
306  *
307  * TMCB_RESPONSE_READY -- a reply is ready to be sent out. Callback is
308  *  is executed just before writing the reply content to network.
309  *
310  * TMCB_DONT_ACK (requires AS support) -- for localy generated INVITEs, TM
311  * automatically generates an ACK for the received 2xx replies. But, if this
312  * flag is passed to TM when creating the initial UAC request, this won't
313  * happen anymore: the ACK generation must be triggered from outside, using
314  * TM's interface.
315  * While this isn't exactly a callback type, it is used as part of the flags
316  * mask when registering callbacks.
317 
318 	the callback's param MUST be in shared memory and will
319 	NOT be freed by TM; you must do it yourself from the
320 	callback function if necessary (for example register it also for
321 	TMCB_DESTROY and when called with TMCB_DESTROY just free the param
322 	).
323 */
324 
325 #define TMCB_NONE_F 0
326 #define TMCB_RETR_F 1
327 #define TMCB_LOCAL_F 2
328 
329 /* pack structure with all params passed to callback function */
330 struct tmcb_params {
331 	struct sip_msg* req;
332 	struct sip_msg* rpl;
333 	void **param;
334 	int code;
335 	unsigned short flags;  /* set to a combination of:
336 							* TMCB_RETR_F if this is a _ser_ retransmission
337 							* (but not if if it's a "forwarded" retr., like a
338 							* retr. 200 Ok for example)
339 							* TMCB_LOCAL_F if this is a local generated message
340 							* (and not forwarded) */
341 	unsigned short branch;
342 	/* could also be: send_buf, dst, branch */
343 	struct retr_buf* t_rbuf;   /* transaction retr. buf., all the information
344 								* regarding destination, data that is/was
345 								* actually sent on the net, branch a.s.o is
346 								* inside */
347 	struct dest_info* dst; /* destination */
348 	str send_buf; /* what was/will be sent on the net, used for ACKs
349 					(which don't have a retr_buf). */
350 };
351 
352 #define INIT_TMCB_PARAMS(tmcb, request, reply, r_code)\
353 do{\
354 	memset(&(tmcb), 0, sizeof((tmcb))); \
355 	(tmcb).req=(request); (tmcb).rpl=(reply);  \
356 	(tmcb).code=(r_code); \
357 }while(0)
358 
359 #define INIT_TMCB_ONSEND_PARAMS(tmcb, req, repl, rbuf, dest, buf, buf_len, \
360 								onsend_flags, t_branch, code) \
361 do{ \
362 	INIT_TMCB_PARAMS(tmcb, req, repl, code); \
363 	tmcb.t_rbuf=(rbuf); tmcb.dst=(dest); \
364 	tmcb.send_buf.s=(buf); tmcb.send_buf.len=(buf_len); \
365 	tmcb.flags=(onsend_flags); tmcb.branch=(t_branch); \
366 }while(0)
367 
368 /* callback function prototype */
369 typedef void (transaction_cb) (struct cell* t, int type, struct tmcb_params*);
370 /*! \brief function to release the callback param */
371 typedef void (release_tmcb_param) (void* param);
372 /* register callback function prototype */
373 typedef int (*register_tmcb_f)(struct sip_msg* p_msg, struct cell *t,
374 			int cb_types, transaction_cb f, void *param,
375 			release_tmcb_param func);
376 
377 
378 struct tm_callback {
379 	int id;                      /* id of this callback - useless */
380 	int types;                   /* types of events that trigger the callback*/
381 	transaction_cb* callback;    /* callback function */
382 	void *param;                 /* param to be passed to callback function */
383 	release_tmcb_param* release; /**< Function to release the callback param
384 									* when the callback is deleted */
385 	struct tm_callback* next;
386 };
387 
388 struct tmcb_head_list {
389 	struct tm_callback volatile *first;
390 	int reg_types;
391 };
392 
393 
394 extern struct tmcb_head_list*  req_in_tmcb_hl;
395 extern struct tmcb_head_list*  local_req_in_tmcb_hl;
396 
397 void set_early_tmcb_list(struct sip_msg *msg,
398 		struct cell *t);
399 
400 #define has_tran_tmcbs(_T_, _types_) \
401 	( ((_T_)->tmcb_hl.reg_types)&(_types_) )
402 #define has_reqin_tmcbs() \
403 	( req_in_tmcb_hl->first!=0 )
404 #define has_local_reqin_tmcbs() \
405 	( local_req_in_tmcb_hl->first!=0 )
406 
407 
408 int init_tmcb_lists(void);
409 
410 void destroy_tmcb_lists(void);
411 
412 
413 /* register a callback for several types of events */
414 int register_tmcb( struct sip_msg* p_msg, struct cell *t, int types,
415 			transaction_cb f, void *param, release_tmcb_param rel_func);
416 
417 /* inserts a callback into the a callback list */
418 int insert_tmcb(struct tmcb_head_list *cb_list, int types,
419 				transaction_cb f, void *param,
420 				release_tmcb_param rel_func);
421 
422 /* run all transaction callbacks for an event type */
423 void run_trans_callbacks( int type , struct cell *trans,
424 						struct sip_msg *req, struct sip_msg *rpl, int code );
425 /* helper function */
426 void run_trans_callbacks_internal(struct tmcb_head_list* cb_lst, int type,
427 									struct cell *trans,
428 									struct tmcb_params *params);
429 /* run all REQUEST_IN callbacks */
430 void run_reqin_callbacks( struct cell *trans, struct sip_msg *req, int code );
431 void run_local_reqin_callbacks( struct cell *trans, struct sip_msg *req,
432 		int code );
433 
434 /* like run_trans_callbacks but provide outgoing buffer (i.e., the
435  * processed message) to callback */
436 void run_trans_callbacks_with_buf(int type, struct retr_buf* rbuf,
437 		struct sip_msg* req, struct sip_msg* repl, short flags);
438 
439 /* like run_trans_callbacks but tmcb_params assumed to contain data already */
440 void run_trans_callbacks_off_params(int type, struct cell* t, struct tmcb_params* p);
441 
442 #endif
443