tm: added t_is_set("target") function
[sip-router] / modules / tm / README
1 1. TM Module
2
3 Jiri Kuthan
4
5    FhG FOKUS
6
7 Juha Heinanen
8
9    <jh@tutpro.com>
10
11    Copyright © 2003 FhG FOKUS
12
13    Copyright © 2008 Juha Heinanen
14      __________________________________________________________________
15
16    1.1. Overview
17    1.2. Serial Forking Based on Q Value
18    1.3. Known Issues
19    1.4. Parameters
20
21         1.4.1. fr_timer (integer)
22         1.4.2. fr_inv_timer (integer)
23         1.4.3. max_inv_lifetime (integer)
24         1.4.4. max_noninv_lifetime (integer)
25         1.4.5. wt_timer (integer)
26         1.4.6. delete_timer (integer)
27         1.4.7. retr_timer1 (integer)
28         1.4.8. retr_timer2 (integer)
29         1.4.9. noisy_ctimer (integer)
30         1.4.10. restart_fr_on_each_reply (integer)
31         1.4.11. auto_inv_100 (integer)
32         1.4.12. auto_inv_100_reason (string)
33         1.4.13. unix_tx_timeout (integer)
34         1.4.14. aggregate_challenges (integer)
35         1.4.15. reparse_invite (integer)
36         1.4.16. ac_extra_hdrs (string)
37         1.4.17. blst_503 (integer)
38         1.4.18. blst_503_def_timeout (integer)
39         1.4.19. blst_503_min_timeout (integer)
40         1.4.20. blst_503_max_timeout (integer)
41         1.4.21. blst_methods_add (unsigned integer)
42         1.4.22. blst_methods_lookup (unsigned integer)
43         1.4.23. cancel_b_method (integer)
44         1.4.24. reparse_on_dns_failover (integer)
45         1.4.25. on_sl_reply (string)
46         1.4.26. contacts_avp (string)
47         1.4.27. fr_timer_avp (string)
48         1.4.28. fr_inv_timer_avp (string)
49         1.4.29. unmatched_cancel (string)
50         1.4.30. ruri_matching (integer)
51         1.4.31. via1_matching (integer)
52         1.4.32. pass_provisional_replies (integer)
53         1.4.33. default_code (integer)
54         1.4.34. default_reason (string)
55         1.4.35. disable_6xx_block (integer)
56         1.4.36. local_ack_mode (integer)
57         1.4.37. failure_reply_mode (integer)
58         1.4.38. faked_reply_prio (integer)
59         1.4.39. local_cancel_reason (boolean)
60         1.4.40. e2e_cancel_reason (boolean)
61
62    1.5. Functions
63
64         1.5.1. t_relay([host, port])
65         1.5.2. t_relay_to_udp([ip, port])
66         1.5.3. t_relay_to_tcp([ip, port])
67         1.5.4. t_relay_to_tls([ip, port])
68         1.5.5. t_relay_to_sctp([ip, port])
69         1.5.6. t_on_failure(failure_route)
70         1.5.7. t_on_reply(onreply_route)
71         1.5.8. t_on_branch(branch_route)
72         1.5.9. append_branch()
73         1.5.10. t_newtran()
74         1.5.11. t_reply(code, reason_phrase)
75         1.5.12. t_lookup_request()
76         1.5.13. t_retransmit_reply()
77         1.5.14. t_release()
78         1.5.15. t_forward_nonack([ip, port])
79         1.5.16. t_forward_nonack_udp(ip, port)
80         1.5.17. t_forward_nonack_tcp(ip, port)
81         1.5.18. t_forward_nonack_tls(ip, port)
82         1.5.19. t_forward_nonack_sctp(ip, port)
83         1.5.20. t_set_fr(fr_inv_timeout [, fr_timeout])
84         1.5.21. t_reset_fr()
85         1.5.22. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
86         1.5.23. t_reset_max_lifetime()
87         1.5.24. t_set_retr(retr_t1_interval, retr_t2_interval)
88         1.5.25. t_reset_retr()
89         1.5.26. t_set_auto_inv_100(0|1)
90         1.5.27. t_branch_timeout()
91         1.5.28. t_branch_replied()
92         1.5.29. t_any_timeout()
93         1.5.30. t_any_replied()
94         1.5.31. t_grep_status("code")
95         1.5.32. t_is_canceled()
96         1.5.33. t_is_expired()
97         1.5.34. t_relay_cancel()
98         1.5.35. t_lookup_cancel([1])
99         1.5.36. t_drop_replies([mode])
100         1.5.37. t_save_lumps()
101         1.5.38. t_load_contacts()
102         1.5.39. t_next_contacts()
103         1.5.40. t_check_trans()
104         1.5.41. t_set_disable_6xx(0|1)
105         1.5.42. t_set_disable_failover(0|1)
106         1.5.43. t_replicate(params)
107         1.5.44. t_relay_to(proxy, flags)
108         1.5.45. t_set_no_e2e_cancel_reason(0|1)
109         1.5.46. t_is_set(target)
110
111    1.6. TM Module API
112
113         1.6.1. Defines
114         1.6.2. Functions
115
116               1.6.2.1. register_tmcb(cb_type, cb_func)
117               1.6.2.2. load_tm(*import_structure)
118               1.6.2.3. int t_suspend(struct sip_msg *msg, unsigned int
119                       *hash_index, unsigned int *label)
120
121               1.6.2.4. int t_continue(unsigned int hash_index, unsigned
122                       int label, struct action *route)
123
124               1.6.2.5. int t_cancel_suspend(unsigned int hash_index,
125                       unsigned int label)
126
127 1.1. Overview
128
129    TM module enables stateful processing of SIP transactions. The main use
130    of stateful logic, which is costly in terms of memory and CPU, is some
131    services inherently need state. For example, transaction-based
132    accounting (module acc) needs to process transaction state as opposed
133    to individual messages, and any kinds of forking must be implemented
134    statefully. Other use of stateful processing is it trading CPU caused
135    by retransmission processing for memory. That makes however only sense
136    if CPU consumption per request is huge. For example, if you want to
137    avoid costly DNS resolution for every retransmission of a request to an
138    unresolvable destination, use stateful mode. Then, only the initial
139    message burdens server by DNS queries, subsequent retransmissions will
140    be dropped and will not result in more processes blocked by DNS
141    resolution. The price is more memory consumption and higher processing
142    latency.
143
144    From user's perspective, there are these major functions : t_relay,
145    t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
146    absorb retransmissions from upstream, generate downstream
147    retransmissions and correlate replies to requests. t_relay forwards to
148    current URI (be it original request's URI or a URI changed by some of
149    URI-modifying functions, such as sethost). t_relay_to_udp and
150    t_relay_to_tcp forward to a specific address over UDP or TCP
151    respectively.
152
153    In general, if TM is used, it copies clones of received SIP messages in
154    shared memory. That costs the memory and also CPU time (memcpys,
155    lookups, shmem locks, etc.) Note that non-TM functions operate over the
156    received message in private memory, that means that any core operations
157    will have no effect on statefully processed messages after creating the
158    transactional state. For example, calling record_route after t_relay is
159    pretty useless, as the RR is added to privately held message whereas
160    its TM clone is being forwarded.
161
162    TM is quite big and uneasy to program--lot of mutexes, shared memory
163    access, malloc and free, timers--you really need to be careful when you
164    do anything. To simplify TM programming, there is the instrument of
165    callbacks. The callback mechanisms allow programmers to register their
166    functions to specific event. See t_hooks.h for a list of possible
167    events.
168
169    Other things programmers may want to know is UAC--it is a very
170    simplistic code which allows you to generate your own transactions.
171    Particularly useful for things like NOTIFYs or IM gateways. The UAC
172    takes care of all the transaction machinery: retransmissions , FR
173    timeouts, forking, etc. See t_uac prototype in uac.h for more details.
174    Who wants to see the transaction result may register for a callback.
175
176 Note
177
178    Several Kamailio (OpenSER) TM module functionalities are now
179    implemented in the TMX module: "modules_k/tmx". Check it to see if what
180    you are looking for is there.
181
182 1.2. Serial Forking Based on Q Value
183
184    A single SIP INVITE request may be forked to multiple destinations. We
185    call the set of all such destinations a destination set. Individual
186    elements within the destination sets are called branches. The script
187    writer can add URIs to the destination set from the configuration file,
188    or they can be loaded from the user location database, each registered
189    contact then becomes one branch in the destination set.
190
191    The default behavior of the tm module, if it encounters a SIP message
192    with multiple branches in the destination set, it to forward the SIP
193    message to all the branches in parallel. That means it sends the
194    message to all the branch destinations before it waits for replies from
195    any of them. This is the default behavior if you call t_relay() and
196    similar functions without anything else.
197
198    Another approach of handling multiple branches in a destination set it
199    serial forking. When configured to do serial forking, the server takes
200    the first branch out of the destination set, forwards the message to
201    its destination and waits for a reply or timeout. Only after a reply
202    has been received or the timeout occurred, the server takes another
203    destination from the destination set and tries again, until it receives
204    a positive final reply or until all branches from the destination set
205    have been tried.
206
207    Yet another, more sophisticated, way of handling multiple branches is
208    combined serial/parallel forking, where individual branches within the
209    destination set are assigned priorities. The order in which individual
210    branches are tried is then determined by their relative priority within
211    the destination set. Branches can be tried sequentially in the
212    descending priority order and all branches that have the same priority
213    can be tried in parallel. Such combined serial/parallel forking can be
214    achieved in the tm module with the help of functions t_load_contacts()
215    and t_next_contacts().
216
217    Every branch in the destination set is assigned a priority number, also
218    known as the q value. The q value is a floating point number in a range
219    0 to 1.0. The higher the q value number, the more priority is the
220    particular branch in the destination set is given. Branches with q
221    value 1.0 have maximum priority, such branches should be always tried
222    first in serial forking. Branches with q value 0 have the lowest
223    priority and they should by tried after all other branches with higher
224    priority in the destination set.
225
226    As an example, consider the following simple configuration file. When
227    the server receives an INVITE, it creates four branches for it with
228    usernames A through D and then forwards the request using t_relay():
229 route {
230   seturi("sip:a@example.com");
231   append_branch("sip:b@example.com");
232   append_branch("sip:c@example.com");
233   append_branch("sip:d@example.com");
234
235   t_relay();
236   break;
237 }
238
239    With this configuratin the server forwards the request to all four
240    branches at once, performing parallel forking described above. We did
241    not set the q value for individual branches in this example but we can
242    do that by slightly modifying the arguments given to append_branch():
243 route {
244   seturi("sip:a@example.com");
245   append_branch("sip:b@example.com", "0.5");
246   append_branch("sip:c@example.com", "0.5");
247   append_branch("sip:d@example.com", "1.0");
248
249   t_relay();
250   break;
251 }
252
253    Here we assigned q value 0.5 to branches B and C and q value 1.0 to
254    branch D. We did not specify any q value for branch A and in that case
255    it is assumed that its q value is the lowest from all branches within
256    the destination set. If you try to run this example again, you will
257    figure out that nothing changed, t_relay() still forward the message to
258    all branches in parallel.
259
260    We now want to implement the combined serial/parallel forking. Branch D
261    should be tried first, because its q value is 1.0. Branches B and C
262    should be tried in parallel, but only after D finishes. Branch A should
263    be tried after B and C finished, because its q value (the default) is
264    the lowest of all. To do that, we need to introduce two new functions
265    into our example and one tm module parameter:
266 modparam("tm", "contacts_avp", "tm_contacts");
267
268 route {
269   seturi("sip:a@example.com");
270   append_branch("sip:b@example.com", "0.5");
271   append_branch("sip:c@example.com", "0.5");
272   append_branch("sip:d@example.com", "1.0");
273
274   t_load_contacts();
275
276   t_next_contacts();
277   t_relay();
278   break;
279 }
280
281    First of all, the tm module parameter is mandatory if the two new
282    functions are used. Function t_load_contacts() takes all branches from
283    the destination set, sorts them according to their q values and stores
284    them in the AVP configured in the modparam. The function also clears
285    the destination set, which means that it removes all branches
286    configured before with seturi() and append_branch().
287
288    Function t_next_contacts() takes the AVP created by the previous
289    function and extract the branches with highest q values from it. In our
290    example it is branch D. That branch is then put back into the
291    destination set and when the script finally reaches t_relay(), the
292    destination set only contains branch D and the request will be
293    forwarded there.
294
295    We achieved the first step of serial forking, but this is not
296    sufficient. Now we also need to forward to other branches with lower
297    priority values when branch D finishes. To do that, we need to extend
298    the configuration file again and introduce a failure_route section:
299 modparam("tm", "contacts_avp", "tm_contacts");
300
301 route {
302   seturi("sip:a@example.com");
303   append_branch("sip:b@example.com", "0.5");
304   append_branch("sip:c@example.com", "0.5");
305   append_branch("sip:d@example.com", "1.0");
306
307   t_load_contacts();
308
309   t_next_contacts();
310   t_on_failure("serial");
311   t_relay();
312   break;
313 }
314
315 failure_route["serial"]
316 {
317   if (!t_next_contacts()) {
318     exit;
319   }
320
321   t_on_failure("serial");
322   t_relay();
323 }
324
325    The failure_route section will be executed when branch D finishes. It
326    executes t_next_contacts() again and this time the function retrieves
327    branches B and C from the AVP and adds them to the destination set.
328    Here we need to check the return value of the function, because a
329    negative value indicates that there were no more branches, in that case
330    the failure_route should just terminate and forward the response from
331    branch D upstream.
332
333    If t_next_contact() returns a positive value then we have more new
334    branches to try and we need to setup the failure_route again and call
335    t_relay(). In our example the request will now be forwarded to branches
336    B and C in paralell, because they were both added to the destination
337    set by t_next_contacts() at the same time.
338
339    When branches B and C finish, the failure_route block is executed
340    again, this time t_next_contacts() puts the final branch A into the
341    destination set and t_relay() forwards the request there.
342
343    And that's the whole example, we achieved combined serial/parallel
344    forking based on the q value of individual branches. In real-world
345    configuration files the script writer would need to check the return
346    value of all functions and restart_fr_on_each_reply. Also the
347    destination set would not be configured directly in the configuration
348    file, but can be retrieved from the user location database, for
349    example. In that case registered contacts will be stored in the
350    destination set as branches and their q values (provided by UAs) will
351    be used.
352
353 1.3. Known Issues
354
355      * Possibly, performance could be improved by not parsing non-INVITEs,
356        as they do not be replied with 100, and do not result in
357        ACK/CANCELs, and other things which take parsing. However, we need
358        to rethink whether we don't need parsed headers later for something
359        else. Remember, when we now conserver a request in sh_mem, we can't
360        apply any pkg_mem operations to it any more. (that might be
361        redesigned too).
362      * Another performance improvement may be achieved by not parsing CSeq
363        in replies until reply branch matches branch of an INVITE/CANCEL in
364        transaction table.
365      * t_replicate should be done more cleanly--Vias, Routes, etc. should
366        be removed from a message prior to replicating it (well, does not
367        matter any longer so much as there is a new replication module).
368
369 1.4. Parameters
370
371 1.4.1. fr_timer (integer)
372
373    Timer which hits if no final reply for a request or ACK for a negative
374    INVITE reply arrives (in milliseconds).
375
376    Default value is 30000 ms (30 seconds).
377
378    See also: t_set_fr(), max_noninv_lifetime.
379
380    Example 1. Set fr_timer parameter
381 ...
382 modparam("tm", "fr_timer", 10000)
383 ...
384
385 1.4.2. fr_inv_timer (integer)
386
387    Timer which hits if no final reply for an INVITE arrives after a
388    provisional message was received (in milliseconds).
389
390    Note: this timer can be restarted when a provisional response is
391    received. For more details see restart_fr_on_each_reply.
392
393    Default value is 120000 ms (120 seconds).
394
395    See also: t_set_fr(), max_inv_lifetime.
396
397    Example 2. Set fr_inv_timer parameter
398 ...
399 modparam("tm", "fr_inv_timer", 180000)
400 ...
401
402 1.4.3. max_inv_lifetime (integer)
403
404    Maximum time an INVITE transaction is allowed to be active (in
405    milliseconds). After this interval has passed from the transaction
406    creation, the transaction will be either moved into the wait state or
407    in the final response retransmission state, irrespective of the
408    transaction fr_inv_timer and fr_timer values.
409
410    An INVITE transaction will be kept in memory for maximum:
411    max_inv_lifetime+fr_timer(from the ack to the final reply
412    wait)+wt_timer.
413
414    The main difference between this timer and fr_inv_timer is that the
415    fr_inv_timer is per branch, while max_inv_lifetime is per the whole
416    transaction. Even on a per branch basis fr_inv_timer could be
417    restarted. For example, by default if restart_fr_on_each_reply is not
418    cleared, the fr_inv_timer will be restarted for each received
419    provisional reply. Even if restart_fr_on_each_reply is not set the
420    fr_inv_timer will still be restarted for each increasing reply (e.g.
421    180, 181, 182, ...). Another example when a transaction can live
422    substantially more then its fr_inv_timer and where max_inv_lifetime
423    will help is when dns failover is used (each failed dns destination can
424    introduce a new branch).
425
426    The default value is 180000 ms (180 seconds - the rfc3261 timer C
427    value).
428
429    See also: max_noninv_lifetime, t_set_max_lifetime() (allows changing
430    max_inv_lifetime on a per transaction basis), t_reset_max_lifetime
431    fr_timer, wt_timer, restart_fr_on_each_reply.
432
433    Example 3. Set max_inv_lifetime parameter
434 ...
435 modparam("tm", "max_inv_lifetime", 150000)
436 ...
437
438 1.4.4. max_noninv_lifetime (integer)
439
440    Maximum time a non-INVITE transaction is allowed to be active (in
441    milliseconds). After this interval has passed from the transaction
442    creation, the transaction will be either moved into the wait state or
443    in the final response retransmission state, irrespective of the
444    transaction fr_timer value. It's the same as max_inv_lifetime, but for
445    non-INVITEs.
446
447    A non-INVITE transaction will be kept in memory for maximum:
448    max_noninv_lifetime+wt_timer.
449
450    The main difference between this timer and fr_timer is that the
451    fr_timer is per branch, while max_noninv_lifetime is per the whole
452    transaction. An example when a transaction can live substantially more
453    then its fr_timer and where max_noninv_lifetime will help is when dns
454    failover is used (each failed dns destination can introduce a new
455    branch).
456
457    The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
458
459    See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
460    max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
461    fr_timer, wt_timer.
462
463    Example 4. Set max_noninv_lifetime parameter
464 ...
465 modparam("tm", "max_inv_lifetime", 30000)
466 ...
467
468 1.4.5. wt_timer (integer)
469
470    Time for which a transaction stays in memory to absorb delayed messages
471    after it completed (in milliseconds); also, when this timer hits,
472    retransmission of local cancels is stopped (a puristic but complex
473    behavior would be not to enter wait state until local branches are
474    finished by a final reply or FR timer--we simplified).
475
476    Default value is 5000 ms (5 seconds).
477
478    Example 5. Set wt_timer parameter
479 ...
480 modparam("tm", "wt_timer", 1000)
481 ...
482
483 1.4.6. delete_timer (integer)
484
485    Time after which a to-be-deleted transaction currently ref-ed by a
486    process will be tried to be deleted again (in milliseconds).
487
488    Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
489    deleted the moment it's not referenced anymore).
490
491    Default value is 200 milliseconds.
492
493    Example 6. Set delete_timer parameter
494 ...
495 modparam("tm", "delete_timer", 100)
496 ...
497
498 1.4.7. retr_timer1 (integer)
499
500    Initial retransmission period (in milliseconds).
501
502    Default value is 500 milliseconds.
503
504    Example 7. Set retr_timer1 parameter
505 ...
506 modparam("tm", "retr_timer1", 1000)
507 ...
508
509 1.4.8. retr_timer2 (integer)
510
511    Maximum retransmission period (in milliseconds). The retransmission
512    interval starts with retr_timer1 and increases until it reaches this
513    value. After this it stays constant at retr_timer2.
514
515    Default value is 4000 milliseconds.
516
517    Example 8. Set retr_timer2 parameter
518 ...
519 modparam("tm", "retr_timer2", 2000)
520 ...
521
522 1.4.9. noisy_ctimer (integer)
523
524    If set, INVITE transactions that time-out (FR INV timer) will be always
525    replied. If it's not set, the transaction has only one branch and no
526    response was ever received on this branch, it will be silently dropped
527    (no 408 reply will be generated) This behavior is overridden if a
528    request is forked, the transaction has a failure route or callback, or
529    some functionality explicitly turned it on for a transaction (like acc
530    does to avoid unaccounted transactions due to expired timer). Turn this
531    off only if you know the client UACs will timeout and their timeout
532    interval for INVITEs is lower or equal than tm's fr_inv_timer.
533
534    Default value is 1 (on).
535
536    Example 9. Set noisy_ctimer parameter
537 ...
538 modparam("tm", "noisy_ctimer", 1)
539 ...
540
541 1.4.10. restart_fr_on_each_reply (integer)
542
543    If set (default), the fr_inv_timer for an INVITE transaction will be
544    restarted for each provisional reply received (rfc3261 mandated
545    behaviour). If not set, the fr_inv_timer will be restarted only for the
546    first provisional replies and for increasing replies greater or equal
547    180 (e.g. 180, 181, 182, 185, ...).
548
549    Setting it to 0 is especially useful when dealing with bad UAs that
550    continuously retransmit 180s, not allowing the transaction to timeout
551    (and thus making impossible the implementation of certain services,
552    like automatic voicemail after x seconds).
553
554    Default value is 1 (on).
555
556    See also: fr_inv_timer, max_inv_lifetime.
557
558    Example 10. Set restart_fr_on_each_reply parameter
559 ...
560 modparam("tm", "restart_fr_on_each_reply", 0)
561 ...
562
563 1.4.11. auto_inv_100 (integer)
564
565    If set (default) tm will automatically send and 100 reply to INVITEs.
566
567    Setting it to 0 one can be used to enable doing first some tests or
568    pre-processing on the INVITE and only if some conditions are met
569    manually send a 100 (using t_reply()). Note however that in this case
570    all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
571    to selectively turn off this feature only for some specific
572    transactions.
573
574    Default value is 1 (on).
575
576    See also: t_set_auto_inv_100() auto_inv_100_reason.
577
578    Example 11. Set auto_inv_100 parameter
579 ...
580 modparam("tm", "auto_inv_100", 0)
581 ...
582
583 1.4.12. auto_inv_100_reason (string)
584
585    Set reason text of the automatically send 100 to an INVITE.
586
587    Default value is "trying -- your call is important to us".
588
589    See also: auto_inv_100.
590
591    Example 12. Set auto_inv_100_reason parameter
592 ...
593 modparam("tm", "auto_inv_100_reason", "Trying")
594 ...
595
596 1.4.13. unix_tx_timeout (integer)
597
598    Unix socket transmission timeout, in milliseconds.
599
600    If unix sockets are used (e.g.: to communicate with sems) and sending a
601    message on a unix socket takes longer then unix_tx_timeout, the send
602    will fail.
603
604    The default value is 500 milliseconds.
605
606    Example 13. Set unix_tx_timeout parameter
607 ...
608 modparam("tm", "unix_tx_timeout", 250)
609 ...
610
611 1.4.14. aggregate_challenges (integer)
612
613    If set (default), the final reply is a 401 or a 407 and more then one
614    branch received a 401 or 407, then all the WWW-Authenticate and
615    Proxy-Authenticate headers from all the 401 and 407 replies will be
616    aggregated in a new final reply. If only one branch received the
617    winning 401 or 407 then this reply will be forwarded (no new one will
618    be built). If 0 only the first 401, or if no 401 was received the first
619    407, will be forwarded (no header aggregation).
620
621    Default value is 1 (required by rfc3261).
622
623    Example 14. Set aggregate_challenges parameter
624 ...
625 modparam("tm", "aggregate_challenges", 0)
626 ...
627
628 1.4.15. reparse_invite (integer)
629
630    If set (default), the CANCEL and negative ACK requests are constructed
631    from the INVITE message which was sent out instead of building them
632    from the received request. The disadvantage is that the outgoing INVITE
633    has to be partially re-parsed, the advantage is that the CANCEL/ACK is
634    always RFC 3261-compliant, it always contains the same route-set as the
635    INVITE message. Do not disable the INVITE re-parsing for example in the
636    following cases:
637
638    - The INVITE contains a preloaded route-set, and SER forwards the
639    message to the next hop according to the Route header. The Route header
640    is not removed in the CANCEL without reparse_invite=1.
641
642    - SER record-routes, thus an in-dialog INVITE contains a Route header
643    which is removed during loose routing. If the in-dialog INVITE is
644    rejected, the negative ACK still contains the Route header without
645    reparse_invite=1.
646
647    Default value is 1.
648
649    Example 15. Set reparse_invite parameter
650 ...
651 modparam("tm", "reparse_invite", 0)
652 ...
653
654 1.4.16. ac_extra_hdrs (string)
655
656    Header fields prefixed by this parameter value are included in the
657    CANCEL and negative ACK messages if they were present in the outgoing
658    INVITE.
659
660    Note, that the parameter value effects only those headers which are not
661    covered by RFC-3261 (which are neither mandatory nor prohibited in
662    CANCEL and ACK), and the parameter can be used only together with
663    reparse_invite=1.
664
665    Default value is "".
666
667    Example 16. Set ac_extra_hdrs parameter
668 ...
669 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
670 ...
671
672 1.4.17. blst_503 (integer)
673
674    If set and the blacklist support is enabled, every 503 reply source is
675    added to the blacklist. The initial blacklist timeout (or ttl) depends
676    on the presence of a Retry-After header in the reply and the values of
677    the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
678    and blst_503_max_timeout.
679
680    WARNING:blindly allowing 503 blacklisting could be very easily
681    exploited for DOS attacks in most network setups.
682
683    The default value is 0 (disabled due to the reasons above).
684
685    Example 17. Set blst_503 parameter
686 ...
687 modparam("tm", "blst_503", 1)
688 ...
689
690 1.4.18. blst_503_def_timeout (integer)
691
692    Blacklist interval in seconds for a 503 reply with no Retry-After
693    header. See also blst_503, blst_503_min_timeout and
694    blst_503_max_timeout.
695
696    The default value is 0, which means that if no Retry-After header is
697    present, the 503 reply source will not be blacklisted (rfc conformant
698    behaviour).
699
700    Example 18. Set blst_503_def_timeout parameter
701 ...
702 modparam("tm", "blst_503_def_timeout", 120)
703 ...
704
705 1.4.19. blst_503_min_timeout (integer)
706
707    Minimum blacklist interval in seconds for a 503 reply with a
708    Retry-After header. It will be used if the Retry-After value is
709    smaller. See also blst_503, blst_503_def_timeout and
710    blst_503_max_timeout.
711
712    The default value is 0
713
714    Example 19. Set blst_503_min_timeout parameter
715 ...
716 modparam("tm", "blst_503_min_timeout", 30)
717 ...
718
719 1.4.20. blst_503_max_timeout (integer)
720
721    Maximum blacklist interval in seconds for a 503 reply with a
722    Retry-After header. It will be used if the Retry-After value is
723    greater. See also blst_503, blst_503_def_timeout and
724    blst_503_min_timeout.
725
726    The default value is 3600
727
728    Example 20. Set blst_503_max_timeout parameter
729 ...
730 modparam("tm", "blst_503_max_timeout", 604800)
731 ...
732
733 1.4.21. blst_methods_add (unsigned integer)
734
735    Bitmap of method types that trigger blacklisting on transaction
736    timeouts. (This setting has no effect on blacklisting because of send
737    failures.)
738
739    The following values are associated to the request methods: INVITE=1,
740    CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
741    INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
742    unknown types). Check parser/msg_parser.h for farther details.
743
744    Change the value carefully, because requests not having provisional
745    response (everything but INVITE) can easily cause the next hop to be
746    inserted into the blacklist by mistake. For exmaple the next hop is a
747    proxy, it is alive, but waiting for the response of the UAS, and has
748    higher fr_timer value.
749
750    The default value is 1, only INVITEs trigger blacklisting
751
752    Example 21. Set blst_methods_add parameter
753 ...
754 # INVITEs and REGISTERs trigger blacklisting
755 modparam("tm", "blst_methods_add", 33)
756 ...
757
758 1.4.22. blst_methods_lookup (unsigned integer)
759
760    Bitmap of method types that are looked-up in the blacklist before
761    statefull forwarding. See also blst_methods_add
762
763    The default value is 4294967287, every method type except BYE. (We try
764    to deliver BYEs no matter what)
765
766    Example 22. Set blst_methods_lookup parameter
767 ...
768 # lookup only INVITEs
769 modparam("tm", "blst_methods_lookup", 1)
770 ...
771
772 1.4.23. cancel_b_method (integer)
773
774    Method used when attempting to CANCEL an unreplied transaction branch
775    (a branch where no reply greater the 99 was received). The possible
776    values are 0, 1, and 2.
777
778    0 will immediately stop the request (INVITE) retransmission on the
779    branch and it will behave as if the branch was immediately replied with
780    a 487 (a fake internal 487 reply). The advantage is the unreplied
781    branches will be terminated immediately. However it introduces a race
782    risk with a possible slightly delayed 2xx reply. In this case we could
783    have an UA receiving a 2xx after a 487. Moreover this risk is greatly
784    amplified by packet loss (e.g. if an 180 is lost the branch will look
785    as unreplied and a CANCEL will silently drop the branch, but a 2xx can
786    still come at a later time). This is the behaviour for ser versions
787    older then 2.1.
788
789    1 will keep retransmitting the request on unreplied branches. If a
790    provisional answer is later received a CANCEL will be immediately sent
791    back (attempting to quickly trigger a 487). This approach is race free
792    and avoids the 2xx after 487 problem, but it's more resource intensive:
793    faced with a branch towards and UA that doesn't answer, a CANCEL
794    attempt will keep the transaction alive for the whole timeout interval
795    (fr_timer).
796
797    2 will send and retransmit CANCEL even on unreplied branches, stopping
798    the request retransmissions. This has the same advantages as 1 and also
799    avoids the extra roundtrip in the case of the provisional reply, but
800    it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
801    pending branches).
802
803    The default value is 1.
804
805    Example 23. Set cancel_b_method parameter
806 ...
807 modparam("tm", "cancel_b_method", 1)
808 ...
809
810 1.4.24. reparse_on_dns_failover (integer)
811
812    If set to 1, the SIP message after a DNS failover is constructed from
813    the outgoing message buffer of the failed branch instead of from the
814    received request.
815
816    It must be set if multiple branches are installed, the SIP message is
817    modified differently in them, and at least one of them can result in
818    DNS failover. If the parameter is not set the per-branch modifications
819    are lost after the failover.
820
821    Note: If the parameter is set, branch route block and
822    TMCB_REQUEST_FWDED callback are not called in case of the failover.
823
824    Disadvantage: only the via header is replaced in the message buffer, so
825    the outgoing socket address is not corrected in any other part of the
826    message. It is dangerous on multihomed hosts: when the new SIP request
827    after the DNS failover is sent via different interface than the first
828    request, the message can contain incorrect ip address in the
829    Record-Route header for instance.
830
831    Default value is 1.
832
833    Example 24. Set reparse_on_dns_failover parameter
834 ...
835 modparam("tm", "reparse_on_dns_failover", 0)
836 ...
837
838 1.4.25. on_sl_reply (string)
839
840    Sets reply route block, to which control is passed when a reply is
841    received that has no associated transaction. The reply is passed to the
842    core for stateless forwarding after the route block execution unless it
843    returns 0.
844
845    Example 25. Set on_sl_reply parameter
846 ...
847 modparam("tm", "on_sl_reply", "stateless_replies")
848 ...
849
850 onreply_route["stateless_replies"] {
851         # do not allow stateless replies to be forwarded
852         return 0;
853 }
854
855 1.4.26. contacts_avp (string)
856
857    This is the name or Id of an AVP that t_load_contacts() function uses
858    to store contacts of the destination set and that t_next_contacts()
859    function uses to restore those contacts.
860
861    Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
862    are disabled).
863
864    Example 26. Set contacts_avp parameter
865 ...
866 modparam("tm", "contacts_avp", "$avp(i:25)")
867 ...
868
869 1.4.27. fr_timer_avp (string)
870
871    The value of fr_timer timer can be overriden on per-transaction basis.
872    The administrator can provide a value to be used for a particular
873    transaction in an AVP. This parameter contains the name of the AVP that
874    will be checked. If the AVP exists then its value will be used for the
875    fr_timer timer, effectively overriding the value configured in fr_timer
876    parameter for the current transaction.
877
878    The value of this parameter is the the name of the AVP to be checked,
879    without the $ character or "$avp" prefix.
880
881 Note
882
883    The value of the AVP is expected to be expressed in seconds and not
884    milliseconds (unlike the rest of the timers).
885
886    This parameter is kept for backwards compatibility (hence its value
887    expressed in seconds instead of milliseconds and its arcane way of
888    specifying the avps). The recommended replacement is using t_set_fr()
889    on a per transaction basis.
890
891    See also: t_set_fr(), fr_timer.
892
893    In Kamailio compatibility mode (defined by #!KAMAILIO), the value of
894    the parameter must be the name of an AVP in pseudo-variable format:
895    $avp(name). In SER compatibility mode it must by just AVP name.
896
897    Example 27. Set fr_timer_avp parameter
898 ...
899 modparam("tm", "fr_timer_avp", "i:708")
900 # K mode
901 modparam("tm", "fr_timer_avp", "$avp(i:708)")
902 ...
903
904 1.4.28. fr_inv_timer_avp (string)
905
906    The value of fr_inv_timer timer can be overriden on per-transaction
907    basis. The administrator can provide a value to be used for a
908    particular transaction in an AVP. This parameter contains the name of
909    the AVP that will be checked. If the AVP exists, is non-empty and
910    non-zero then its value will be used for the fr_inv_timer timer,
911    effectively overriding the value configured in fr_inv_timer parameter
912    for the current transaction.
913
914    The value of this parameter is the the name of the AVP to be checked,
915    without the $ character or "$avp" prefix.
916
917 Note
918
919    The value of the AVP is expected to be expressed in seconds and not
920    milliseconds (unlike the rest of the timers).
921
922    This parameter is kept for backwards compatibility (hence its value
923    expressed in seconds instead of milliseconds and its arcane way of
924    specifying the avps). The recommended replacement is using t_set_fr()
925    on a per transaction basis.
926
927    See also: t_set_fr(), fr_inv_timer.
928
929    In Kamailio compatibility mode (defined by #!KAMAILIO), the value of
930    the parameter must be the name of an AVP in pseudo-variable format:
931    $avp(name). In SER compatibility mode it must by just AVP name.
932
933    Example 28. Set fr_inv_timer_avp parameter
934 ...
935 modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
936 # K mode
937 modparam("tm", "fr_inv_timer_avp", "$avp(my_fr_inv_timer)")
938 ...
939
940 1.4.29. unmatched_cancel (string)
941
942    This parameter selects between forwarding CANCELs that do not match any
943    transaction statefully (0, default value), statelessly (1) or dropping
944    them (2). Note that the statefull forwarding has an additional hidden
945    advantage: tm will be able to recognize INVITEs that arrive after their
946    CANCEL. Note also that this feature could be used to try a memory
947    exhaustion DOS attack against a proxy that authenticates all requests,
948    by continuously flooding the victim with CANCELs to random destinations
949    (since the CANCEL cannot be authenticated, each received bogus CANCEL
950    will create a new transaction that will live by default 30s).
951
952    Default value is 0.
953
954    Example 29. Set unmatched_cancel parameter
955 ...
956 modparam("tm", "unmatched_cancel", "2")
957 ...
958
959 1.4.30. ruri_matching (integer)
960
961    If set it will also try to match the request uri when doing pre-3261
962    transaction matching (the via branch parameter does not contain the
963    3261 cookie).
964
965    The only reason to have it not set is for interoperability with old,
966    broken implementations.
967
968    Default value is 1 (on).
969
970    Can be set at runtime, e.g.:
971         $ sercmd cfg.set_now_int tm ruri_matching 0
972
973    Example 30. Set ruri_matching parameter
974 ...
975 modparam("tm", "ruri_matching", 1)
976 ...
977
978 1.4.31. via1_matching (integer)
979
980    If set it will also try to match the topmost via when doing pre-3261
981    transaction matching (the via branch parameter does not contain the
982    3261 cookie).
983
984    The only reason to have it not set is for interoperability with old,
985    broken implementations.
986
987    Default value is 1 (on).
988
989    Can be set at runtime, e.g.:
990         $ sercmd cfg.set_now_int tm via1_matching 0
991
992    Example 31. Set via1_matching parameter
993 ...
994 modparam("tm", "via1_matching", 1)
995 ...
996
997 1.4.32. pass_provisional_replies (integer)
998
999    If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
1000    also for provisional replies.
1001
1002    Default value is 0 (off).
1003
1004    Can be set at runtime, e.g.:
1005         $ sercmd cfg.set_now_int tm pass_provisional_replies 1
1006
1007    Example 32. Set pass_provisional_replies parameter
1008 ...
1009 modparam("tm", "pass_provisional_replies", 1)
1010 ...
1011
1012 1.4.33. default_code (integer)
1013
1014    Default response code sent by t_reply() if it cannot retrieve its
1015    parameters (e.g. inexistent avp). Valid values are between 400 and 699.
1016
1017    Default value is 500.
1018
1019    Can be set at runtime, e.g.:
1020         $ sercmd cfg.set_now_int tm default_code 505
1021
1022    Example 33. Set default_code parameter
1023 ...
1024 modparam("tm", "default_code", 501)
1025 ...
1026
1027 1.4.34. default_reason (string)
1028
1029    Default SIP reason phrase sent by t_reply() if it cannot retrieve its
1030    parameters (e.g. inexistent avp).
1031
1032    Default value is "Server Internal Error".
1033
1034    Can be set at runtime, e.g.:
1035         $ sercmd cfg.set_now_string tm default_reason "Unknown error"
1036
1037    Example 34. Set default_reason parameter
1038 ...
1039 modparam("tm", "default_reason", "Unknown reason")
1040 ...
1041
1042 1.4.35. disable_6xx_block (integer)
1043
1044    If set tm will treat all the 6xx replies like normal replies (warning:
1045    this would be non-rfc conformant behaviour).
1046
1047    If not set (default) receiving a 6xx will cancel all the running
1048    parallel branches, will stop dns failover and forking. However serial
1049    forking using append_branch() in the failure_route will still work.
1050
1051    It can be overwritten on a per transaction basis using
1052    t_set_disable_6xx().
1053
1054    Default value is 0 (off, rfc conformant behaviour).
1055
1056    Can be set at runtime, e.g.:
1057         $ sercmd cfg.set_now_int tm disable_6xx_block 0
1058
1059    See also: t_set_disable_6xx().
1060
1061    Example 35. Set disable_6xx_block parameter
1062 ...
1063 modparam("tm", "disable_6xx_block", 1)
1064 ...
1065
1066 1.4.36. local_ack_mode (integer)
1067
1068    It controls where locally generated ACKs for 2xx replies to local
1069    transactions (transactions created via t_uac*() either thorugh the tm
1070    api or via RPC/mi/fifo) are sent.
1071
1072    It has 3 possible values:
1073      * 0 - the ACK destination is choosen according to the rfc: the next
1074        hop is found using the contact and the route set and then DNS
1075        resolution is used on it.
1076      * 1 - the ACK is sent to the same address as the corresponding INVITE
1077        branch.
1078      * 2 - the ACK is sent to the source of the 2xx reply.
1079
1080 Note
1081
1082    Mode 1 and 2 break the rfc, but are useful to deal with some simple UAs
1083    behind the NAT cases (no different routing for the ACK and the contact
1084    contains an address behind the NAT).
1085
1086    The default value is 0 (rfc conformant behaviour).
1087
1088    Can be set at runtime, e.g.:
1089         $ sercmd cfg.set_now_int tm local_ack_mode 0
1090
1091    Example 36. Set local_ack_mode parameter
1092 ...
1093 modparam("tm", "local_ack_mode", 1)
1094 ...
1095
1096 1.4.37. failure_reply_mode (integer)
1097
1098    It controls how branches are managed and replies are selected for
1099    failure_route handling: keep all, drop all, drop last branches in SIP
1100    serial forking handling.
1101
1102    To control per transaction see t_drop_replies().
1103
1104    It has 4 possible values:
1105      * 0 - all branches are kept, no matter a new leg of serial forking
1106        has been started. Beware that if the new leg fails, you may get in
1107        failure_route a reply code from a branch of previous serial forking
1108        legs (e.g., if in first leg you got a 3xx, then you handled the
1109        redirection in failure route, sent to a new destination and this
1110        one timeout, you will get again the 3xx). Use t_drop_replies() on
1111        per transaction fashion to control the behavior you want. It is the
1112        default behaviour comming from SER 2.1.x.
1113      * 1 - all branches are discarded by default. You can still overwrite
1114        the behaviour via t_drop_replies()
1115      * 2 - by default only the branches of previous leg of serial forking
1116        are discarded
1117      * 3 - all previous branches are discarded if there is a new serial
1118        forking leg. This is the default behaviour coming from Kamailio
1119        1.5.x. Use this mode if you don't want to handle in a per
1120        transaction fashion with t_drop_replies(). It ensures that you will
1121        get the winning reply from the branches of last serial forking step
1122        (e.g., if in first step you get 3xx, then you forward to a new
1123        destination, you will get in failure_route the reply coming from
1124        that destination or a local timeout).
1125
1126    The default value is 0.
1127
1128    Example 37. Set failure_reply_mode parameter
1129 ...
1130 modparam("tm", "failure_reply_mode", 3)
1131 ...
1132
1133 1.4.38. faked_reply_prio (integer)
1134
1135    It controls how branch selection is done. It allows to give a penalty
1136    to faked replies such as the infamous 408 on branch timeout.
1137
1138    Internally, every reply is assigned a priority between 0 (high prio)
1139    and 32000 (low prio). With this parameter the priority of fake replies
1140    can be adjusted.
1141      * 0 - disabled (default)
1142      * < 0 - priority is increased by given amount.
1143      * > 0 - priority is decreased by given amount. Do not make it higer
1144        than 10000 or faked replies will even loose from 1xx clsss replies.
1145
1146    The default value is 0.
1147
1148    To let received replies win from a locally generated 408, set this
1149    value to 2000.
1150
1151    Example 38. Set faked_reply_prio parameter
1152 ...
1153 modparam("tm", "faked_reply_prio", 2000)
1154 ...
1155
1156 1.4.39. local_cancel_reason (boolean)
1157
1158    Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1159    due to receiving a final reply. The reason header added will look like:
1160    "Reason: SIP;cause=<final_reply_code>".
1161
1162    Default value is 1 (enabled).
1163
1164    Can be set at runtime, e.g.:
1165         $ sercmd cfg.set_now_int tm local_cancel_reason 0
1166
1167    See also: e2e_cancel_reason.
1168
1169    Example 39. Set local_cancel_reason parameter
1170 ...
1171 modparam("tm", "local_cancel_reason", 0)
1172 ...
1173
1174 1.4.40. e2e_cancel_reason (boolean)
1175
1176    Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1177    due to a received CANCEL. If enabled the reason headers from received
1178    CANCELs will be copied into the generated hop-by-hop CANCELs.
1179
1180    Default value is 1 (enabled).
1181
1182    Can be changed at runtime, e.g.:
1183         $ sercmd cfg.set_now_int tm e2e_cancel_reason 0
1184
1185    See also: t_set_no_e2e_cancel_reason() and local_cancel_reason.
1186
1187    Example 40. Set e2e_cancel_reason parameter
1188 ...
1189 modparam("tm", "e2e_cancel_reason", 0)
1190 ...
1191
1192 1.5. Functions
1193
1194 1.5.1. t_relay([host, port])
1195
1196    Relay a message statefully either to the destination indicated in the
1197    current URI (if called without any parameters) or to the specified host
1198    and port. In the later case (host and port specified) the protocol used
1199    is the same protocol on which the message was received.
1200
1201    t_relay() is the statefull version for forward() while t_relay(host,
1202    port) is similar to forward(host, port).
1203
1204    In the forward to uri case (t_relay()), if the original URI was
1205    rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
1206    taken). The destination (including the protocol) is determined from the
1207    uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
1208    depending also on the dns options).
1209
1210    Returns a negative value on failure -- you may still want to send a
1211    negative reply upstream statelessly not to leave upstream UAC in lurch.
1212
1213    Example 41. t_relay usage
1214 ...
1215 if (!t_relay())
1216 {
1217     sl_reply_error();
1218     break;
1219 };
1220 ...
1221
1222 1.5.2. t_relay_to_udp([ip, port])
1223
1224    Relay a message statefully using a fixed protocol either to the
1225    specified fixed destination or to a destination derived from the
1226    message uri (if the host address and port are not specified). These
1227    along with t_relay are the functions most users want to use--all other
1228    are mostly for programming. Programmers interested in writing TM logic
1229    should review how t_relay is implemented in tm.c and how TM callbacks
1230    work.
1231
1232    Meaning of the parameters is as follows:
1233      * ip - IP address where the message should be sent.
1234      * port - Port number.
1235
1236    If no parameters are specified the message is sent to a destination
1237    derived from the message uri (using sip sepcific DNS lookups), but with
1238    the protocol corresponding to the function name.
1239
1240    Example 42. t_relay_to_udp usage
1241 ...
1242 if (src_ip==10.0.0.0/8)
1243         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
1244 else
1245         t_relay_to_tcp(); # relay to msg. uri, but over tcp
1246 ...
1247
1248 1.5.3. t_relay_to_tcp([ip, port])
1249
1250    See function t_relay_to_udp([ip, port]).
1251
1252 1.5.4. t_relay_to_tls([ip, port])
1253
1254    See function t_relay_to_udp([ip, port]).
1255
1256 1.5.5. t_relay_to_sctp([ip, port])
1257
1258    See function t_relay_to_udp([ip, port]).
1259
1260 1.5.6. t_on_failure(failure_route)
1261
1262    Sets failure routing block, to which control is passed after a
1263    transaction completed with a negative result but before sending a final
1264    reply. In the referred block, you can either start a new branch (good
1265    for services such as forward_on_no_reply) or send a final reply on your
1266    own (good for example for message silo, which received a negative reply
1267    from upstream and wants to tell upstream "202 I will take care of it").
1268    Note that the set of commands which are usable within failure_routes is
1269    strictly limited to rewriting URI, initiating new branches, logging,
1270    and sending stateful replies (t_reply). Any other commands may result
1271    in unpredictable behavior and possible server failure. Note that
1272    whenever failure_route is entered, uri is reset to value which it had
1273    on relaying. If it temporarily changed during a reply_route processing,
1274    subsequent reply_route will ignore the changed value and use again the
1275    original one.
1276
1277    Meaning of the parameters is as follows:
1278      * failure_route - Failure route block to be called.
1279
1280    Example 43. t_on_failure usage
1281 ...
1282 route {
1283     t_on_failure("1");
1284     t_relay();
1285 }
1286
1287 failure_route[1] {
1288     revert_uri();
1289     setuser("voicemail");
1290     append_branch();
1291 }
1292 ...
1293
1294    See test/onr.cfg for a more complex example of combination of serial
1295    with parallel forking.
1296
1297 1.5.7. t_on_reply(onreply_route)
1298
1299    Sets the reply routing block, to which control is passed when a reply
1300    for the current transaction is received. Note that the set of commands
1301    which are usable within onreply_routes is limited.
1302
1303    Meaning of the parameters is as follows:
1304      * onreply_route - Onreply route block to be called.
1305
1306    Example 44. t_on_reply usage
1307 ...
1308 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
1309 ...
1310 route {
1311         /* if natted */
1312         t_on_reply("1");
1313         t_relay();
1314 }
1315
1316 onreply_route[1] {
1317         if (status=~ "(183)|2[0-9][0-9]"){
1318                 force_rtp_proxy();
1319                 search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
1320 es');
1321         }
1322         if (nat_uac_test("1")){
1323                 fix_nated_contact();
1324         }
1325 }
1326
1327 1.5.8. t_on_branch(branch_route)
1328
1329    Sets the branch routing block, to which control is passed after forking
1330    (when a new branch is created). For now branch routes are intended only
1331    for last minute changes of the SIP messages (like adding new headers).
1332    Note that the set of commands which are usable within branch_routes is
1333    very limited. It is not possible to generate a reply.
1334
1335    Meaning of the parameters is as follows:
1336      * branch_route - branch route block to be called.
1337
1338    Example 45. t_on_branch usage
1339 ...
1340 route {
1341         t_on_branch("1");
1342         t_relay();
1343 }
1344
1345 branch_route[1] {
1346         if (uri=~"sip:[0-9]+"){
1347                 append_hf("P-Warn: numeric uri\r\n");
1348         }
1349 }
1350
1351 1.5.9. append_branch()
1352
1353    Similarly to t_fork_to, it extends destination set by a new entry. The
1354    difference is that current URI is taken as new entry.
1355
1356    Example 46. append_branch usage
1357 ...
1358 set_user("john");
1359 t_fork();
1360 set_user("alice");
1361 t_fork();
1362 t_relay();
1363 ...
1364
1365 1.5.10. t_newtran()
1366
1367    Creates a new transaction, returns a negative value on error. This is
1368    the only way a script can add a new transaction in an atomic way.
1369    Typically, it is used to deploy a UAS.
1370
1371    Example 47. t_newtran usage
1372 ...
1373 if (t_newtran()) {
1374     log("UAS logic");
1375     t_reply("999","hello");
1376 } else sl_reply_error();
1377 ...
1378
1379    See test/uas.cfg for more examples.
1380
1381 1.5.11. t_reply(code, reason_phrase)
1382
1383    Sends a stateful reply after a transaction has been established. See
1384    t_newtran for usage.
1385
1386    Meaning of the parameters is as follows:
1387      * code - Reply code number.
1388      * reason_phrase - Reason string.
1389
1390    Example 48. t_reply usage
1391 ...
1392 t_reply("404", "Not found");
1393 ...
1394
1395 1.5.12. t_lookup_request()
1396
1397    Checks if a transaction exists. Returns a positive value if so,
1398    negative otherwise. Most likely you will not want to use it, as a
1399    typical application of a look-up is to introduce a new transaction if
1400    none was found. However this is safely (atomically) done using
1401    t_newtran.
1402
1403    Example 49. t_lookup_request usage
1404 ...
1405 if (t_lookup_request()) {
1406     ...
1407 };
1408 ...
1409
1410 1.5.13. t_retransmit_reply()
1411
1412    Retransmits a reply sent previously by UAS transaction.
1413
1414    Example 50. t_retransmit_reply usage
1415 ...
1416 t_retransmit_reply();
1417 ...
1418
1419 1.5.14. t_release()
1420
1421    Remove transaction from memory (it will be first put on a wait timer to
1422    absorb delayed messages).
1423
1424    Example 51. t_release usage
1425 ...
1426 t_release();
1427 ...
1428
1429 1.5.15. t_forward_nonack([ip, port])
1430
1431    Mainly for internal usage -- forward a non-ACK request statefully.
1432    Variants of this functions can enforce a specific transport protocol.
1433
1434    Meaning of the parameters is as follows:
1435      * ip - IP address where the message should be sent.
1436      * port - Port number.
1437
1438    Example 52. t_forward_nonack usage
1439 ...
1440 t_forward_nonack("1.2.3.4", "5060");
1441 ...
1442
1443 1.5.16. t_forward_nonack_udp(ip, port)
1444
1445    See function t_forward_nonack([ip, port]).
1446
1447 1.5.17. t_forward_nonack_tcp(ip, port)
1448
1449    See function t_forward_nonack([ip, port]).
1450
1451 1.5.18. t_forward_nonack_tls(ip, port)
1452
1453    See function t_forward_nonack([ip, port]).
1454
1455 1.5.19. t_forward_nonack_sctp(ip, port)
1456
1457    See function t_forward_nonack([ip, port]).
1458
1459 1.5.20. t_set_fr(fr_inv_timeout [, fr_timeout])
1460
1461    Sets the fr_inv_timeout and optionally fr_timeout for the current
1462    transaction or for transactions created during the same script
1463    invocation, after calling this function. If the transaction is already
1464    created (e.g called after t_relay() or in an onreply_route) all the
1465    branches will have their final response timeout updated on-the-fly. If
1466    one of the parameters is 0, its value won't be changed.
1467
1468    Meaning of the parameters is as follows:
1469      * fr_inv_timeout - new final response timeout (in milliseconds) for
1470        INVITEs. See also fr_inv_timer.
1471        fr_timeout - new final response timeout (in milliseconds) for
1472        non-INVITE transaction, or INVITEs which haven't received yet a
1473        provisional response. See also fr_timer.
1474
1475    See also: fr_timer, fr_inv_timer, t_reset_fr().
1476
1477    Example 53. t_set_fr usage
1478 ...
1479 route {
1480         t_set_fr(10000); # set only fr invite timeout to 10s
1481         t_on_branch("1");
1482         t_relay();
1483 }
1484
1485 branch_route[1] {
1486         # if we are calling the pstn, extend the invite timeout to 50s
1487         # for all the branches, and set the no-reply-received timeout to 2s
1488         if (uri=~"sip:[0-9]+"){
1489                 t_set_fr(50000, 2000);
1490         }
1491 }
1492
1493 1.5.21. t_reset_fr()
1494
1495    Resets the fr_inv_timer and fr_timer for the current transaction to the
1496    default values (set using the tm module parameters fr_inv_timer and
1497    fr_timer).
1498
1499    It will effectively cancel any previous calls to t_set_fr for the same
1500    transaction.
1501
1502    See also: fr_timer, fr_inv_timer, t_set_fr.
1503
1504    Example 54. t_reset_fr usage
1505 ...
1506 route {
1507 ...
1508                 t_reset_fr();
1509 ...
1510 }
1511
1512 1.5.22. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1513
1514    Sets the maximum lifetime for the current INVITE or non-INVITE
1515    transaction, or for transactions created during the same script
1516    invocation, after calling this function (that's why it takes values for
1517    both INVITE and non-INVITE). If one of the parameters is 0, its value
1518    won't be changed.
1519
1520    It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
1521
1522    Meaning of the parameters is as follows:
1523      * inv_lifetime - maximum INVITE transaction lifetime (in
1524        milliseconds). See also max_inv_lifetime.
1525        noninv_lifetime - maximum non-INVITE transaction lifetime (in
1526        milliseconds). See also max_noninv_lifetime.
1527
1528    See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
1529
1530    Example 55. t_set_max_lifetime usage
1531 ...
1532 route {
1533     if (src_ip=1.2.3.4)
1534         t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
1535     else
1536         t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
1537                                           # the current transaction is an
1538                                           # INVITE and to 15s if not
1539 }
1540
1541 1.5.23. t_reset_max_lifetime()
1542
1543    Resets the the maximum lifetime for the current INVITE or non-INVITE
1544    transaction to the default value (set using the tm module parameter
1545    max_inv_lifetime or max_noninv_lifetime).
1546
1547    It will effectively cancel any previous calls to t_set_max_lifetime for
1548    the same transaction.
1549
1550    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
1551
1552    Example 56. t_reset_max_lifetime usage
1553 ...
1554 route {
1555 ...
1556                 t_reset_max_lifetime();
1557 ...
1558 }
1559
1560 1.5.24. t_set_retr(retr_t1_interval, retr_t2_interval)
1561
1562    Sets the retr_t1_interval and retr_t2_interval for the current
1563    transaction or for transactions created during the same script
1564    invocation, after calling this function. If one of the parameters is 0,
1565    it's value won't be changed. If the transaction is already created (e.g
1566    called after t_relay() or in an onreply_route) all the existing
1567    branches will have their retransmissions intervals updated on-the-fly:
1568    if the retransmission interval for the branch has not yet reached T2
1569    the interval will be reset to retr_t1_interval, else to
1570    retr_t2_interval. Note that the change will happen after the current
1571    interval expires (after the next retransmission, the next-next
1572    retransmission will take place at retr_t1_interval or
1573    retr_t2_interval). All new branches of the same transaction will start
1574    with the new values. This function will work even if it's called in the
1575    script before a transaction creating function (e.g.: t_set_retr(500,
1576    4000); t_relay()). All new transaction created after this function
1577    call, during the same script invocation will use the new values. Note
1578    that this function will work only if tm is compile with
1579    -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
1580    bytes).
1581
1582    Meaning of the parameters is as follows:
1583      * retr_t1_interval - new T1 retransmission interval (in
1584        milliseconds). See also retr_t1_timeout.
1585        retr_t2_interval - new T2 (or maximum) retransmission interval (in
1586        milliseconds). See also retr_t2_timeout.
1587
1588    See also: retr_timer1, retr_timer2, t_reset_retr().
1589
1590    Example 57. t_set_retr usage
1591 ...
1592 route {
1593         t_set_retr(250, 0); # set only T1 to 250 ms
1594         t_on_branch("1");
1595         t_relay();
1596 }
1597
1598 branch_route[1] {
1599         # if we are calling the a remote pstn, extend T1 and decrease T2
1600         # for all the branches
1601         if (uri=~"sip:[0-9]+"){
1602                 t_set_retr(500, 2000);
1603         }
1604 }
1605
1606 1.5.25. t_reset_retr()
1607
1608    Resets the retr_timer1 and retr_timer2 for the current transaction to
1609    the default values (set using the tm module parameters retr_timer1 and
1610    retr_timer2).
1611
1612    It will effectively cancel any previous calls to t_set_retr for the
1613    same transaction.
1614
1615    See also: retr_timer1, retr_timer2, t_set_retr.
1616
1617    Example 58. t_reset_retr usage
1618 ...
1619 route {
1620 ...
1621                 t_reset_retr();
1622 ...
1623 }
1624
1625 1.5.26. t_set_auto_inv_100(0|1)
1626
1627    Switch automatically sending 100 replies to INVITEs on/off on a per
1628    transaction basis. It overrides the auto_inv_100 value for the current
1629    transaction.
1630
1631    See also: auto_inv_100.
1632
1633    Example 59. t_set_auto_inv_100 usage
1634 ...
1635 route {
1636 ...
1637         if (src_ip==1.2.3.0/24)
1638                 t_set_auto_inv_100(0); # turn off automatic 100 replies
1639 ...
1640 }
1641
1642 1.5.27. t_branch_timeout()
1643
1644    Returns true if the failure route is executed for a branch that did
1645    timeout. It can be used only from the failure_route.
1646
1647    Example 60. t_branch_timeout usage
1648 ...
1649 failure_route[0]{
1650         if (t_branch_timeout()){
1651                 log("timeout\n");
1652                 # ...
1653         }
1654 }
1655
1656 1.5.28. t_branch_replied()
1657
1658    Returns true if the failure route is executed for a branch that did
1659    receive at least one reply in the past (the "current" reply is not
1660    taken into account). It can be used only from the failure_route.
1661
1662    Example 61. t_branch_replied usage
1663 ...
1664 failure_route[0]{
1665         if (t_branch_timeout()){
1666                 if (t_branch_replied())
1667                         log("timeout after receiving a reply (no answer?)\n");
1668                 else
1669                         log("timeout, remote side seems to be down\n");
1670                 # ...
1671         }
1672 }
1673
1674 1.5.29. t_any_timeout()
1675
1676    Returns true if at least one of the current transactions branches did
1677    timeout.
1678
1679    Example 62. t_any_timeout usage
1680 ...
1681 failure_route[0]{
1682         if (!t_branch_timeout()){
1683                 if (t_any_timeout()){
1684                         log("one branch did timeout\n");
1685                         sl_send_reply("408", "Timeout");
1686                 }
1687         }
1688 }
1689
1690 1.5.30. t_any_replied()
1691
1692    Returns true if at least one of the current transactions branches did
1693    receive some reply in the past. If called from a failure or onreply
1694    route, the "current" reply is not taken into account.
1695
1696    Example 63. t_any_replied usage
1697 ...
1698 onreply_route[0]{
1699         if (!t_any_replied()){
1700                 log("first reply received\n");
1701                 # ...
1702         }
1703 }
1704
1705 1.5.31. t_grep_status("code")
1706
1707    Returns true if "code" is the final reply received (or locally
1708    generated) in at least one of the current transactions branches.
1709
1710    Example 64. t_grep_status usage
1711 ...
1712 onreply_route[0]{
1713         if (t_grep_status("486")){
1714                 /* force a 486 reply, even if this is not the winning branch */
1715                 t_reply("486", "Busy");
1716         }
1717 }
1718
1719 1.5.32. t_is_canceled()
1720
1721    Returns true if the current transaction was canceled.
1722
1723    Example 65. t_is_canceled usage
1724 ...
1725 failure_route[0]{
1726         if (t_is_canceled()){
1727                 log("transaction canceled\n");
1728                 # ...
1729         }
1730 }
1731
1732 1.5.33. t_is_expired()
1733
1734    Returns true if the current transaction has already been expired, i.e.
1735    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
1736
1737    Example 66. t_is_expired usage
1738 ...
1739 failure_route[0]{
1740         if (t_is_expired()){
1741                 log("transaction expired\n");
1742                 # There is no point in adding a new branch.
1743         }
1744 }
1745
1746 1.5.34. t_relay_cancel()
1747
1748    Forwards the CANCEL if the corresponding INVITE transaction exists. The
1749    function is supposed to be used at the very beginning of the script,
1750    because the CANCELs can be caught and the rest of the script can be
1751    bypassed this way. Do not disable reparse_invite module parameter, and
1752    call t_relay_cancel() right after the sanity tests.
1753
1754    Return value is 0 (drop) if the corresponding INVITE was found and the
1755    CANCELs were successfully sent to the pending branches, true if the
1756    INVITE was not found, and false in case of any error.
1757
1758    Example 67. t_relay_cancel usage
1759 if (method == CANCEL) {
1760         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
1761                                   # nothing to do
1762
1763                 # corresponding INVITE transaction found but error occurred
1764                 sl_reply("500", "Internal Server Error");
1765                 drop;
1766         }
1767         # bad luck, corresponding INVITE transaction is missing,
1768         # do the same as for INVITEs
1769 }
1770
1771 1.5.35. t_lookup_cancel([1])
1772
1773    Returns true if the corresponding INVITE transaction exists for a
1774    CANCEL request. The function can be called at the beginning of the
1775    script to check whether or not the CANCEL can be immediately forwarded
1776    bypassing the rest of the script. Note however that t_relay_cancel
1777    includes t_lookup_cancel as well, therefore it is not needed to
1778    explicitly call this function unless something has to be logged for
1779    example.
1780
1781    If the function parameter (optional) is set to 1, the message flags are
1782    overwritten with the flags of the INVITE. isflagset() can be used to
1783    check the flags of the previously forwarded INVITE in this case.
1784
1785    Example 68. t_lookup_cancel usage
1786 if (method == CANCEL) {
1787         if (t_lookup_cancel()) {
1788                 log("INVITE transaction exists");
1789                 if (!t_relay_cancel()) {  # implicit drop if
1790                                           # relaying was successful,
1791                                           # nothing to do
1792
1793                         # corresponding INVITE transaction found
1794                         # but error occurred
1795                         sl_reply("500", "Internal Server Error");
1796                         drop;
1797                 }
1798         }
1799         # bad luck, corresponding INVITE transaction is missing,
1800         # do the same as for INVITEs
1801 }
1802
1803 1.5.36. t_drop_replies([mode])
1804
1805    Drops all the previously received replies in failure_route block to
1806    make sure that none of them is picked up again.
1807
1808    The parameter 'mode' controls which replies are dropped: 'a' or missing
1809    - all replies are dropped; 'l' - replies received for last set of
1810    branches are dropped; 'n' - no reply is dropped.
1811
1812    Dropping replies works only if a new branch is added to the
1813    transaction, or it is explicitly replied in the script!
1814
1815    Example 69. t_drop_replies() usage
1816 ...
1817 failure_route[0]{
1818         if (t_check_status("5[0-9][0-9]")){
1819                 # I do not like the 5xx responses,
1820                 # so I give another chance to "foobar.com",
1821                 # and I drop all the replies to make sure that
1822                 # they are not forwarded to the caller.
1823                 t_drop_replies();
1824
1825                 rewritehostport("foobar.com");
1826                 append_branch();
1827                 t_relay();
1828         }
1829 }
1830
1831 1.5.37. t_save_lumps()
1832
1833    Forces the modifications of the processed SIP message to be saved in
1834    shared memory before t_relay() is called. The new branches which are
1835    created in failure_route will contain the same modifications, and any
1836    other modification after t_save_lumps() will be lost.
1837
1838    Note that t_relay() automatically saves the modifications when it is
1839    called the first time, there is no need for t_save_lumps() unless
1840    message changes between t_save_lumps() and t_relay() must not be
1841    propagated to failure_route.
1842
1843    The transaction must be created by t_newtran() before calling
1844    t_save_lumps().
1845
1846    Example 70. t_save_lumps() usage
1847 route {
1848         ...
1849         t_newtran();
1850         append_hf("hf1: my first header\r\n");
1851         ...
1852         t_save_lumps();
1853         append_hf("hf2: my second header\r\n");
1854         ...
1855         t_on_failure("1");
1856         t_relay();
1857 }
1858
1859 failure_route[1] {
1860         append_branch();
1861         append_hf("hf3: my third header\r\n");
1862         #
1863         # This branch contains hf1 and hf3, but does
1864         # not contain hf2 header.
1865         # hf2 would be also present here without
1866         # t_save_lumps().
1867         ...
1868         t_relay();
1869 }
1870
1871 1.5.38. t_load_contacts()
1872
1873    This is the first of the two functions that can be used to implement
1874    serial/parallel forking based on the q value of individual branches in
1875    a destination set.
1876
1877    The function t_load_contacts() takes all branches from the current
1878    destination set and encodes them into the AVP whose name or ID is
1879    configured with the parameter contacts_avp. Note that you have to
1880    configure this parameter before you can use the function, the parameter
1881    is set to NULL by default, which disables the function.
1882
1883    If the destination set contains only one branch (the Request-URI) or if
1884    all branches have the same q value then the function does nothing to
1885    minimize performance impact. In such case all branches should be tried
1886    in parallel and that is the default mode of operation of functions like
1887    t_relay(), so there is no need to create the AVP or sort the branches.
1888
1889    If the current destination set contains more than one branch and not
1890    all branches have the same q value then the function sorts them
1891    according to the increasing value of the q parameter. The resulting
1892    sorted list of branches is then encoded into the AVP.
1893
1894    The q parameter contains a value from a range of 0 to 1.0 and it
1895    expresses relative preferrence of the branch among all branches in the
1896    destination set. The higher the q value the more preferrence the user
1897    agent gave to the branch. Branches with higher q values will be tried
1898    first when serial forking takes place.
1899
1900    After that the function clears all branches and you have to call
1901    t_next_contacts to retrieve them sorted according to their q value.
1902    Note that if you use t_load_contacts then you also have to use
1903    t_next_contacts before calling t_relay.
1904
1905    The AVP created by the function may contain multiple values, with one
1906    encoded branch per value. The first value will contain the branch with
1907    the highest q value. Each value contains the Request-URI, the
1908    destination URI, the path vector, the outgoing socket description and
1909    branch flags. All these fields are delimited with the LF character.
1910
1911    The function returns 1 if loading of contacts succeeded or there was
1912    nothing to do. Returns -1 on error (see syslog).
1913
1914    This function can be used from REQUEST_ROUTE.
1915
1916    Example 71. t_load_contacts usage
1917 ...
1918 if (!t_load_contacts()) {
1919         sl_send_reply("500", "Server Internal Error - Cannot load contacts");
1920         exit;
1921 };
1922 ...
1923
1924 1.5.39. t_next_contacts()
1925
1926    The function t_next_contacts is the second of the two functions that
1927    can be used to implement serial/parallel forking based on the q value
1928    of individual branches in a destination set.
1929
1930    This function takes the contact_avp created by t_load_contacts and
1931    extracts branches with highest q value from it into the destination set
1932    when called for the first time. When you call the function second time
1933    it extracts branches with lower q value, and so on until all branches
1934    have been extracted. At each call, Request URI is rewritten with first
1935    branch and the remaining branches (if any) are added as branches. Then
1936    these "used" branches are remove from the AVP.
1937
1938    The function does nothing if there are no contact_avp values.
1939
1940    The function returns 1 if the AVP was not empty and a destination set
1941    was successfully added, returns -2 if contact_avp was empty and thus
1942    there was nothing to do, and returns -1 in case of an error (see
1943    syslog). This function can be used from REQUEST_ROUTE and
1944    FAILURE_ROUTE.
1945
1946    Note that if use use t_load_contacts and t_next_contacts functions then
1947    you should also set the value of restart_fr_on_each_reply parameter to
1948    0. If you do not do that then it can happen that a broken user agent
1949    that retransmits 180 periodically will keep resetting the fr_inv_timer
1950    value and serial forking never happens.
1951
1952    Before calling t_relay(), you can check if the previous call of
1953    next_contacts() consumed all branches by checking if contact_avp is not
1954    anymore set. Based on that test, you can then use t_set_fr() function
1955    to set timers according to your needs.
1956
1957    Example 72. t_next_contacts usage
1958 ...
1959 # First call after t_load_contacts() when transaction does not exist yet
1960 # and contacts should be available
1961 if (!t_next_contacts()) {
1962         sl_send_reply("500", "Server Internal Error - Cannot get contacts");
1963 } else {
1964         t_relay();
1965 };
1966 ...
1967 # Following call, when transaction exists and there may or may not be
1968 # contacts left
1969 if (!t_next_contacts()) {
1970         t_reply("408", "Request Timeout");
1971 } else {
1972         t_relay();
1973 };
1974 ...
1975
1976 1.5.40. t_check_trans()
1977
1978    t_check_trans() can be used to quickly check if a message belongs or is
1979    related to a transaction. It behaves differently for different types of
1980    messages:
1981      * For a SIP Reply it returns true if the reply belongs to an existing
1982        transaction and false otherwise.
1983      * For a CANCEL it behaves exactly as t_lookup_cancel(): returns true
1984        if a corresponding INVITE transaction exists for the CANCEL and
1985        false otherwise.
1986      * For ACKs to negative replies or for ACKs to local transactions it
1987        will terminate the script if the ACK belongs to a transaction (it
1988        would make very little sense to process an ACK to a negative reply
1989        for an existing transaction in some other way then to simply pass
1990        it to tm) or return false if not.
1991      * For end-to-end ACKs (ACKs to 2xx responses for forwarded INVITE
1992        transactions) it will return true if the corresponding INVITE
1993        transaction is found and still active and false if not.
1994
1995 Note
1996        Note that the e2e ACK matching is more of a hint then a certainty.
1997        A delayed e2e ACK might arrive after the transaction wait time
1998        elapses, when the INVITE transaction no longer exists and thus
1999        would not match anything. There are also cases when tm would not
2000        keep all the information needed for e2e ACK matching (since this is
2001        not needed for a statefull proxy and it requires additional memory,
2002        tm will not keep this information unless needed by some other
2003        module or callbacks).
2004      * For other requests (non ACKs and non CANCELs), it will terminate
2005        the script for retransmissions and return false for new requests
2006        (for which no transaction exists yet).
2007
2008 Note
2009
2010    An important difference from kamailio version is that for an ACK to
2011    negative reply or for a local transaction, the script execution will be
2012    immediately stopped and the message handled by tm, instead of returning
2013    true.
2014
2015    t_check_trans() functionality for requests, except for the e2e ACK
2016    matching, can be replicated in the script using t_lookup_cancel() and
2017    t_lookup_request().
2018
2019    See also: t_lookup_request(), t_lookup_cancel().
2020
2021    Example 73. t_check_trans usage
2022 if ( method == "CANCEL" && !t_check_trans())
2023         sl_reply("403", "cancel out of the blue forbidden");
2024 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
2025
2026 1.5.41. t_set_disable_6xx(0|1)
2027
2028    Turn off/on 6xx replies special rfc conformant handling on a per
2029    transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
2030    treated like normal replies.
2031
2032    It overrides the disable_6xx_block value for the current transaction.
2033
2034    See also: disable_6xx_block.
2035
2036    Example 74. t_set_disable_6xx usage
2037 ...
2038 route {
2039 ...
2040         if (src_ip==1.2.3.4) # bad user agent that sends 603
2041                 t_set_disable_6xx(1); # turn off 6xx special handling
2042 ...
2043 }
2044
2045 1.5.42. t_set_disable_failover(0|1)
2046
2047    Turn off/on dns failover on a per transaction basis.
2048
2049    See also: use_dns_failover.
2050
2051    Example 75. t_set_disable_failover usage
2052 ...
2053 route {
2054 ...
2055         if (uri=~"@foo.bar$")
2056                 t_set_disable_failover(1); # turn off dns failover
2057 ...
2058 }
2059
2060 1.5.43. t_replicate(params)
2061
2062    Replicate the SIP request to a specific address.
2063
2064    There are several function prototypes:
2065      * t_replicate(uri),
2066      * t_replicate(host, port),
2067      * t_replicat_udp(host, port)
2068      * t_replicate_tcp(host, port)
2069      * t_replicate_tls(host, port)
2070      * t_replicate_sctp(host, port)
2071      * t_replicate_to(proto, hostport)
2072
2073    Meaning of the parameters is as follows:
2074      * uri - SIP URI where the message should be sent. It can be given via
2075        a script variable.
2076      * host - host address where the message should be sent.
2077      * port - port number.
2078      * proto - transport protocol to be used.
2079      * hostport - address in "host:port" format. It can be given via an
2080        AVP.
2081
2082    Example 76. t_replicate usage
2083 ...
2084 # sent to 1.2.3.4:5060 over tcp
2085 t_replicate("sip:1.2.3.4:5060;transport=tcp");
2086
2087 # sent to 1.2.3.4:5061 over tls
2088 $var(h) = "1.2.3.4:5061";
2089 t_replicate("sip:$var(h);transport=tls");
2090
2091 # sent to 1.2.3.4:5060 over udp
2092 t_replicate_to_udp("1.2.3.4", "5060");
2093 ...
2094
2095 1.5.44. t_relay_to(proxy, flags)
2096
2097    Forward the SIP request to a specific address, controlling internal
2098    behavior via flags.
2099
2100    There are several function prototypes:
2101      * t_relay_to(),
2102      * t_relay_to(proxy),
2103      * t_relay_to(flags)
2104      * t_relay_to(proxy, flags)
2105
2106    Meaning of the parameters is as follows:
2107      * proxy - address where the request should be sent. Format is:
2108        "proto:host:port" - any of proto or port can be ommitted, along
2109        with the semicolon after or before.
2110      * flags - bitmask integer value to control the internal behavior.
2111        Bits can be:
2112           + 0x01 - do not generate 100 reply.
2113           + 0x02 - do not generate reply on internal error (NOTE: has no
2114             effect anymore).
2115           + 0x04 - disable dns failover.
2116
2117    Example 77. t_replicate usage
2118 ...
2119 # sent to 1.2.3.4:5060 over tcp
2120 t_relay_to("tcp:1.2.3.4:5060");
2121
2122 # sent to 1.2.3.4 over tls
2123 t_relay_to("tls:1.2.3.4");
2124
2125 # sent to dst URI or R-URI without a 100 reply
2126 t_relay_to("0x01");
2127 ...
2128
2129 1.5.45. t_set_no_e2e_cancel_reason(0|1)
2130
2131    Enables/disables reason header (RFC 3326) copying from the triggering
2132    received CANCEL to the generated hop-by-hop CANCEL. 0 enables and 1
2133    disables.
2134
2135    It overrides the e2e_cancel_reason setting (module parameter) for the
2136    current transaction.
2137
2138    See also: e2e_cancel_reason.
2139
2140    Example 78. t_set_no_e2e_cancel_reason usage
2141 ...
2142 route {
2143 ...
2144         if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
2145                 t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header c
2146 opying
2147 ...
2148 }
2149
2150 1.5.46. t_is_set(target)
2151
2152    Return true if the attribute specified by 'target' is set for
2153    transaction.
2154
2155    The target parameter can be:
2156      * branch_route - the function returns true if a branch route is set
2157        to be executed.
2158      * failure_route - the function returns true if a failure route is set
2159        to be executed.
2160      * onreply_route - the function returns true if an onreply route is
2161        set to be executed.
2162
2163    Example 79. t_replicate usage
2164 ...
2165 if(!t_is_set("failure_route"))
2166     LM_DBG("no failure route will be executed for current transaction\n");
2167 ...
2168
2169 1.6. TM Module API
2170
2171    There are applications which would like to generate SIP transactions
2172    without too big involvement in SIP stack, transaction management, etc.
2173    An example of such an application is sending instant messages from a
2174    website. To address needs of such apps, SIP-router accepts requests for
2175    new transactions via the management interface. If you want to enable
2176    this feature, start the management interface server by configuring the
2177    proper modules.
2178
2179    An application can easily launch a new transaction by writing a
2180    transaction request to this interface. The request must follow very
2181    simple format, which for the basic FIFO interface is
2182  :t_uac_from:[<file_name>]\n
2183  <method>\n
2184  <sender's uri>\n
2185  <dst uri>\n
2186  <CR_separated_headers>\n
2187  <body>\n
2188  .\n
2189  \n
2190
2191    (Filename is to where a report will be dumped. ser assumes /tmp as
2192    file's directory.)
2193
2194    Note the request write must be atomic, otherwise it might get
2195    intermixed with writes from other writers. You can easily use it via
2196    Unix command-line tools, see the following example:
2197 [jiri@bat jiri]$ cat > /tmp/ser_fifo
2198 :t_uac_from:xxx
2199 MESSAGE
2200 sip:sender@iptel.org
2201 sip:mrx@iptel.org
2202 header:value
2203 foo:bar
2204 bznk:hjhjk
2205 p_header: p_value
2206
2207 body body body
2208 yet body
2209 end of body
2210 .
2211
2212    or cat test/transaction.fifo > /tmp/ser_fifo
2213
2214 1.6.1. Defines
2215
2216      * ACK_TAG enables stricter matching of acknowledgments including
2217        to-tags. Without it, to-tags are ignored. It is disabled by default
2218        for two reasons:
2219           + It eliminates an unlikely race condition in which
2220             transaction's to-tag is being rewritten by a 200 OK whereas an
2221             ACK is being looked up by to-tag.
2222           + It makes UACs happy who set wrong to-tags.
2223        It should not make a difference, as there may be only one negative
2224        reply sent upstream and 200/ACKs are not matched as they constitute
2225        another transaction. It will make no difference at all when the new
2226        magic cookie matching is enabled anyway.
2227      * CANCEL_TAG similarly enables strict matching of CANCELs including
2228        to-tags--act of mercy to UACs, who screw up the to-tags (however,
2229        it still depends on how forgiving the downstream UAS is). Like with
2230        ACK_TAG, all this complex transactions matching goes with RFC3261's
2231        magic cookie away anyway.
2232
2233 1.6.2. Functions
2234
2235 1.6.2.1. register_tmcb(cb_type, cb_func)
2236
2237    For programmatic use only--register a function to be called back on an
2238    event. See t_hooks.h for more details.
2239
2240    Meaning of the parameters is as follows:
2241      * cb_type - Callback type.
2242      * cb_func - Callback function.
2243
2244 1.6.2.2. load_tm(*import_structure)
2245
2246    For programmatic use only--import exported TM functions. See the acc
2247    module for an example of use.
2248
2249    Meaning of the parameters is as follows:
2250      * import_structure - Pointer to the import structure.
2251
2252 1.6.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
2253 unsigned int *label)
2254
2255    For programmatic use only. This function together with t_continue() can
2256    be used to implement asynchronous actions: t_suspend() saves the
2257    transaction, returns its identifiers, and t_continue() continues the
2258    SIP request processing. (The request processing does not continue from
2259    the same point in the script, a separate route block defined by the
2260    parameter of t_continue() is executed instead. The reply lock is held
2261    during the route block execution.) FR timer is ticking while the
2262    transaction is suspended, and the transaction's failure route is
2263    executed if t_continue() is not called in time.
2264
2265    Missing: message lumps are saved by t_suspend() and are not updated by
2266    the subsequent t_relay(). This means that the modifications made
2267    between them are lost.
2268
2269    Meaning of the parameters is as follows:
2270      * msg - SIP message pointer.
2271      * hash_index - transaction identifier.
2272      * label - transaction identifier.
2273
2274    Return value: 0 - success, <0 - error.
2275
2276    Usage: Allocate a memory block for storing the transaction identifiers
2277    (hash_index and label), and for storing also any variable related to
2278    the async query. Before calling t_suspend(), register for the following
2279    callbacks, and pass the pointer to the allocated shared memory as a
2280    parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN (in
2281    case of INVITE transaction). The async operation can be cancelled, if
2282    it is still pending, when TMCB_ON_FAILURE or TMCB_E2ECANCEL_IN is
2283    called. TMCB_DESTROY is suitable to free the shared memory allocated
2284    for the async and SIP transaction identifiers. Once the async query
2285    result is available call t_continue(), see below. The SIP transaction
2286    must exist before calling t_suspend(), and the module function calling
2287    t_suspend() should return 0 to make sure that the script processing
2288    does not continue.
2289
2290 1.6.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct
2291 action *route)
2292
2293    For programmatic use only. This function is the pair of t_suspend(),
2294    and is supposed to be called when the asynchronous query result is
2295    available. The function executes a route block with the saved SIP
2296    message. It is possible to add more branches to the transaction, or
2297    send a reply from the route block.
2298
2299    Meaning of the parameters is as follows:
2300      * hash_index - transaction identifier.
2301      * label - transaction identifier.
2302      * route - route block to execute.
2303
2304    Return value: 0 - success, <0 - error.
2305
2306 1.6.2.5. int t_cancel_suspend(unsigned int hash_index, unsigned int label)
2307
2308    For programmatic use only. This function is for revoking t_suspend()
2309    from the same process as it was executed before. t_cancel_suspend() can
2310    be used when something fails after t_suspend() has already been
2311    executed and it turns out that the transcation should not have been
2312    suspended. The function cancels the FR timer of the transacation.
2313
2314    The message lumps are saved by t_suspend() which cannot be restored.
2315
2316    Meaning of the parameters is as follows:
2317      * hash_index - transaction identifier.
2318      * label - transaction identifier.
2319
2320    Return value: 0 - success, <0 - error.