e338bd80fdbdb0369e3558061053cc5ef5691a38
[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_tcp(ip, port)</function>
21         </title>
22         <para>
23             Relay a message statefully to a fixed destination. This along with
24             <function>t_relay</function> is the function most users want to
25             use--all other are mostly for programming. Programmers interested
26             in writing <acronym>TM</acronym> logic should review how t_relay is
27             implemented in tm.c and how <acronym>TM</acronym> callbacks work.
28         </para>
29         <para>Meaning of the parameters is as follows:</para>
30         <itemizedlist>
31             <listitem>
32                 <para><emphasis>ip</emphasis> - IP address where the message should be sent.
33                 </para>
34             </listitem>
35             <listitem>
36                 <para><emphasis>port</emphasis> - Port number.
37                 </para>
38             </listitem>
39         </itemizedlist>
40         <example>
41             <title><function>t_relay_to_udp</function> usage</title>
42             <programlisting>
43 ...
44 t_relay_to_udp("1.2.3.4", "5060");
45 ...
46             </programlisting>
47         </example>
48     </section>
49
50     <section id="t_relay">
51         <title>
52             <function>t_relay()</function>
53         </title>
54         <para>
55             Relay a message statefully to destination indicated in current URI. (If the
56             original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the new URI will
57             be taken). Returns a negative value on failure--you may still want to send a
58             negative reply upstream statelessly not to leave upstream UAC in lurch.
59         </para>
60         <example>
61             <title><function>t_relay</function> usage</title>
62             <programlisting>
63 ...
64 if (!t_relay()) 
65
66     sl_reply_error(); 
67     break; 
68 };
69 ...
70             </programlisting>
71         </example>
72     </section>
73     
74     <section id="t_on_failure">
75         <title>
76             <function>t_on_failure(failure_route)</function>
77         </title>
78         <para>
79             Sets failure routing block, to which control is passed after a
80             transaction completed with a negative result but before sending a
81             final reply. In the referred block, you can either start a new
82             branch (good for services such as forward_on_no_reply) or send a
83             final reply on your own (good for example for message silo, which
84             received a negative reply from upstream and wants to tell upstream
85             "202 I will take care of it"). Note that the set of
86             commands which are usable within failure_routes is strictly limited to
87             rewriting URI, initiating new branches, logging, and sending
88             stateful replies (<function>t_reply</function>). Any other commands
89             may result in unpredictable behavior and possible server
90             failure. Note that whenever failure_route is entered, uri is reset to
91             value which it had on relaying. If it temporarily changed during a
92             reply_route processing, subsequent reply_route will ignore the
93             changed value and use again the original one.
94         </para>
95         <para>Meaning of the parameters is as follows:</para>
96         <itemizedlist>
97             <listitem>
98                 <para><emphasis>failure_route</emphasis> - Failure route block to be called.
99                 </para>
100             </listitem>
101         </itemizedlist>
102         <example>
103             <title><function>t_on_failure</function> usage</title>
104             <programlisting>
105 ...
106 route { 
107     t_on_failure("1"); 
108     t_relay(); 
109
110
111 failure_route[1] {
112     revert_uri(); 
113     setuser("voicemail"); 
114     append_branch(); 
115 }
116 ...
117             </programlisting>
118         </example>
119         <para>
120             See <filename>test/onr.cfg</filename> for a more complex example of
121             combination of serial with parallel forking.
122         </para>
123     </section>
124  
125          <section id="t_on_reply">
126         <title>
127             <function>t_on_reply(onreply_route)</function>
128         </title>
129         <para>
130             Sets the reply routing block, to which control is passed when a
131             reply for the current transaction is received.
132             Note that the set of commands which are usable within onreply_routes is
133              limited.
134         </para>
135         <para>Meaning of the parameters is as follows:</para>
136         <itemizedlist>
137             <listitem>
138                 <para><emphasis>onreply_route</emphasis> - Onreply route block to be
139                         called.
140                 </para>
141             </listitem>
142         </itemizedlist>
143         <example>
144             <title><function>t_on_reply</function> usage</title>
145             <programlisting>
146 ...
147 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
148 ...
149 route { 
150         /* if natted */
151         t_on_reply("1"); 
152         t_relay(); 
153
154
155 onreply_route[1] {
156         if (status=~ "(183)|2[0-9][0-9]"){
157                 force_rtp_proxy();
158                 search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=yes');
159         }
160         if (nat_uac_test("1")){
161                 fix_nated_contact();
162         }
163 }
164             </programlisting>
165         </example>
166         </section>
167
168         <section id="t_on_branch">
169         <title>
170             <function>t_on_branch(branch_route)</function>
171         </title>
172         <para>
173             Sets the branch routing block, to which control is passed after
174             forking (when a new branch is created). For now branch routes
175             are intended only for last minute changes of the SIP messages
176             (like adding new headers).
177             Note that the set of commands which are usable within branch_routes is
178             very limited. It is not possible to drop a message or generate a reply.
179         </para>
180         <para>Meaning of the parameters is as follows:</para>
181         <itemizedlist>
182             <listitem>
183                 <para><emphasis>branch_route</emphasis> - branch route block to be
184                         called.
185                 </para>
186             </listitem>
187         </itemizedlist>
188         <example>
189             <title><function>t_on_branch</function> usage</title>
190             <programlisting>
191 ...
192 route { 
193         t_on_branch("1"); 
194         t_relay(); 
195
196
197 branch_route[1] {
198         if (uri=~"sip:[0-9]+"){
199                 append_hf("P-Warn: numeric uri\r\n");
200         }
201 }
202             </programlisting>
203         </example>
204         </section>
205
206     <section id="append_branch">
207         <title>
208             <function>append_branch()</function>
209         </title>
210         <para>
211             Similarly to <function>t_fork_to</function>, it extends destination
212             set by a new entry. The difference is that current URI is taken
213             as new entry.
214         </para>
215         <example>
216             <title><function>append_branch</function> usage</title>
217             <programlisting>
218 ...
219 set_user("john"); 
220 t_fork(); 
221 set_user("alice");
222 t_fork(); 
223 t_relay();
224 ...
225             </programlisting>
226         </example>
227     </section>
228
229     <section id="t_newtran">
230         <title>
231             <function>t_newtran()</function>
232         </title>
233         <para>
234             Creates a new transaction, returns a negative value on error. This
235             is the only way a script can add a new transaction in an atomic
236             way. Typically, it is used to deploy a UAS.
237         </para>
238         <example>
239             <title><function>t_newtran</function> usage</title>
240             <programlisting>
241 ...
242 if (t_newtran()) { 
243     log("UAS logic"); 
244     t_reply("999","hello"); 
245 } else sl_reply_error();
246 ...
247             </programlisting>
248         </example>
249         <para>
250             See test/uas.cfg for more examples.
251         </para>
252     </section>
253
254     <section id="t_reply">
255         <title>
256             <function>t_reply(code, reason_phrase)</function>
257         </title>
258         <para>
259             Sends a stateful reply after a transaction has been
260             established. See <function>t_newtran</function> for usage.
261         </para>
262         <para>Meaning of the parameters is as follows:</para>
263         <itemizedlist>
264             <listitem>
265                 <para><emphasis>code</emphasis> - Reply code number.
266                 </para>
267             </listitem>
268             <listitem>
269                 <para><emphasis>reason_phrase</emphasis> - Reason string.
270                 </para>
271             </listitem>
272         </itemizedlist>
273         <example>
274             <title><function>t_reply</function> usage</title>
275             <programlisting>
276 ...
277 t_reply("404", "Not found");
278 ...
279             </programlisting>
280         </example>
281     </section>
282
283     <section id="t_lookup_request">
284         <title>
285             <function>t_lookup_request()</function>
286         </title>
287         <para>
288             Checks if a transaction exists. Returns a positive value if so,
289             negative otherwise.  Most likely you will not want to use it, as a
290             typical application of a looku-up is to introduce a new transaction
291             if none was found. However this is safely (atomically) done using
292             <function>t_newtran</function>.
293         </para>
294         <example>
295             <title><function>t_lookup_request</function> usage</title>
296             <programlisting>
297 ...
298 if (t_lookup_request()) {
299     ...
300 };
301 ...
302             </programlisting>
303         </example>
304     </section>
305
306     <section id="t_retransmit_reply">
307         <title>
308             <function>t_retransmit_reply()</function>
309         </title>
310         <para>
311             Retransmits a reply sent previously by UAS transaction.
312         </para>
313         <example>
314             <title><function>t_retransmit_reply</function> usage</title>
315             <programlisting>
316 ...
317 t_retransmit_reply();
318 ...
319             </programlisting>
320         </example>
321     </section>
322
323     <section id="t_release">
324         <title>
325             <function>t_release()</function>
326         </title>
327         <para>
328             Remove transaction from memory (it will be first put on a wait
329             timer to absorb delayed messages).
330         </para>
331         <example>
332             <title><function>t_release</function> usage</title>
333             <programlisting>
334 ...
335 t_release();
336 ...
337             </programlisting>
338         </example>
339     </section>
340
341     <section id="t_forward_nonack">
342         <title>
343             <function>t_forward_nonack(ip, port)</function>
344         </title>
345         <para>
346             mainly for internal usage--forward a non-ACK request statefully.
347         </para>
348         <para>Meaning of the parameters is as follows:</para>
349         <itemizedlist>
350             <listitem>
351                 <para><emphasis>ip</emphasis> - IP address where the message should be sent.
352                 </para>
353             </listitem>
354             <listitem>
355                 <para><emphasis>port</emphasis> - Port number.
356                 </para>
357             </listitem>
358         </itemizedlist>
359         <example>
360             <title><function>t_forward_nonack</function> usage</title>
361             <programlisting>
362 ...
363 t_forward_nonack("1.2.3.4", "5060");
364 ...
365             </programlisting>
366         </example>
367     </section>
368
369         <section id="t_set_fr">
370         <title>
371             <function>t_set_fr(fr_inv_timeout [, fr_timeout])</function>
372         </title>
373         <para>
374                 Sets the fr_inv_timeout and optionally fr_timeout for the current
375                 transaction or for transactions created during the same script 
376                 invocation, after calling this function.
377                 If the transaction is already created (e.g called after
378                  <function>t_relay()</function> or in an onreply_route) all the
379                  branches will have their final response timeout updated on-the-fly.
380                 If one of the parameters is 0, it's value won't be changed.
381         </para>
382         <para>Meaning of the parameters is as follows:</para>
383         <itemizedlist>
384             <listitem>
385                 <para><emphasis>fr_inv_timeout</emphasis> - new final response timeout
386                         (in milliseconds) for INVITEs. See also 
387                         <varname>fr_inv_timer</varname>.
388                 </para>
389                 <para><emphasis>fr_timeout</emphasis> - new final response timeout
390                         (in milliseconds) for non-INVITE transaction, or INVITEs which 
391                         haven't received yet a provisional response. See also
392                         <varname>fr_timer</varname>.
393                 </para>
394             </listitem>
395         </itemizedlist>
396         <example>
397             <title><function>t_set_fr</function> usage</title>
398             <programlisting>
399 ...
400 route { 
401         t_set_fr(10000); # set only fr invite timeout to 10s
402         t_on_branch("1");
403         t_relay(); 
404
405
406 branch_route[1] {
407         # if we are calling the pstn, extend the invite timeout to 50s
408         # for all the branches, and set the no-reply-received timeout to 2s
409         if (uri=~"sip:[0-9]+"){
410                 t_set_fr(50000, 2000); 
411         }
412 }
413             </programlisting>
414         </example>
415         </section>
416
417         <section id="t_set_retr">
418         <title>
419             <function>t_set_retr(retr_t1_interval, retr_t2_interval)</function>
420         </title>
421         <para>
422                 Sets the retr_t1_interval and retr_t2_interval for the current
423                 transaction or for transactions created during the same script 
424                 invocation, after calling this function.
425                 If one of the parameters is 0, it's value won't be changed.
426                 If the transaction is already created (e.g called after
427                  <function>t_relay()</function> or in an onreply_route) all the
428                  existing branches will have their retransmissions intervals updated 
429                  on-the-fly:
430                  if the retransmission interval for the branch has not yet reached T2
431                   the interval will be reset to retr_t1_interval, else to 
432                   retr_t2_interval. Note that the change will happen after the current
433                   interval expires (after the next retransmission, the next-next 
434                   retransmission will take place at retr_t1_interval or 
435                   retr_t2_interval).
436                  All new branches of the same transaction will start with the new 
437                  values.
438                  This function will work even if it's called in the script before
439                 a transaction creating function (e.g.: t_set_retr(500, 4000);
440                 t_relay()). All new transaction created after this function call, 
441                 during the same script invocation will use the new values.
442                 Note that this function will work only if tm is compile with
443                  -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with
444                  4 bytes).
445         </para>
446         <para>Meaning of the parameters is as follows:</para>
447         <itemizedlist>
448             <listitem>
449                 <para><emphasis>retr_t1_interval</emphasis> - new T1 retransmission
450                         interval (in milliseconds). See also
451                         <varname>retr_t1_timeout</varname>.
452                 </para>
453                 <para><emphasis>retr_t2_interval</emphasis> - new T2 (or maximum) 
454                         retransmission interval (in milliseconds). See also
455                         <varname>retr_t2_timeout</varname>.
456                 </para>
457             </listitem>
458         </itemizedlist>
459         <example>
460             <title><function>t_set_retr</function> usage</title>
461             <programlisting>
462 ...
463 route { 
464         t_set_retr(250, 0); # set only T1 to 250 ms
465         t_on_branch("1");
466         t_relay(); 
467
468
469 branch_route[1] {
470         # if we are calling the a remote pstn, extend T1 and decrease T2
471         # for all the branches
472         if (uri=~"sip:[0-9]+"){
473                 t_set_retr(500, 2000); 
474         }
475 }
476             </programlisting>
477         </example>
478         </section>
479
480         <section id="t_branch_timeout">
481         <title>
482             <function>t_branch_timeout()</function>
483         </title>
484         <para>
485                 Returns true if the failure route is executed for a branch that did
486                 timeout. It can be used only from the 
487                 <emphasis>failure_route</emphasis>.
488         </para>
489         <example>
490             <title><function>t_branch_timeout</function> usage</title>
491             <programlisting>
492 ...
493 failure_route[0]{ 
494         if (t_branch_timeout()){
495                 log("timeout\n");
496                 # ... 
497         }
498
499             </programlisting>
500         </example>
501         </section>
502
503 <section id="t_branch_replied">
504         <title>
505             <function>t_branch_replied()</function>
506         </title>
507         <para>
508                 Returns true if the failure route is executed for a branch that did
509                 receive at least one reply in the past (the "current" reply is not 
510                 taken into account). It can be used only from the 
511                 <emphasis>failure_route</emphasis>.
512         </para>
513         <example>
514             <title><function>t_branch_replied</function> usage</title>
515             <programlisting>
516 ...
517 failure_route[0]{ 
518         if (t_branch_timeout()){
519                 if (t_branch_replied())
520                         log("timeout after receiving a reply (no answer?)\n");
521                 else
522                         log("timeout, remote side seems to be down\n");
523                 # ... 
524         }
525
526             </programlisting>
527         </example>
528         </section>
529
530 <section id="t_any_timeout">
531         <title>
532             <function>t_any_timeout()</function>
533         </title>
534         <para>
535                 Returns true if at least one of the current transactions branches
536                 did timeout.
537         </para>
538         <example>
539             <title><function>t_any_timeout</function> usage</title>
540             <programlisting>
541 ...
542 failure_route[0]{ 
543         if (!t_branch_timeout()){
544                 if (t_any_timeout()){
545                         log("one branch did timeout\n");
546                         sl_send_reply("408", "Timeout");
547                 }
548         }
549
550             </programlisting>
551         </example>
552         </section>
553
554 <section id="t_any_replied">
555         <title>
556             <function>t_any_replied()</function>
557         </title>
558         <para>
559                 Returns true if at least one of the current transactions branches
560                 did receive some reply in the past. If called from a failure or
561                 onreply route, the "current" reply is not taken into account.
562         </para>
563         <example>
564             <title><function>t_any_replied</function> usage</title>
565             <programlisting>
566 ...
567 onreply_route[0]{ 
568         if (!t_any_replied()){
569                 log("first reply received\n");
570                 # ...
571         }
572
573             </programlisting>
574         </example>
575 </section>
576
577 <section id="t_grep_status">
578         <title>
579             <function>t_grep_status("code")</function>
580         </title>
581         <para>
582                 Returns true if "code" is the the final reply received (or locally
583                  generated) in at least one of the current transactions branches.
584         </para>
585         <example>
586             <title><function>t_grep_status</function> usage</title>
587             <programlisting>
588 ...
589 onreply_route[0]{ 
590         if (t_grep_status("486")){
591                 /* force a 486 reply, even if this is not the winning branch */
592                 t_reply("486", "Busy");
593         }
594
595             </programlisting>
596         </example>
597 </section>
598
599 <section id="t_is_canceled">
600         <title>
601             <function>t_is_canceled()</function>
602         </title>
603         <para>
604                 Returns true if the current transaction was canceled.
605         </para>
606         <example>
607             <title><function>t_is_canceled</function> usage</title>
608             <programlisting>
609 ...
610 failure_route[0]{ 
611         if (t_is_canceled()){
612                 log("transaction canceled\n");
613                 # ...
614         }
615
616             </programlisting>
617         </example>
618         </section>
619
620     <section id="t_relay_cancel">
621         <title>
622             <function>t_relay_cancel()</function>
623         </title>
624         <para>
625                 Forwards the CANCEL if the corresponding INVITE transaction
626                 exists. The function is supposed to be used at the very
627                 beginning of the script, because the CANCELs can be caught
628                 and the rest of the script can be bypassed this way. Do not disable
629                 <varname>reparse_invite</varname> module parameter, and call
630                 <varname>t_relay_cancel()</varname> right after the sanity tests.
631         </para>
632         <para>
633                 Return value is 0 (drop) if the corresponding INVITE was found
634                 and the CANCELs were successfully sent to the pending branches,
635                 true if the INVITE was not found, and false in case of any error.
636         </para>
637         <example>
638             <title><function>t_relay_cancel</function> usage</title>
639             <programlisting>
640
641 if (method == CANCEL) {
642         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
643                                   # nothing to do
644
645                 # corresponding INVITE transaction found but error occurred
646                 sl_reply("500", "Internal Server Error");
647                 drop;
648         }
649         # bad luck, corresponding INVITE transaction is missing,
650         # do the same as for INVITEs
651 }
652             </programlisting>
653         </example>
654     </section>
655
656     <section id="t_drop_replies">
657         <title>
658             <function>t_drop_replies()</function>
659         </title>
660         <para>
661                 Drops all the previously received replies in failure_route
662                 block to make sure that none of them is picked up again.
663                 Works only if a new branch is added to the transaction,
664                 or it is explicitly replied in the script!
665         </para>
666         <example>
667             <title><function>t_drop_replies()</function> usage</title>
668             <programlisting>
669 ...
670 failure_route[0]{ 
671         if (t_check_status("5[0-9][0-9]")){
672                 # I do not like the 5xx responses,
673                 # so I give another chance to "foobar.com",
674                 # and I drop all the replies to make sure that
675                 # they are not forwarded to the caller.
676                 t_drop_replies();
677                 
678                 rewritehostport("foobar.com");
679                 append_branch();
680                 t_relay();
681         }
682
683             </programlisting>
684         </example>
685     </section>
686 </section>