tm: docs: reason header modparams and script function
[sip-router] / modules / tm / doc / functions.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <section id="tm.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6     <sectioninfo>
7         <revhistory>
8             <revision>
9                 <revnumber>$Revision$</revnumber>
10                 <date>$Date$</date>
11             </revision>
12         </revhistory>
13     </sectioninfo>
14
15     <title>Functions</title>
16
17     <section id="t_relay_to_udp">
18         <title>
19             <function>t_relay_to_udp(ip, port)</function>,
20             <function>t_relay_to_udp()</function>,
21             <function>t_relay_to_tcp(ip, port)</function>
22             <function>t_relay_to_tcp()</function>
23             <function>t_relay_to_tls(ip, port)</function>
24             <function>t_relay_to_tls()</function>
25             <function>t_relay_to_sctp(ip, port)</function>
26             <function>t_relay_to_sctp()</function>
27         </title>
28         <para>
29             Relay a message statefully using a fixed protocol either to the 
30                  specified fixed destination or to a destination derived from the 
31                  message uri (if the host address and port are not specified).
32                  These along with
33             <function>t_relay</function> are the functions most users want to
34             use--all other are mostly for programming. Programmers interested
35             in writing <acronym>TM</acronym> logic should review how t_relay is
36             implemented in tm.c and how <acronym>TM</acronym> callbacks work.
37         </para>
38         <para>Meaning of the parameters is as follows:</para>
39         <itemizedlist>
40             <listitem>
41                 <para><emphasis>ip</emphasis> - IP address where the message should be sent.
42                 </para>
43             </listitem>
44             <listitem>
45                 <para><emphasis>port</emphasis> - Port number.
46                 </para>
47             </listitem>
48         </itemizedlist>
49         <para>If no parameters are specified the message is sent to a destination
50          derived from the message uri (using sip sepcific DNS lookups), but with 
51          the protocol corresponding to the function name.</para>
52         <example>
53             <title><function>t_relay_to_udp</function> usage</title>
54             <programlisting>
55 ...
56 if (src_ip==10.0.0.0/8)
57         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
58 else
59         t_relay_to_tcp(); # relay to msg. uri, but over tcp
60 ...
61             </programlisting>
62         </example>
63     </section>
64
65     <section id="t_relay">
66         <title>
67             <function>t_relay()</function>
68             <function>t_relay(host, port)</function>
69         </title>
70         <para>
71             Relay a message statefully either to the destination indicated in the
72                 current URI (if called without any parameters) or to the specified 
73                 host and port. In the later case (host and port specified) the protocol
74                  used is the same protocol on which the message was received.
75         </para>
76         <para>
77                 <function>t_relay()</function> is the statefull version for 
78                 <function>forward(uri:host, uri:port)</function>
79                 while <function>t_relay(host, port)</function> is similar to 
80                 <function>forward(host, port)</function>.
81         </para>
82         <para>
83                 In the forward to uri case (<function>t_relay()</function>), if the
84             original URI was rewritten (by UsrLoc, RR, strip/prefix, etc.) the new
85                 URI will be taken). The destination (including the protocol) is 
86                 determined from the uri, using SIP specific DNS resolving if needed
87                 (NAPTR, SRV a.s.o depending also on the dns options).
88         </para>
89         <para>
90                 Returns a negative value on failure--you may still want to send a
91             negative reply upstream statelessly not to leave upstream UAC in lurch.
92         </para>
93         <example>
94             <title><function>t_relay</function> usage</title>
95             <programlisting>
96 ...
97 if (!t_relay()) 
98
99     sl_reply_error(); 
100     break; 
101 };
102 ...
103             </programlisting>
104         </example>
105     </section>
106     
107     <section id="t_on_failure">
108         <title>
109             <function>t_on_failure(failure_route)</function>
110         </title>
111         <para>
112             Sets failure routing block, to which control is passed after a
113             transaction completed with a negative result but before sending a
114             final reply. In the referred block, you can either start a new
115             branch (good for services such as forward_on_no_reply) or send a
116             final reply on your own (good for example for message silo, which
117             received a negative reply from upstream and wants to tell upstream
118             "202 I will take care of it"). Note that the set of
119             commands which are usable within failure_routes is strictly limited to
120             rewriting URI, initiating new branches, logging, and sending
121             stateful replies (<function>t_reply</function>). Any other commands
122             may result in unpredictable behavior and possible server
123             failure. Note that whenever failure_route is entered, uri is reset to
124             value which it had on relaying. If it temporarily changed during a
125             reply_route processing, subsequent reply_route will ignore the
126             changed value and use again the original one.
127         </para>
128         <para>Meaning of the parameters is as follows:</para>
129         <itemizedlist>
130             <listitem>
131                 <para><emphasis>failure_route</emphasis> - Failure route block to be called.
132                 </para>
133             </listitem>
134         </itemizedlist>
135         <example>
136             <title><function>t_on_failure</function> usage</title>
137             <programlisting>
138 ...
139 route { 
140     t_on_failure("1"); 
141     t_relay(); 
142
143
144 failure_route[1] {
145     revert_uri(); 
146     setuser("voicemail"); 
147     append_branch(); 
148 }
149 ...
150             </programlisting>
151         </example>
152         <para>
153             See <filename>test/onr.cfg</filename> for a more complex example of
154             combination of serial with parallel forking.
155         </para>
156     </section>
157  
158          <section id="t_on_reply">
159         <title>
160             <function>t_on_reply(onreply_route)</function>
161         </title>
162         <para>
163             Sets the reply routing block, to which control is passed when a
164             reply for the current transaction is received.
165             Note that the set of commands which are usable within onreply_routes is
166              limited.
167         </para>
168         <para>Meaning of the parameters is as follows:</para>
169         <itemizedlist>
170             <listitem>
171                 <para><emphasis>onreply_route</emphasis> - Onreply route block to be
172                         called.
173                 </para>
174             </listitem>
175         </itemizedlist>
176         <example>
177             <title><function>t_on_reply</function> usage</title>
178             <programlisting>
179 ...
180 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
181 ...
182 route { 
183         /* if natted */
184         t_on_reply("1"); 
185         t_relay(); 
186
187
188 onreply_route[1] {
189         if (status=~ "(183)|2[0-9][0-9]"){
190                 force_rtp_proxy();
191                 search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=yes');
192         }
193         if (nat_uac_test("1")){
194                 fix_nated_contact();
195         }
196 }
197             </programlisting>
198         </example>
199         </section>
200
201         <section id="t_on_branch">
202         <title>
203             <function>t_on_branch(branch_route)</function>
204         </title>
205         <para>
206             Sets the branch routing block, to which control is passed after
207             forking (when a new branch is created). For now branch routes
208             are intended only for last minute changes of the SIP messages
209             (like adding new headers).
210             Note that the set of commands which are usable within branch_routes is
211             very limited. It is not possible to drop a message or generate a reply.
212         </para>
213         <para>Meaning of the parameters is as follows:</para>
214         <itemizedlist>
215             <listitem>
216                 <para><emphasis>branch_route</emphasis> - branch route block to be
217                         called.
218                 </para>
219             </listitem>
220         </itemizedlist>
221         <example>
222             <title><function>t_on_branch</function> usage</title>
223             <programlisting>
224 ...
225 route { 
226         t_on_branch("1"); 
227         t_relay(); 
228
229
230 branch_route[1] {
231         if (uri=~"sip:[0-9]+"){
232                 append_hf("P-Warn: numeric uri\r\n");
233         }
234 }
235             </programlisting>
236         </example>
237         </section>
238
239     <section id="append_branch">
240         <title>
241             <function>append_branch()</function>
242         </title>
243         <para>
244             Similarly to <function>t_fork_to</function>, it extends destination
245             set by a new entry. The difference is that current URI is taken
246             as new entry.
247         </para>
248         <example>
249             <title><function>append_branch</function> usage</title>
250             <programlisting>
251 ...
252 set_user("john"); 
253 t_fork(); 
254 set_user("alice");
255 t_fork(); 
256 t_relay();
257 ...
258             </programlisting>
259         </example>
260     </section>
261
262     <section id="t_newtran">
263         <title>
264             <function>t_newtran()</function>
265         </title>
266         <para>
267             Creates a new transaction, returns a negative value on error. This
268             is the only way a script can add a new transaction in an atomic
269             way. Typically, it is used to deploy a UAS.
270         </para>
271         <example>
272             <title><function>t_newtran</function> usage</title>
273             <programlisting>
274 ...
275 if (t_newtran()) { 
276     log("UAS logic"); 
277     t_reply("999","hello"); 
278 } else sl_reply_error();
279 ...
280             </programlisting>
281         </example>
282         <para>
283             See test/uas.cfg for more examples.
284         </para>
285     </section>
286
287     <section id="t_reply">
288         <title>
289             <function>t_reply(code, reason_phrase)</function>
290         </title>
291         <para>
292             Sends a stateful reply after a transaction has been
293             established. See <function>t_newtran</function> for usage.
294         </para>
295         <para>Meaning of the parameters is as follows:</para>
296         <itemizedlist>
297             <listitem>
298                 <para><emphasis>code</emphasis> - Reply code number.
299                 </para>
300             </listitem>
301             <listitem>
302                 <para><emphasis>reason_phrase</emphasis> - Reason string.
303                 </para>
304             </listitem>
305         </itemizedlist>
306         <example>
307             <title><function>t_reply</function> usage</title>
308             <programlisting>
309 ...
310 t_reply("404", "Not found");
311 ...
312             </programlisting>
313         </example>
314     </section>
315
316     <section id="t_lookup_request">
317         <title>
318             <function>t_lookup_request()</function>
319         </title>
320         <para>
321             Checks if a transaction exists. Returns a positive value if so,
322             negative otherwise.  Most likely you will not want to use it, as a
323             typical application of a look-up is to introduce a new transaction
324             if none was found. However this is safely (atomically) done using
325             <function>t_newtran</function>.
326         </para>
327         <example>
328             <title><function>t_lookup_request</function> usage</title>
329             <programlisting>
330 ...
331 if (t_lookup_request()) {
332     ...
333 };
334 ...
335             </programlisting>
336         </example>
337     </section>
338
339     <section id="t_retransmit_reply">
340         <title>
341             <function>t_retransmit_reply()</function>
342         </title>
343         <para>
344             Retransmits a reply sent previously by UAS transaction.
345         </para>
346         <example>
347             <title><function>t_retransmit_reply</function> usage</title>
348             <programlisting>
349 ...
350 t_retransmit_reply();
351 ...
352             </programlisting>
353         </example>
354     </section>
355
356     <section id="t_release">
357         <title>
358             <function>t_release()</function>
359         </title>
360         <para>
361             Remove transaction from memory (it will be first put on a wait
362             timer to absorb delayed messages).
363         </para>
364         <example>
365             <title><function>t_release</function> usage</title>
366             <programlisting>
367 ...
368 t_release();
369 ...
370             </programlisting>
371         </example>
372     </section>
373
374     <section id="t_forward_nonack">
375         <title>
376             <function>t_forward_nonack()</function>
377             <function>t_forward_nonack(ip, port)</function>
378             <function>t_forward_nonack_udp(ip, port)</function>
379             <function>t_forward_nonack_tcp(ip, port)</function>
380             <function>t_forward_nonack_tls(ip, port)</function>
381             <function>t_forward_nonack_sctp(ip, port)</function>
382         </title>
383         <para>
384             mainly for internal usage--forward a non-ACK request statefully.
385         </para>
386         <para>Meaning of the parameters is as follows:</para>
387         <itemizedlist>
388             <listitem>
389                 <para><emphasis>ip</emphasis> - IP address where the message should be sent.
390                 </para>
391             </listitem>
392             <listitem>
393                 <para><emphasis>port</emphasis> - Port number.
394                 </para>
395             </listitem>
396         </itemizedlist>
397         <example>
398             <title><function>t_forward_nonack</function> usage</title>
399             <programlisting>
400 ...
401 t_forward_nonack("1.2.3.4", "5060");
402 ...
403             </programlisting>
404         </example>
405     </section>
406
407         <section id="t_set_fr">
408         <title>
409             <function>t_set_fr(fr_inv_timeout [, fr_timeout])</function>
410         </title>
411         <para>
412                 Sets the fr_inv_timeout and optionally fr_timeout for the current
413                 transaction or for transactions created during the same script 
414                 invocation, after calling this function.
415                 If the transaction is already created (e.g called after
416                  <function>t_relay()</function> or in an onreply_route) all the
417                  branches will have their final response timeout updated on-the-fly.
418                 If one of the parameters is 0, its value won't be changed.
419         </para>
420         <para>Meaning of the parameters is as follows:</para>
421         <itemizedlist>
422             <listitem>
423                 <para><emphasis>fr_inv_timeout</emphasis> - new final response timeout
424                         (in milliseconds) for INVITEs. See also 
425                         <varname>fr_inv_timer</varname>.
426                 </para>
427                 <para><emphasis>fr_timeout</emphasis> - new final response timeout
428                         (in milliseconds) for non-INVITE transaction, or INVITEs which 
429                         haven't received yet a provisional response. See also
430                         <varname>fr_timer</varname>.
431                 </para>
432             </listitem>
433         </itemizedlist>
434         <para>
435                 See also: 
436                         <varname>fr_timer</varname>,
437                         <varname>fr_inv_timer</varname>,
438                         <function>t_reset_fr()</function>.
439         </para>
440         <example>
441             <title><function>t_set_fr</function> usage</title>
442             <programlisting>
443 ...
444 route { 
445         t_set_fr(10000); # set only fr invite timeout to 10s
446         t_on_branch("1");
447         t_relay(); 
448
449
450 branch_route[1] {
451         # if we are calling the pstn, extend the invite timeout to 50s
452         # for all the branches, and set the no-reply-received timeout to 2s
453         if (uri=~"sip:[0-9]+"){
454                 t_set_fr(50000, 2000); 
455         }
456 }
457             </programlisting>
458         </example>
459         </section>
460
461         <section id="t_reset_fr">
462         <title>
463             <function>t_reset_fr()</function>
464         </title>
465         <para>
466                 Resets the <varname>fr_inv_timer</varname> and 
467                 <varname>fr_timer</varname> for the current transaction to the default
468                 values (set using the tm module parameters
469                 <varname>fr_inv_timer</varname> and <varname>fr_timer</varname>).
470         </para>
471         <para>
472                 It will effectively cancel any previous calls to 
473                 <function>t_set_fr</function> for the same transaction.
474         </para>
475         <para>
476                 See also: <varname>fr_timer</varname>,
477                                 <varname>fr_inv_timer</varname>,
478                                 <function>t_set_fr</function>.
479         </para>
480         <example>
481                 <title><function>t_reset_fr</function> usage</title>
482                 <programlisting>
483 ...
484 route { 
485 ...
486                 t_reset_fr();
487 ...
488
489                 </programlisting>
490         </example>
491         </section>
492
493
494         <section id="t_set_max_lifetime">
495         <title>
496             <function>t_set_max_lifetime(inv_lifetime, noninv_lifetime)</function>
497         </title>
498         <para>
499                 Sets the maximum lifetime for the current INVITE or non-INVITE 
500                 transaction, or for transactions created during the same script
501                 invocation, after calling this function (that's why it takes values
502                 for both INVITE and non-INVITE).
503                 If one of the parameters is 0, its value won't be changed.
504         </para>
505         <para>
506                 It works as a per transaction <varname>max_inv_lifetime</varname> or
507                 <varname>max_noninv_lifetime</varname>.
508         </para>
509         <para>Meaning of the parameters is as follows:</para>
510         <itemizedlist>
511             <listitem>
512                 <para><emphasis>inv_lifetime</emphasis> - maximum INVITE transaction
513                         lifetime (in milliseconds). See also 
514                         <varname>max_inv_lifetime</varname>.
515                 </para>
516                 <para><emphasis>noninv_lifetime</emphasis> - maximum non-INVITE 
517                         transaction lifetime (in milliseconds).
518                         See also <varname>max_noninv_lifetime</varname>.
519                 </para>
520             </listitem>
521         </itemizedlist>
522         <para>
523                 See also: <varname>max_inv_lifetime</varname>,
524                                 <varname>max_noninv_lifetime</varname>,
525                                 <function>t_reset_max_lifetime</function>.
526         </para>
527         <example>
528                 <title><function>t_set_max_lifetime</function> usage</title>
529                 <programlisting>
530 ...
531 route { 
532     if (src_ip=1.2.3.4)
533         t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
534     else
535         t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
536                                           # the current transaction is an 
537                                           # INVITE and to 15s if not
538
539
540                 </programlisting>
541         </example>
542         </section>
543
544         <section id="t_reset_max_lifetime">
545         <title>
546             <function>t_reset_max_lifetime()</function>
547         </title>
548         <para>
549                 Resets the the maximum lifetime for the current INVITE or non-INVITE 
550                 transaction to the default value (set using the tm module parameter
551                 <varname>max_inv_lifetime</varname> or 
552                 <varname>max_noninv_lifetime</varname>).
553         </para>
554         <para>
555                 It will effectively cancel any previous calls to 
556                 <function>t_set_max_lifetime</function> for the same transaction.
557         </para>
558         <para>
559                 See also: <varname>max_inv_lifetime</varname>,
560                                 <varname>max_noninv_lifetime</varname>,
561                                 <function>t_set_max_lifetime</function>.
562         </para>
563         <example>
564                 <title><function>t_reset_max_lifetime</function> usage</title>
565                 <programlisting>
566 ...
567 route { 
568 ...
569                 t_reset_max_lifetime();
570 ...
571
572                 </programlisting>
573         </example>
574         </section>
575
576         <section id="t_set_retr">
577         <title>
578             <function>t_set_retr(retr_t1_interval, retr_t2_interval)</function>
579         </title>
580         <para>
581                 Sets the retr_t1_interval and retr_t2_interval for the current
582                 transaction or for transactions created during the same script 
583                 invocation, after calling this function.
584                 If one of the parameters is 0, it's value won't be changed.
585                 If the transaction is already created (e.g called after
586                  <function>t_relay()</function> or in an onreply_route) all the
587                  existing branches will have their retransmissions intervals updated 
588                  on-the-fly:
589                  if the retransmission interval for the branch has not yet reached T2
590                   the interval will be reset to retr_t1_interval, else to 
591                   retr_t2_interval. Note that the change will happen after the current
592                   interval expires (after the next retransmission, the next-next 
593                   retransmission will take place at retr_t1_interval or 
594                   retr_t2_interval).
595                  All new branches of the same transaction will start with the new 
596                  values.
597                  This function will work even if it's called in the script before
598                 a transaction creating function (e.g.: t_set_retr(500, 4000);
599                 t_relay()). All new transaction created after this function call, 
600                 during the same script invocation will use the new values.
601                 Note that this function will work only if tm is compile with
602                  -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with
603                  4 bytes).
604         </para>
605         <para>Meaning of the parameters is as follows:</para>
606         <itemizedlist>
607             <listitem>
608                 <para><emphasis>retr_t1_interval</emphasis> - new T1 retransmission
609                         interval (in milliseconds). See also
610                         <varname>retr_t1_timeout</varname>.
611                 </para>
612                 <para><emphasis>retr_t2_interval</emphasis> - new T2 (or maximum) 
613                         retransmission interval (in milliseconds). See also
614                         <varname>retr_t2_timeout</varname>.
615                 </para>
616             </listitem>
617         </itemizedlist>
618         <para>
619                 See also: 
620                         <varname>retr_timer1</varname>,
621                         <varname>retr_timer2</varname>,
622                         <function>t_reset_retr()</function>.
623         </para>
624         <example>
625             <title><function>t_set_retr</function> usage</title>
626             <programlisting>
627 ...
628 route { 
629         t_set_retr(250, 0); # set only T1 to 250 ms
630         t_on_branch("1");
631         t_relay(); 
632
633
634 branch_route[1] {
635         # if we are calling the a remote pstn, extend T1 and decrease T2
636         # for all the branches
637         if (uri=~"sip:[0-9]+"){
638                 t_set_retr(500, 2000); 
639         }
640 }
641             </programlisting>
642         </example>
643         </section>
644
645
646         <section id="t_reset_retr">
647         <title>
648             <function>t_reset_retr()</function>
649         </title>
650         <para>
651                 Resets the <varname>retr_timer1</varname> and 
652                 <varname>retr_timer2</varname> for the current transaction to the 
653                 default values (set using the tm module parameters
654                 <varname>retr_timer1</varname> and <varname>retr_timer2</varname>).
655         </para>
656         <para>
657                 It will effectively cancel any previous calls to 
658                 <function>t_set_retr</function> for the same transaction.
659         </para>
660         <para>
661                 See also: <varname>retr_timer1</varname>,
662                                 <varname>retr_timer2</varname>,
663                                 <function>t_set_retr</function>.
664         </para>
665         <example>
666                 <title><function>t_reset_retr</function> usage</title>
667                 <programlisting>
668 ...
669 route { 
670 ...
671                 t_reset_retr();
672 ...
673
674                 </programlisting>
675         </example>
676         </section>
677
678         <section id="t_set_auto_inv_100">
679         <title>
680             <function>t_set_auto_inv_100(0|1)</function>
681         </title>
682         <para>
683                 Switch automatically sending 100 replies to INVITEs on/off on a 
684                 per transaction basis. It overrides the 
685                 <varname>auto_inv_100</varname> value for the current transaction.
686         </para>
687         <para>
688                 See also: <varname>auto_inv_100</varname>.
689         </para>
690         <example>
691                 <title><function>t_set_auto_inv_100</function> usage</title>
692                 <programlisting>
693 ...
694 route { 
695 ...
696         if (src_ip==1.2.3.0/24)
697                 t_set_auto_inv_100(0); # turn off automatic 100 replies
698 ...
699
700                 </programlisting>
701         </example>
702         </section>
703
704         <section id="t_branch_timeout">
705         <title>
706             <function>t_branch_timeout()</function>
707         </title>
708         <para>
709                 Returns true if the failure route is executed for a branch that did
710                 timeout. It can be used only from the 
711                 <emphasis>failure_route</emphasis>.
712         </para>
713         <example>
714             <title><function>t_branch_timeout</function> usage</title>
715             <programlisting>
716 ...
717 failure_route[0]{ 
718         if (t_branch_timeout()){
719                 log("timeout\n");
720                 # ... 
721         }
722
723             </programlisting>
724         </example>
725         </section>
726
727 <section id="t_branch_replied">
728         <title>
729             <function>t_branch_replied()</function>
730         </title>
731         <para>
732                 Returns true if the failure route is executed for a branch that did
733                 receive at least one reply in the past (the "current" reply is not 
734                 taken into account). It can be used only from the 
735                 <emphasis>failure_route</emphasis>.
736         </para>
737         <example>
738             <title><function>t_branch_replied</function> usage</title>
739             <programlisting>
740 ...
741 failure_route[0]{ 
742         if (t_branch_timeout()){
743                 if (t_branch_replied())
744                         log("timeout after receiving a reply (no answer?)\n");
745                 else
746                         log("timeout, remote side seems to be down\n");
747                 # ... 
748         }
749
750             </programlisting>
751         </example>
752         </section>
753
754 <section id="t_any_timeout">
755         <title>
756             <function>t_any_timeout()</function>
757         </title>
758         <para>
759                 Returns true if at least one of the current transactions branches
760                 did timeout.
761         </para>
762         <example>
763             <title><function>t_any_timeout</function> usage</title>
764             <programlisting>
765 ...
766 failure_route[0]{ 
767         if (!t_branch_timeout()){
768                 if (t_any_timeout()){
769                         log("one branch did timeout\n");
770                         sl_send_reply("408", "Timeout");
771                 }
772         }
773
774             </programlisting>
775         </example>
776         </section>
777
778 <section id="t_any_replied">
779         <title>
780             <function>t_any_replied()</function>
781         </title>
782         <para>
783                 Returns true if at least one of the current transactions branches
784                 did receive some reply in the past. If called from a failure or
785                 onreply route, the "current" reply is not taken into account.
786         </para>
787         <example>
788             <title><function>t_any_replied</function> usage</title>
789             <programlisting>
790 ...
791 onreply_route[0]{ 
792         if (!t_any_replied()){
793                 log("first reply received\n");
794                 # ...
795         }
796
797             </programlisting>
798         </example>
799 </section>
800
801 <section id="t_grep_status">
802         <title>
803             <function>t_grep_status("code")</function>
804         </title>
805         <para>
806                 Returns true if "code" is the final reply received (or locally
807                  generated) in at least one of the current transactions branches.
808         </para>
809         <example>
810             <title><function>t_grep_status</function> usage</title>
811             <programlisting>
812 ...
813 onreply_route[0]{ 
814         if (t_grep_status("486")){
815                 /* force a 486 reply, even if this is not the winning branch */
816                 t_reply("486", "Busy");
817         }
818
819             </programlisting>
820         </example>
821 </section>
822
823 <section id="t_is_canceled">
824         <title>
825             <function>t_is_canceled()</function>
826         </title>
827         <para>
828                 Returns true if the current transaction was canceled.
829         </para>
830         <example>
831             <title><function>t_is_canceled</function> usage</title>
832             <programlisting>
833 ...
834 failure_route[0]{ 
835         if (t_is_canceled()){
836                 log("transaction canceled\n");
837                 # ...
838         }
839
840             </programlisting>
841         </example>
842         </section>
843
844         <section id="t_is_expired">
845         <title>
846             <function>t_is_expired()</function>
847         </title>
848         <para>
849                 Returns true if the current transaction has already been expired,
850                 i.e. the max_inv_lifetime/max_noninv_lifetime interval has already
851                 elapsed.
852         </para>
853         <example>
854             <title><function>t_is_expired</function> usage</title>
855             <programlisting>
856 ...
857 failure_route[0]{ 
858         if (t_is_expired()){
859                 log("transaction expired\n");
860                 # There is no point in adding a new branch.
861         }
862
863             </programlisting>
864         </example>
865         </section>
866
867     <section id="t_relay_cancel">
868         <title>
869             <function>t_relay_cancel()</function>
870         </title>
871         <para>
872                 Forwards the CANCEL if the corresponding INVITE transaction
873                 exists. The function is supposed to be used at the very
874                 beginning of the script, because the CANCELs can be caught
875                 and the rest of the script can be bypassed this way. Do not disable
876                 <varname>reparse_invite</varname> module parameter, and call
877                 <varname>t_relay_cancel()</varname> right after the sanity tests.
878         </para>
879         <para>
880                 Return value is 0 (drop) if the corresponding INVITE was found
881                 and the CANCELs were successfully sent to the pending branches,
882                 true if the INVITE was not found, and false in case of any error.
883         </para>
884         <example>
885             <title><function>t_relay_cancel</function> usage</title>
886             <programlisting>
887
888 if (method == CANCEL) {
889         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
890                                   # nothing to do
891
892                 # corresponding INVITE transaction found but error occurred
893                 sl_reply("500", "Internal Server Error");
894                 drop;
895         }
896         # bad luck, corresponding INVITE transaction is missing,
897         # do the same as for INVITEs
898 }
899             </programlisting>
900         </example>
901     </section>
902
903     <section id="t_lookup_cancel">
904         <title>
905             <function>t_lookup_cancel()</function>,
906             <function>t_lookup_cancel(1)</function>
907         </title>
908         <para>
909                 Returns true if the corresponding INVITE transaction exists
910                 for a CANCEL request. The function can be called at the beginning
911                 of the script to check whether or not the CANCEL can be immediately
912                 forwarded bypassing the rest of the script. Note however that
913                 <function>t_relay_cancel</function> includes
914                 <function>t_lookup_cancel</function> as well, therefore it is not
915                 needed to explicitly call this function unless something has to be
916                 logged for example.
917         </para>
918         <para>
919                 If the function parameter (optional) is set to 1, the message flags
920                 are overwritten with the flags of the INVITE. isflagset() can be used
921                 to check the flags of the previously forwarded INVITE in this case.
922         </para>
923         <example>
924             <title><function>t_lookup_cancel</function> usage</title>
925             <programlisting>
926
927 if (method == CANCEL) {
928         if (t_lookup_cancel()) {
929                 log("INVITE transaction exists");
930                 if (!t_relay_cancel()) {  # implicit drop if
931                                           # relaying was successful,
932                                           # nothing to do
933
934                         # corresponding INVITE transaction found
935                         # but error occurred
936                         sl_reply("500", "Internal Server Error");
937                         drop;
938                 }
939         }
940         # bad luck, corresponding INVITE transaction is missing,
941         # do the same as for INVITEs
942 }
943             </programlisting>
944         </example>
945     </section>
946
947     <section id="t_drop_replies">
948         <title>
949             <function>t_drop_replies([mode])</function>
950         </title>
951         <para>
952                 Drops all the previously received replies in failure_route
953                 block to make sure that none of them is picked up again.
954         </para>
955         <para>
956                 The parameter 'mode' controls which replies are dropped: 'a'
957                 or missing - all replies are dropped; 'l' - replies received for
958                 last set of branches are dropped; 'n' - no reply is dropped.
959         </para>
960         <para>
961                 Dropping replies works only if a new branch is added to the
962                 transaction, or it is explicitly replied in the script!
963         </para>
964         <example>
965             <title><function>t_drop_replies()</function> usage</title>
966             <programlisting>
967 ...
968 failure_route[0]{ 
969         if (t_check_status("5[0-9][0-9]")){
970                 # I do not like the 5xx responses,
971                 # so I give another chance to "foobar.com",
972                 # and I drop all the replies to make sure that
973                 # they are not forwarded to the caller.
974                 t_drop_replies();
975                 
976                 rewritehostport("foobar.com");
977                 append_branch();
978                 t_relay();
979         }
980
981             </programlisting>
982         </example>
983     </section>
984
985     <section id="t_save_lumps">
986         <title>
987             <function>t_save_lumps()</function>
988         </title>
989         <para>
990                 Forces the modifications of the processed SIP message
991                 to be saved in shared memory before t_relay() is called.
992                 The new branches which are created in failure_route will
993                 contain the same modifications, and any other modification
994                 after t_save_lumps() will be lost.
995         </para>
996         <para>
997                 Note that t_relay() automatically saves the modifications
998                 when it is called the first time, there is no need for
999                 t_save_lumps() unless message changes between t_save_lumps()
1000                 and t_relay() must not be propagated to failure_route.
1001         </para>
1002         <para>
1003                 The transaction must be created by t_newtran() before
1004                 calling t_save_lumps().
1005         </para>
1006         <example>
1007             <title><function>t_save_lumps()</function> usage</title>
1008             <programlisting>
1009 route {
1010         ...
1011         t_newtran();
1012         append_hf("hf1: my first header\r\n");
1013         ...
1014         t_save_lumps();
1015         append_hf("hf2: my second header\r\n");
1016         ...
1017         t_on_failure("1");
1018         t_relay();
1019 }
1020
1021 failure_route[1] {
1022         append_branch();
1023         append_hf("hf3: my third header\r\n");
1024         #
1025         # This branch contains hf1 and hf3, but does
1026         # not contain hf2 header.
1027         # hf2 would be also present here without
1028         # t_save_lumps().
1029         ...
1030         t_relay();
1031 }
1032             </programlisting>
1033         </example>
1034     </section>
1035
1036         <section>
1037                 <title>
1038                 <function moreinfo="none">t_load_contacts()</function>
1039                 </title>
1040                 <para>
1041                   This is the first of the two functions that can be used to implement
1042                   serial/parallel forking based on the q value of individual branches
1043                   in a destination set.
1044                 </para>
1045                 <para>
1046                   The function <function>t_load_contacts()</function> takes all
1047                   branches from the current destination set and encodes them into the
1048                   AVP whose name or ID is configured with the
1049                   parameter <varname>contacts_avp</varname>. Note that you have to
1050                   configure this parameter before you can use the function, the
1051                   parameter is set to NULL by default, which disables the function.
1052                 </para>
1053                 <para>
1054                   If the destination set contains only one branch (the Request-URI) or
1055                   if all branches have the same q value then the function does nothing
1056                   to minimize performance impact. In such case all branches should be
1057                   tried in parallel and that is the default mode of operation of
1058                   functions like <function>t_relay()</function>, so there is no need
1059                   to create the AVP or sort the branches.
1060                 </para>
1061                 <para>
1062                   If the current destination set contains more than one branch and not
1063                   all branches have the same q value then the function sorts them
1064                   according to the increasing value of the q parameter. The resulting
1065                   sorted list of branches is then encoded into the AVP.
1066                 </para>
1067                 <para>
1068                   The q parameter contains a value from a range of 0 to 1.0 and it
1069                   expresses relative preferrence of the branch among all branches in
1070                   the destination set. The higher the q value the more preferrence the
1071                   user agent gave to the branch. Branches with higher q values will be
1072                   tried first when serial forking takes place.
1073                 </para>
1074                 <para>
1075                   After that the function clears all branches and you have to
1076                   call <function>t_next_contacts</function> to retrieve them sorted
1077                   according to their q value. Note that if you
1078                   use <function>t_load_contacts</function> then you also have to
1079                   use <function>t_next_contacts</function> before
1080                   calling <function>t_relay</function>.
1081                 </para>
1082                 <para>
1083                   The AVP created by the function may contain multiple values, with
1084                   one encoded branch per value. The first value will contain the
1085                   branch with the highest q value. Each value contains the
1086                   Request-URI, the destination URI, the path vector, the outgoing
1087                   socket description and branch flags. All these fields are delimited
1088                   with the LF character.
1089                 </para>
1090                 <para>
1091           The function returns 1 if loading of contacts succeeded or there was
1092           nothing to do. Returns -1 on error (see syslog).
1093                 </para>
1094                 <para>
1095                 This function can be used from REQUEST_ROUTE.
1096                 </para>
1097                 <example>
1098                 <title><function>t_load_contacts</function> usage</title>
1099                 <programlisting format="linespecific">
1100 ...
1101 if (!t_load_contacts()) {
1102         sl_send_reply("500", "Server Internal Error - Cannot load contacts");
1103         exit;
1104 };
1105 ...
1106 </programlisting>
1107                 </example>
1108         </section>
1109
1110         <section>
1111                 <title>
1112                 <function moreinfo="none">t_next_contacts()</function>
1113                 </title>
1114                 <para>
1115                   The function <function>t_next_contacts</function> is the second of
1116                   the two functions that can be used to implement serial/parallel
1117                   forking based on the q value of individual branches in a destination
1118                   set.
1119                 </para>
1120                 <para>
1121                   This function takes the AVP created
1122                   by <function>t_load_contacts</function> and extracts branches with
1123                   highest q value from it into the destination set when called for the
1124                   first time. When you call the function second time it extracts
1125                   branches with lower q value, and so on until all branches have been
1126                   extracted.      
1127                 </para>
1128                 <para>
1129           If no transaction exist when <function>t_next_contacts()</function>
1130           is called, this usually happens when you call the function from a
1131           request route block before you call <function>t_relay</function>, it
1132           replaces the Request-URI with the first contacts_avp value, adds the
1133           remaining contacts_avp values with the same q value as branches, and
1134           destroys those AVPs. 
1135                 </para>
1136         <para>
1137           If transaction does exist when t_next_contacts() is called, it adds
1138           the first <varname>contacts_avp</varname> value and all following
1139           <varname>contacts_avp</varname> values with the same q value as new
1140           branches to request and destroys those AVPs. 
1141         </para>
1142                 <para>
1143                   When you call the function repeatedly from a failure_route branch,
1144                   it looks for more AVP values each time and adds branches that have
1145                   same q value from the AVP as additional destination set branches. It
1146                   always stops when it reaches a branch that has a lower q value. Used
1147                   AVP values are always destroyed.,
1148                 </para>
1149                 <para>
1150                   The function does nothing if there are
1151                   no <varname>contact_avp</varname> values.
1152                 </para>
1153                 <para>
1154           The function returns 1 if there were no errors and -1 if an error
1155           occurred (see syslog). This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
1156                 </para>
1157                 <para>
1158                   Note that if use use <function>t_load_contacts</function>
1159                   and <function>t_next_contacts</function> functions then you should
1160                   also set the value of <varname>restart_fr_on_each_reply</varname>
1161                   parameter to 0. If you do not do that then it can happen that a
1162                   broken user agent that retransmits 180 periodically will keep
1163                   resetting the fr_inv_timer value and serial forking never happens.
1164                 </para>
1165                 <para>
1166                   Also make sure that you
1167                   configured <varname>fr_inv_timer_next</varname> with lower value,
1168                   especially if you expect to have many serially forked branches. See
1169                   the documentation of that parameter for more details.
1170                 </para>
1171                 <example>
1172                 <title><function>t_next_contacts</function> usage</title>
1173                 <programlisting format="linespecific">
1174 ...
1175 # First call after t_load_contacts() when transaction does not exist yet
1176 # and contacts should be available
1177 if (!t_next_contacts()) {
1178         sl_send_reply("500", "Server Internal Error - Cannot get contacts");
1179 } else {
1180         t_relay();
1181 };
1182 ...
1183 # Following call, when transaction exists and there may or may not be
1184 # contacts left
1185 if (!t_next_contacts()) {
1186         t_reply("408", "Request Timeout");
1187 } else {
1188         t_relay();
1189 };
1190 ...
1191 </programlisting>
1192                 </example>
1193         </section>
1194
1195         <section id="t_check_trans">
1196         <title>
1197                 <function>t_check_trans()</function>
1198         </title>
1199         <para>
1200                 <function>t_check_trans()</function> can be used to quickly check if
1201                 a message belongs or is related to a transaction. It behaves
1202                 differently for different types of messages:
1203                 <itemizedlist>
1204                         <listitem>
1205                                 <para>For a SIP Reply it returns true if the reply belongs to
1206                                 an existing transaction and false otherwise.</para>
1207                         </listitem>
1208                         <listitem>
1209                                 <para>For a CANCEL it behaves exactly as
1210                                 <function>t_lookup_cancel()</function>: returns true if a
1211                                 corresponding INVITE transaction exists for the CANCEL and
1212                                 false otherwise.</para>
1213                         </listitem>
1214                         <listitem>
1215                                 <para>For ACKs to negative replies or for ACKs to local
1216                                 transactions it will terminate the script if the ACK belongs
1217                                 to a transaction (it would make very little sense to process
1218                                 an ACK to a negative reply  for an existing transaction in
1219                                 some other way then to simply pass it to tm) or return false
1220                                 if not.</para>
1221                         </listitem>
1222                         <listitem>
1223                                 <para>For end-to-end ACKs (ACKs to 2xx responses for forwarded
1224                                 INVITE transactions) it will return true if the corresponding
1225                                 INVITE transaction is found and still active and false if not.
1226                                 </para>
1227                                 <note>
1228                                 <para>
1229                                 Note that the e2e ACK matching is more of a hint
1230                                 then a certainty. A delayed e2e ACK might arrive after the
1231                                 transaction wait time elapses, when the INVITE transaction no
1232                                 longer exists and thus would not match anything. There are
1233                                 also cases when tm would not keep all the information needed
1234                                 for e2e ACK matching (since this is not needed for a statefull
1235                                 proxy and it requires additional memory, tm will not keep this
1236                                 information unless needed by some other module or callbacks).
1237                                 </para>
1238                                 </note>
1239                         </listitem>
1240                         <listitem>
1241                                 <para>For other requests (non ACKs and non CANCELs), it will
1242                                 terminate the script for retransmissions and return false for
1243                                 new requests (for which no transaction exists yet).</para>
1244                         </listitem>
1245                 </itemizedlist>
1246         </para>
1247         <note><para>
1248                 An important difference from kamailio version is that for an ACK to
1249                 negative reply or for a local transaction, the script execution will be
1250                 immediately stopped and the message handled by tm, instead of returning
1251                 true.
1252         </para></note>
1253         <para><function>t_check_trans()</function> functionality for requests,
1254                 except for the e2e ACK matching, can be replicated in the script
1255                 using <function>t_lookup_cancel()</function> and
1256                 <function>t_lookup_request()</function>.
1257         </para>
1258         <para>See also: <function>t_lookup_request()</function>,
1259                                         <function>t_lookup_cancel()</function>.
1260         </para>
1261         <example>
1262                 <title><function>t_check_trans</function> usage</title>
1263                 <programlisting>
1264
1265 if ( method == "CANCEL" &amp;&amp; !t_check_trans())
1266         sl_reply("403", "cancel out of the blue forbidden");
1267 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
1268
1269                 </programlisting>
1270         </example>
1271         </section>
1272
1273         <section id="t_set_disable_6xx">
1274         <title>
1275                 <function>t_set_disable_6xx(0|1)</function>
1276         </title>
1277         <para>
1278                 Turn off/on 6xx replies special rfc conformant handling on a per
1279                 transaction basis. If turned off
1280                 (<function>t_set_disable_6xx("1")</function>) 6XXs will be treated
1281                 like normal replies.
1282         </para>
1283         <para>
1284                 It overrides the <varname>disable_6xx_block</varname> value for
1285                 the current transaction.
1286         </para>
1287         <para>
1288                 See also: <varname>disable_6xx_block</varname>.
1289         </para>
1290         <example>
1291                 <title><function>t_set_disable_6xx</function> usage</title>
1292                 <programlisting>
1293 ...
1294 route {
1295 ...
1296         if (src_ip==1.2.3.4) # bad user agent that sends 603
1297                 t_set_disable_6xx(1); # turn off 6xx special handling
1298 ...
1299 }
1300                 </programlisting>
1301         </example>
1302         </section>
1303
1304         <section id="t_set_disable_failover">
1305         <title>
1306                 <function>t_set_disable_failover(0|1)</function>
1307         </title>
1308         <para>
1309                 Turn off/on dns failover on a per transaction basis.
1310         </para>
1311         <para>
1312                 See also: <varname>use_dns_failover</varname>.
1313         </para>
1314         <example>
1315                 <title><function>t_set_disable_failover</function> usage</title>
1316                 <programlisting>
1317 ...
1318 route {
1319 ...
1320         if (uri=~"@foo.bar$")
1321                 t_set_disable_failover(1); # turn off dns failover
1322 ...
1323 }
1324                 </programlisting>
1325         </example>
1326         </section>
1327
1328         <section id="t_replicate">
1329         <title>
1330             <function>t_replicate(params)</function>
1331         </title>
1332         <para>
1333                 Replicate the SIP request to a specific address.
1334         </para>
1335         <para>
1336                 There are several function prototypes:
1337                 <itemizedlist>
1338                 <listitem><para>
1339             <function>t_replicate(uri)</function>,
1340                 </para></listitem>
1341                 <listitem><para>
1342             <function>t_replicate(host, port)</function>,
1343                 </para></listitem>
1344                 <listitem><para>
1345             <function>t_replicat_udp(host, port)</function>
1346                 </para></listitem>
1347                 <listitem><para>
1348             <function>t_replicate_tcp(host, port)</function>
1349                 </para></listitem>
1350                 <listitem><para>
1351             <function>t_replicate_tls(host, port)</function>
1352                 </para></listitem>
1353                 <listitem><para>
1354             <function>t_replicate_sctp(host, port)</function>
1355                 </para></listitem>
1356                 <listitem><para>
1357             <function>t_replicate_to(proto, hostport)</function>
1358                 </para></listitem>
1359                 </itemizedlist>
1360         </para>
1361         <para>Meaning of the parameters is as follows:</para>
1362         <itemizedlist>
1363             <listitem>
1364                 <para><emphasis>uri</emphasis> - SIP URI where the message should be sent.
1365                 It can be given via a script variable.
1366                 </para>
1367             </listitem>
1368             <listitem>
1369                 <para><emphasis>host</emphasis> - host address where the message should be sent.
1370                 </para>
1371             </listitem>
1372             <listitem>
1373                 <para><emphasis>port</emphasis> - port number.
1374                 </para>
1375             </listitem>
1376             <listitem>
1377                 <para><emphasis>proto</emphasis> - transport protocol to be used.
1378                 </para>
1379             </listitem>
1380             <listitem>
1381                 <para><emphasis>hostport</emphasis> - address in "host:port" format. It can be
1382                 given via an AVP.
1383                 </para>
1384             </listitem>
1385         </itemizedlist>
1386         <example>
1387             <title><function>t_replicate</function> usage</title>
1388             <programlisting>
1389 ...
1390 # sent to 1.2.3.4:5060 over tcp
1391 t_replicate("sip:1.2.3.4:5060;transport=tcp");
1392
1393 # sent to 1.2.3.4:5061 over tls
1394 $var(h) = "1.2.3.4:5061";
1395 t_replicate("sip:$var(h);transport=tls");
1396
1397 # sent to 1.2.3.4:5060 over udp
1398 t_replicate_to_udp("1.2.3.4", "5060");
1399 ...
1400             </programlisting>
1401         </example>
1402     </section>
1403         <section id="t_relay_to">
1404         <title>
1405             <function>t_relay_to(proxy, flags)</function>
1406         </title>
1407         <para>
1408                 Forward the SIP request to a specific address, controlling internal
1409                 behavior via flags.
1410         </para>
1411         <para>
1412                 There are several function prototypes:
1413                 <itemizedlist>
1414                 <listitem><para>
1415             <function>t_relay_to()</function>,
1416                 </para></listitem>
1417                 <listitem><para>
1418             <function>t_relay_to(proxy)</function>,
1419                 </para></listitem>
1420                 <listitem><para>
1421             <function>t_relay_to(flags)</function>
1422                 </para></listitem>
1423                 <listitem><para>
1424             <function>t_relay_to(proxy, flags)</function>
1425                 </para></listitem>
1426                 </itemizedlist>
1427         </para>
1428         <para>Meaning of the parameters is as follows:</para>
1429         <itemizedlist>
1430             <listitem>
1431                 <para><emphasis>proxy</emphasis> - address where the request should
1432                 be sent. Format is: "proto:host:port" - any of proto or port can be
1433                 ommitted, along with the semicolon after or before.
1434                 </para>
1435             </listitem>
1436             <listitem>
1437                 <para><emphasis>flags</emphasis> - bitmask integer value to control
1438                 the internal behavior. Bits can be:
1439                 </para>
1440                 <itemizedlist>
1441             <listitem>
1442                 <para><emphasis>0x01</emphasis> - do not generate 100 reply.
1443                 </para>
1444             </listitem>
1445             <listitem>
1446                 <para><emphasis>0x02</emphasis> - do not generate reply on internal
1447                 error (NOTE: has no effect anymore).
1448                 </para>
1449             </listitem>
1450             <listitem>
1451                 <para><emphasis>0x04</emphasis> - disable dns failover.
1452                 </para>
1453             </listitem>
1454                 </itemizedlist>
1455             </listitem>
1456         </itemizedlist>
1457         <example>
1458             <title><function>t_replicate</function> usage</title>
1459             <programlisting>
1460 ...
1461 # sent to 1.2.3.4:5060 over tcp
1462 t_relay_to("tcp:1.2.3.4:5060");
1463
1464 # sent to 1.2.3.4 over tls
1465 t_relay_to("tls:1.2.3.4");
1466
1467 # sent to dst URI or R-URI without a 100 reply
1468 t_relay_to("0x01");
1469 ...
1470             </programlisting>
1471         </example>
1472     </section>
1473
1474
1475         <section id="t_set_no_e2e_cancel_reason">
1476         <title>
1477                 <function>t_set_no_e2e_cancel_reason(0|1)</function>
1478         </title>
1479         <para>
1480                 Enables/disables reason header (RFC 3326) copying from the triggering
1481                 received CANCEL to the generated hop-by-hop CANCEL. 0 enables and
1482                 1 disables.
1483         </para>
1484         <para>
1485                 It overrides the <varname>e2e_cancel_reason</varname> setting (module
1486                  parameter) for the current transaction.
1487         </para>
1488         <para>
1489                 See also: <varname>e2e_cancel_reason</varname>.
1490         </para>
1491         <example>
1492                 <title><function>t_set_no_e2e_cancel_reason</function> usage</title>
1493                 <programlisting>
1494 ...
1495 route {
1496 ...
1497         if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
1498                 t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header copying
1499 ...
1500 }
1501                 </programlisting>
1502         </example>
1503         </section>
1504
1505
1506 </section>