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