git.sip-router.org Git - sip-router/blob - 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
 687     <section id="t_save_lumps">
 688         <title>
 689             <function>t_save_lumps()</function>
 690         </title>
 691         <para>
 692                 Forces the modifications of the processed SIP message
 693                 to be saved in shared memory before t_relay() is called.
 694                 The new branches which are created in failure_route will
 695                 contain the same modifications, and any other modification
 696                 after t_save_lumps() will be lost.
 697         </para>
 698         <para>
 699                 Note that t_relay() automatically saves the modifications
 700                 when it is called the first time, there is no need for
 701                 t_save_lumps() unless message changes between t_save_lumps()
 702                 and t_relay() must not be propagated to failure_route.
 703         </para>
 704         <para>
 705                 The transaction must be created by t_newtran() before
 706                 calling t_save_lumps().
 707         </para>
 708         <example>
 709             <title><function>t_save_lumps()</function> usage</title>
 710             <programlisting>
 711 route {
 712         ...
 713         t_newtran();
 714         append_hf("hf1: my first header\r\n");
 715         ...
 716         t_save_lumps();
 717         append_hf("hf2: my second header\r\n");
 718         ...
 719         t_on_failure("1");
 720         t_relay();
 721 }
 722
 723 failure_route[1] {
 724         append_branch();
 725         append_hf("hf3: my third header\r\n");
 726         #
 727         # This branch contains hf1 and hf3, but does
 728         # not contain hf2 header.
 729         # hf2 would be also present here without
 730         # t_save_lumps().
 731         ...
 732         t_relay();
 733 }
 734             </programlisting>
 735         </example>
 736     </section>
 737 </section>