Merge remote branch 'origin/andrei/cancel_reason'
authorAndrei Pelinescu-Onciul <andrei@iptel.org>
Fri, 13 Aug 2010 19:44:36 +0000 (21:44 +0200)
committerAndrei Pelinescu-Onciul <andrei@iptel.org>
Fri, 13 Aug 2010 19:44:36 +0000 (21:44 +0200)
CANCEL Reason support, according to RFC 3326.
The Reason headers are added both for CANCELs generated due to a
received final reply and hop by hop CANCELs generated because of
a received CANCEL. Both cases can be turned on/off individually.

* origin/andrei/cancel_reason:
  tm: no reason modparams if compiled with no cancelr. support
  tm: option to compile without reason support
  tm: docs: reason header modparams and script function
  tm: improved Reason support for E2E CANCELs
  tm: fix Reason generation for on-the-fly branch CANCELs
  tm: CANCEL reason header on/off switches
  tm: Reason header copy for received CANCELs
  tm: Reason header generation for local CANCELs

16 files changed:
1  2 
NEWS
modules/tm/README
modules/tm/doc/functions.xml
modules/tm/doc/params.xml
modules/tm/doc/tm.xml
modules/tm/h_table.c
modules/tm/h_table.h
modules/tm/t_cancel.c
modules/tm/t_cancel.h
modules/tm/t_fwd.c
modules/tm/t_lookup.c
modules/tm/t_msgbuilder.c
modules/tm/t_reply.c
modules/tm/t_reply.h
modules/tm/timer.c
modules/tm/tm.c

diff --cc NEWS
--- 1/NEWS
--- 2/NEWS
+++ b/NEWS
@@@ -99,16 -37,24 +99,33 @@@ modules
              the mask for possible local replies to the current message.
             blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
              clears instead of setting.
 +   - tls:
 +           new options for better tuning memory usage for modern openssl
 +            versions: ssl_release_buffers, ssl_freelist_max_len,
 +            ssl_max_send_fragment, ssl_read_ahead. For more info see
 +            modules/doc/tls/README.
 +           compression is now disabled by default. To enable it set
 +            tls_disable_compression to 0, but note that memory usage will
 +            increase dramatically especially for large number of
 +            connections (>1000).
  tm:
+    - reason header support (RFC3326) both for CANCELs generated due to a
+       received final reply and for hop by hop CANCELs generated because of a
+       received CANCEL.
+       E.g.: reason header added for a CANCEL generated after a 200 reply was
+             received on one of the branches "Reason: SIP;cause=200".
+       The reason header support can be turned on/off using either tm
+       module parameters or in the end to end CANCEL case also on a per
+       transaction basis, using a script function:
+        local_cancel_reason = 0 | 1 (default 1/on) - turns on adding reason
+          headers for CANCELs generated due to a final reply. Can be changed
+          at runtime.
+        e2e_cancel_reason = 0 | 1 (default 1/on) - turns on copying reason
+          headers from a received end to end CANCEL (the generated hop by hop
+          CANCELs will have the same reason headers as the received CANCEL).
+          Can be changed at runtime.
+        t_set_no_e2e_cancel_reason(0|1) - enable/disable cancel reason 
+          header copying on a per transaction basis (0 - enable, 1 disable).
     - t_reply() can be used both from the main/core onreply_route{} and tm
       onreply_route[...]{}s.
  
@@@ -45,18 -45,20 +45,20 @@@ Juha Heinane
          1.4.23. cancel_b_method (integer)
          1.4.24. reparse_on_dns_failover (integer)
          1.4.25. on_sl_reply (string)
 -        1.4.26. fr_inv_timer_next (integer)
 -        1.4.27. contacts_avp (string)
 -        1.4.28. fr_timer_avp (string)
 -        1.4.29. fr_inv_timer_avp (string)
 -        1.4.30. unmatched_cancel (string)
 -        1.4.31. ruri_matching (integer)
 -        1.4.32. via1_matching (integer)
 -        1.4.33. pass_provisional_replies (integer)
 -        1.4.34. default_code (integer)
 -        1.4.35. default_reason (string)
 -        1.4.36. disable_6xx_block (integer)
 -        1.4.37. local_ack_mode (integer)
 +        1.4.26. contacts_avp (string)
 +        1.4.27. fr_timer_avp (string)
 +        1.4.28. fr_inv_timer_avp (string)
 +        1.4.29. unmatched_cancel (string)
 +        1.4.30. ruri_matching (integer)
 +        1.4.31. via1_matching (integer)
 +        1.4.32. pass_provisional_replies (integer)
 +        1.4.33. default_code (integer)
 +        1.4.34. default_reason (string)
 +        1.4.35. disable_6xx_block (integer)
 +        1.4.36. local_ack_mode (integer)
 +        1.4.37. failure_reply_mode (integer)
+         1.4.38. local_cancel_reason (boolean)
+         1.4.39. e2e_cancel_reason (boolean)
  
     1.5. Functions
  
  modparam("tm", "local_ack_mode", 1)
  ...
  
 +1.4.37. failure_reply_mode (integer)
 +
 +   It controls how branches are managed and replies are selected for
 +   failure_route handling: keep all, drop all, drop last branches in SIP
 +   serial forking handling.
 +
 +   To control per transaction see t_drop_replies().
 +
 +   It has 4 possible values:
 +     * 0 - all branches are kept, no matter a new leg of serial forking
 +       has been started. Beware that if the new leg fails, you may get in
 +       failure_route a reply code from a branch of previous serial forking
 +       legs (e.g., if in first leg you got a 3xx, then you handled the
 +       redirection in failure route, sent to a new destination and this
 +       one timeout, you will get again the 3xx). Use t_drop_replies() on
 +       per transaction fashion to control the behavior you want. It is the
 +       default behaviour comming from SER 2.1.x.
 +     * 1 - all branches are discarded by default. You can still overwrite
 +       the behaviour via t_drop_replies()
 +     * 2 - by default only the branches of previous leg of serial forking
 +       are discarded
 +     * 3 - all previous branches are discarded if there is a new serial
 +       forking leg. This is the default behaviour coming from Kamailio
 +       1.5.x. Use this mode if you don't want to handle in a per
 +       transaction fashion with t_drop_replies(). It ensures that you will
 +       get the winning reply from the branches of last serial forking step
 +       (e.g., if in first step you get 3xx, then you forward to a new
 +       destination, you will get in failure_route the reply coming from
 +       that destination or a local timeout).
 +
 +   The default value is 0.
 +
 +   Example 37. Set failure_reply_mode parameter
 +...
 +modparam("tm", "failure_reply_mode", 3)
 +...
 +
+ 1.4.38. local_cancel_reason (boolean)
+    Enables/disables adding reason headers (RFC 3326) for CANCELs generated
+    due to receiving a final reply. The reason header added will look like:
+    "Reason: SIP;cause=<final_reply_code>".
+    Default value is 1 (enabled).
+    Can be set at runtime, e.g.:
+         $ sercmd cfg.set_now_int tm local_cancel_reason 0
+    See also: e2e_cancel_reason.
+    Example 38. Set local_cancel_reason parameter
+ ...
+ modparam("tm", "local_cancel_reason", "0")
+ ...
+ 1.4.39. e2e_cancel_reason (boolean)
+    Enables/disables adding reason headers (RFC 3326) for CANCELs generated
+    due to a received CANCEL. If enabled the reason headers from received
+    CANCELs will be copied into the generated hop-by-hop CANCELs.
+    Default value is 1 (enabled).
+    Can be changed at runtime, e.g.:
+         $ sercmd cfg.set_now_int tm e2e_cancel_reason 0
+    See also: t_set_no_e2e_cancel_reason() and local_cancel_reason.
+    Example 39. Set e2e_cancel_reason parameter
+ ...
+ modparam("tm", "e2e_cancel_reason", "0")
+ ...
  1.5. Functions
  
     Revision History
@@@ -1869,12 -1923,11 +1908,12 @@@ if (!t_load_contacts()) 
     that retransmits 180 periodically will keep resetting the fr_inv_timer
     value and serial forking never happens.
  
 -   Also make sure that you configured fr_inv_timer_next with lower value,
 -   especially if you expect to have many serially forked branches. See the
 -   documentation of that parameter for more details.
 +   Before calling t_relay(), you can check if the previous call of
 +   next_contacts() consumed all branches by checking if contact_avp is not
 +   anymore set. Based on that test, you can then use t_set_fr() function
 +   to set timers according to your needs.
  
-    Example 69. t_next_contacts usage
+    Example 71. t_next_contacts usage
  ...
  # First call after t_load_contacts() when transaction does not exist yet
  # and contacts should be available
Simple merge
@@@ -1117,59 -1167,67 +1119,121 @@@ modparam("tm", "local_ack_mode", 1
            </programlisting>
        </example>
        </section>
 +      
 +      <section id="failure_reply_mode">
 +      <title><varname>failure_reply_mode</varname> (integer)</title>
 +      <para>
 +              It controls how branches are managed and replies are selected for
 +              failure_route handling: keep all, drop all, drop last branches in
 +              SIP serial forking handling.
 +      </para>
 +      <para>
 +              To control per transaction see <function>t_drop_replies()</function>.
 +      </para>
 +      <para> It has 4 possible values:</para>
 +      <itemizedlist>
 +              <listitem><para>
 +              <emphasis>0</emphasis> - all branches are kept, no matter a new leg of
 +              serial forking has been started. Beware that if the new leg fails, you
 +              may get in failure_route a reply code from a branch of previous serial
 +              forking legs (e.g., if in first leg you got a 3xx, then you handled
 +              the redirection in failure route, sent to a new destination and this
 +              one timeout, you will get again the 3xx). Use t_drop_replies() on per
 +              transaction fashion to control the behavior you want. It is the
 +              default behaviour comming from SER 2.1.x.
 +              </para></listitem>
 +              <listitem><para>
 +              <emphasis>1</emphasis> - all branches are discarded by default. You
 +              can still overwrite the behaviour via t_drop_replies()
 +              </para></listitem>
 +              <listitem><para>
 +              <emphasis>2</emphasis> - by default only the branches of previous leg
 +              of serial forking are discarded
 +              </para></listitem>
 +              <listitem><para>
 +              <emphasis>3</emphasis> - all previous branches are discarded if there
 +              is a new serial forking leg. This is the default behaviour coming from
 +              Kamailio 1.5.x. Use this mode if you don't want to handle in a per
 +              transaction fashion with t_drop_replies(). It ensures that you will
 +              get the winning reply from the branches of last serial forking step
 +              (e.g., if in first step you get 3xx, then you forward to a new
 +              destination, you will get in failure_route the reply coming from that
 +              destination or a local timeout).
 +              </para></listitem>
 +      </itemizedlist>
 +      <para>
 +              The default value is 0.
 +      </para>
 +      <example>
 +              <title>Set <varname>failure_reply_mode</varname> parameter</title>
 +              <programlisting>
 +...
 +modparam("tm", "failure_reply_mode", 3)
 +...
 +          </programlisting>
 +      </example>
 +      </section>
  
+       <section id="local_cancel_reason">
+               <title><varname>local_cancel_reason</varname> (boolean)</title>
+               <para>
+                       Enables/disables adding reason headers (RFC 3326) for CANCELs
+                       generated due to receiving a final reply. The reason header added
+                       will look like: "Reason: SIP;cause=&lt;final_reply_code&gt;".
+               </para>
+               <para>
+                       Default value is 1 (enabled).
+               </para>
+               <para>
+                       Can be set at runtime, e.g.:
+                       <programlisting>
+       $ sercmd cfg.set_now_int tm local_cancel_reason 0
+                       </programlisting>
+               </para>
+               <para>
+                       See also: <varname>e2e_cancel_reason</varname>.
+               </para>
+               <example>
+                       <title>Set <varname>local_cancel_reason</varname> parameter</title>
+                       <programlisting>
+ ...
+ modparam("tm", "local_cancel_reason", "0")
+ ...
+                       </programlisting>
+               </example>
+       </section>
+       <section id="e2e_cancel_reason">
+               <title><varname>e2e_cancel_reason</varname> (boolean)</title>
+               <para>
+                       Enables/disables adding reason headers (RFC 3326) for CANCELs
+                       generated due to a received CANCEL.  If enabled the reason headers
+                       from received CANCELs will be copied into the generated hop-by-hop
+                       CANCELs.
+               </para>
+               <para>
+                       Default value is 1 (enabled).
+               </para>
+               <para>
+                       Can be changed at runtime, e.g.:
+                       <programlisting>
+       $ sercmd cfg.set_now_int tm e2e_cancel_reason 0
+                       </programlisting>
+               </para>
+               <para>
+                       See also: <function>t_set_no_e2e_cancel_reason()</function> and
+                                               <varname>local_cancel_reason</varname>.
+               </para>
+               <example>
+                       <title>Set <varname>e2e_cancel_reason</varname> parameter</title>
+                       <programlisting>
+ ...
+ modparam("tm", "e2e_cancel_reason", "0")
+ ...
+                       </programlisting>
+               </example>
+       </section>
  </section>
Simple merge
Simple merge
Simple merge
Simple merge
Simple merge
Simple merge
Simple merge
Simple merge
@@@ -596,20 -595,17 +605,23 @@@ static int _reply_light( struct cell *t
        /* do UAC cleanup procedures in case we generated
           a final answer whereas there are pending UACs */
        if (code>=200) {
 -              if (unlikely(is_local(trans) && 
 -                                      has_tran_tmcbs(trans, TMCB_LOCAL_COMPLETED) ))
 -                      run_trans_callbacks(TMCB_LOCAL_COMPLETED, trans,
 +              if (unlikely(is_local(trans))) {
 +                      if(unlikely(has_tran_tmcbs(trans, TMCB_LOCAL_COMPLETED)))
 +                              run_trans_callbacks(TMCB_LOCAL_COMPLETED, trans,
                                                                        0, FAKED_REPLY, code);
 +              } else {
 +                      if(unlikely(has_tran_tmcbs(trans, TMCB_RESPONSE_READY))) {
 +                              run_trans_callbacks(TMCB_RESPONSE_READY, trans,
 +                                      trans->uas.request, FAKED_REPLY, code);
 +                      }
 +              }
                cleanup_uac_timers( trans );
                if (is_invite(trans)){
-                       prepare_to_cancel(trans, &cancel_bitmap, 0);
-                       cancel_uacs( trans, cancel_bitmap, F_CANCEL_B_KILL );
+                       prepare_to_cancel(trans, &cancel_data.cancel_bitmap, 0);
+ #ifdef CANCEL_REASON_SUPPORT
+                       cancel_data.reason.cause=code;
+ #endif /* CANCEL_REASON_SUPPORT */
+                       cancel_uacs( trans, &cancel_data, F_CANCEL_B_KILL );
                }
                start_final_repl_retr(  trans );
        }
Simple merge
Simple merge
diff --cc modules/tm/tm.c
@@@ -501,7 -549,10 +515,11 @@@ static param_export_t params[]=
        {"contacts_avp",        PARAM_STRING, &contacts_avp_param                },
        {"disable_6xx_block",   PARAM_INT, &default_tm_cfg.disable_6xx           },
        {"local_ack_mode",      PARAM_INT, &default_tm_cfg.local_ack_mode        },
 +      {"failure_reply_mode",  PARAM_INT, &failure_reply_mode                   },
+ #ifdef CANCEL_REASON_SUPPORT
+       {"local_cancel_reason", PARAM_INT, &default_tm_cfg.local_cancel_reason   },
+       {"e2e_cancel_reason",   PARAM_INT, &default_tm_cfg.e2e_cancel_reason     },
+ #endif /* CANCEL_REASON_SUPPORT */
        {0,0,0}
  };