GPLization banner introduced to *.[hc] files
[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
28
29 #ifndef _HOOKS_H
30 #define _HOOKS_H
31
32 struct sip_msg;
33 struct cell;
34
35 typedef enum { TMCB_REPLY,  TMCB_E2EACK, TMCB_REPLY_IN, 
36         TMCB_REQUEST_OUT, TMCB_LOCAL_COMPLETED, TMCB_ON_NEGATIVE,
37         TMCB_END } tmcb_type;
38
39 /* 
40         TMCB_REPLY      -  a reply has been sent out
41           no chance to change anything in the message; 
42           still good enough for many uses, such as accounting
43           of completed transactions; note well that the message
44           passed to the callback may also have value FAKED_REPLY,
45           i.e., refering to it will segfault
46         TMCB_REPLY_IN - a reply was received and is about to be forwarded;
47           compared to TMCB_REPLY, it is a very internal callback and
48           you should use it with lot of caution
49           - it allows you to change the message (called before printing
50             the relayed message)
51           - it is called from a reply lock -- it is mroe dangerous and
52             anything you do makes the processes spend more time in
53             the lock, decreasing overall performance
54           - is is called only for replies >100, <300 (final replies
55             might be cached on forking, stored in shmem -- then, there
56                 is no more easy way to change messages)
57           - as it is called before printing and forwarding, there is
58             no guarantee the message will be sent out -- either can
59             fail
60
61                 Note: none of the reply callbacks will be evoked if
62                 "silent C timer" hits. Silent C timer is a feature which
63                 prevents cancellation of a call in progress by a server
64                 in the middle, when C timer expires. On one side, 
65                 INVITE transactional state cannot be kept for ever,
66                 on the other side you want to allow long ringing 
67                 uninterrupted by a proxy server. The silent_c feature
68                 -- if circumstances allow -- simply discards transaction
69                 state when C timer hits, the transaction can then complete
70                 statelessly. Then, however, the stateful callback will
71                 NOT be called. If you do not wish this behaviour (e.g.,
72                 for sake of transaction accounting, in which you do
73                 not desire users to wait until silent C hits and
74                 eventually complete an unaccounted transaction), turn
75                 silent C off either globaly (TM option "noisy_ctimer"
76                 set to 1) or for a specific transaction (you can for
77                 example set the transaction member "noisy_timer"
78                 from request callback.)
79
80         TMCB_E2EACK - presumably, an end2end ACK was received and
81                 is about to be processed statelessly; you better don't
82             use this callback as there is no reliable way to match
83             an e2e ACK to an INVITE transaction, we just try it for
84             those, who believe they can't live without knowing about
85             the ACK; There are more reasons why the e2e ACK callback
86             is never triggered: 1) the e2eACK does not pass the server
87             at all 2) the e2e ACK does not match an INVITE transaction
88                 because its r-uri or via is different
89         TMCB_REQUEST_OUT - a request was received and is about to be fwd-ed;
90                 it is not called on retransmissions; it is called prior to
91                 printing the relayed message, i.e., changes to it can
92                 be done
93         TMCB_LOCAL_COMPLETED - a local transaction completed; note that
94             the callback parameter may be FAKED_REPLY
95         TMCB_MISSED -- transaction was replied with a negative value;
96                 called from within a REPLY_LOCK, message may be FAKED_REPLY
97         TMCB_ON_NEGATIVE -- called whenever a transaction is about to complete
98             with a negative result; it's a great time to introduce a new
99             uac (serial forking) or change the reply code; be cautions
100             though -- it is called from within REPLY_LOCK and careless
101             usage of the callback can easily result in a deadlock; msg
102             is always 0 (callback refers to whole transaction and not
103             to individual message), code is the currently lowest status
104             code
105         TMCB_END        - just a bumper
106
107         see the 'acc' module for an example of callback usage
108
109         note that callbacks MUST be installed before forking
110     (callback lists do not live in shmem and have no access
111         protection)
112 */
113
114 typedef void (transaction_cb) ( struct cell* t, struct sip_msg* msg, 
115         int code, void *param );
116
117 struct tm_callback_s {
118         int id;
119         transaction_cb* callback;
120         struct tm_callback_s* next;
121         void *param;
122 };
123
124
125 extern struct tm_callback_s* callback_array[ TMCB_END ];
126
127 typedef int (*register_tmcb_f)(tmcb_type cbt, transaction_cb f, void *param);
128
129 int register_tmcb( tmcb_type cbt, transaction_cb f, void *param );
130 void callback_event( tmcb_type cbt, struct cell *trans,
131         struct sip_msg *msg, int code );
132
133 #endif