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