modules/tmx: added new function t_reuse_branch()

modules/tmx/README

@@ -1,4 +1,3 @@
-
 TMX Module
 
 Daniel-Constantin Mierla
@@ -6,14 +5,25 @@ Daniel-Constantin Mierla
    asipto.com
    <[email protected]>
 
+Juha Heinanen
+
+   TutPro Inc.
+   <[email protected]>
+
 Edited by
 
 Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2009 Daniel-Constantin Mierla
-     _________________________________________________________________
+Edited by
+
+Juha Heinanen
+
+   <[email protected]>
+
+   Copyright (c) 2009 Daniel-Constantin Mierla
+     __________________________________________________________________
 
    Table of Contents
 
@@ -27,24 +37,25 @@ Daniel-Constantin Mierla
 
         3. Functions
 
-              3.1. t_cancel_branches(which) 
-              3.2. t_cancel_callid(callid, cseq, flag) 
-              3.3. t_reply_callid(callid, cseq, code, reason) 
-              3.4. t_flush_flags() 
-              3.5. t_is_failure_route() 
-              3.6. t_is_branch_route() 
-              3.7. t_is_reply_route() 
-              3.8. t_suspend() 
-              3.9. t_continue(tindex, tlabel, rtname) 
+              3.1. t_cancel_branches(which)
+              3.2. t_cancel_callid(callid, cseq, flag)
+              3.3. t_reply_callid(callid, cseq, code, reason)
+              3.4. t_flush_flags()
+              3.5. t_is_failure_route()
+              3.6. t_is_branch_route()
+              3.7. t_is_reply_route()
+              3.8. t_suspend()
+              3.9. t_continue(tindex, tlabel, rtname)
+              3.10. t_reuse_branch()
 
         4. Exported pseudo-variables
         5. MI Commands
 
-              5.1. t_uac_dlg 
-              5.2. t_uac_cancel 
-              5.3. t_hash 
-              5.4. t_reply 
-              5.5. t_reply_callid 
+              5.1. t_uac_dlg
+              5.2. t_uac_cancel
+              5.3. t_hash
+              5.4. t_reply
+              5.5. t_reply_callid
 
         6. Statistics
 
@@ -71,6 +82,7 @@ Daniel-Constantin Mierla
    1.7. t_is_reply_route usage
    1.8. t_suspend usage
    1.9. t_continue usage
+   1.10. t_reuse_branch usage
 
 Chapter 1. Admin Guide
 
@@ -84,24 +96,25 @@ Chapter 1. Admin Guide
 
    3. Functions
 
-        3.1. t_cancel_branches(which) 
-        3.2. t_cancel_callid(callid, cseq, flag) 
-        3.3. t_reply_callid(callid, cseq, code, reason) 
-        3.4. t_flush_flags() 
-        3.5. t_is_failure_route() 
-        3.6. t_is_branch_route() 
-        3.7. t_is_reply_route() 
-        3.8. t_suspend() 
-        3.9. t_continue(tindex, tlabel, rtname) 
+        3.1. t_cancel_branches(which)
+        3.2. t_cancel_callid(callid, cseq, flag)
+        3.3. t_reply_callid(callid, cseq, code, reason)
+        3.4. t_flush_flags()
+        3.5. t_is_failure_route()
+        3.6. t_is_branch_route()
+        3.7. t_is_reply_route()
+        3.8. t_suspend()
+        3.9. t_continue(tindex, tlabel, rtname)
+        3.10. t_reuse_branch()
 
    4. Exported pseudo-variables
    5. MI Commands
 
-        5.1. t_uac_dlg 
-        5.2. t_uac_cancel 
-        5.3. t_hash 
-        5.4. t_reply 
-        5.5. t_reply_callid 
+        5.1. t_uac_dlg
+        5.2. t_uac_cancel
+        5.3. t_hash
+        5.4. t_reply
+        5.5. t_reply_callid
 
    6. Statistics
 
@@ -136,25 +149,26 @@ Chapter 1. Admin Guide
 
 2.2. External Libraries or Applications
 
-   The  following  libraries  or  applications  must  be installed before
+   The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * None.
 
 3. Functions
 
-   3.1. t_cancel_branches(which) 
-   3.2. t_cancel_callid(callid, cseq, flag) 
-   3.3. t_reply_callid(callid, cseq, code, reason) 
-   3.4. t_flush_flags() 
-   3.5. t_is_failure_route() 
-   3.6. t_is_branch_route() 
-   3.7. t_is_reply_route() 
-   3.8. t_suspend() 
-   3.9. t_continue(tindex, tlabel, rtname) 
+   3.1. t_cancel_branches(which)
+   3.2. t_cancel_callid(callid, cseq, flag)
+   3.3. t_reply_callid(callid, cseq, code, reason)
+   3.4. t_flush_flags()
+   3.5. t_is_failure_route()
+   3.6. t_is_branch_route()
+   3.7. t_is_reply_route()
+   3.8. t_suspend()
+   3.9. t_continue(tindex, tlabel, rtname)
+   3.10. t_reuse_branch()
 
 3.1.  t_cancel_branches(which)
 
-   Cancel  branches  of  an  active  SIP transaction. The function can be
+   Cancel branches of an active SIP transaction. The function can be
    called for a SIP reply that will identify the current branch.
 
    Parameter can be:.
@@ -211,9 +225,9 @@ if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
 
 3.4.  t_flush_flags()
 
-   Flush  the  flags  from  current  SIP message into the already created
-   transaction.  It  make  sense only in routing block if the transaction
-   was created via t_newtran() and the flags have been altered since.
+   Flush the flags from current SIP message into the already created
+   transaction. It make sense only in routing block if the transaction was
+   created via t_newtran() and the flags have been altered since.
 
    This function can be used from ANY_ROUTE .
 
@@ -275,8 +289,8 @@ route[abc] {
 
 3.8.  t_suspend()
 
-   Suspend  the execution of SIP request in a transaction. If transaction
-   was  not  created yet, it is created by this function. Returns true in
+   Suspend the execution of SIP request in a transaction. If transaction
+   was not created yet, it is created by this function. Returns true in
    case of success and internal transaction index and label are available
    via $T(id_index) and $T(id_label).
 
@@ -293,15 +307,15 @@ if(t_suspend())
 
 3.9.  t_continue(tindex, tlabel, rtname)
 
-   Continue  the  execution  of  the transaction identified by tindex and
+   Continue the execution of the transaction identified by tindex and
    tlabel with the actions defined in route[rtname].
 
    Parameters:.
-     * tindex  -  internal  index  of transaction. Can be an integer or a
+     * tindex - internal index of transaction. Can be an integer or a
        pseudo-variable.
-     * tlabel  -  internal  label  of transaction. Can be an integer or a
+     * tlabel - internal label of transaction. Can be an integer or a
        pseudo-variable.
-     * rtname  -  the name of the route block to execute. Can be a static
+     * rtname - the name of the route block to execute. Can be a static
        string value or a dynamic string with pseudo-variables.
 
    This function can be used in ANY_ROUTE.
@@ -311,6 +325,25 @@ if(t_suspend())
 tcontinue('123', '456', 'MYROUTE');
 ...
 
+3.10.  t_reuse_branch()
+
+   Creates new "main" branch by making copy of branch-failure branch.
+   Currently the following branch attributes are copied from
+   branch-failure branch: request-uri, ruid, path, instance, and branch
+   flags.
+
+   This function can be used from tm:branch-failure event_route.
+
+   Example 1.10. t_reuse_branch usage
+...
+event_route [tm:branch-failure:contact] {
+    t_reuse_branch();
+    setbflag(10);
+    t_relay();
+    exit;
+}
+...
+
 4. Exported pseudo-variables
 
      * $T_branch_idx
@@ -322,15 +355,15 @@ tcontinue('123', '456', 'MYROUTE');
      * $T_reply_ruid
 
    Exported pseudo-variables are documented at
-   http://www.kamailio.org/dokuwiki/.
+   http://www.kamailio.org/wiki/.
 
 5. MI Commands
 
-   5.1. t_uac_dlg 
-   5.2. t_uac_cancel 
-   5.3. t_hash 
-   5.4. t_reply 
-   5.5. t_reply_callid 
+   5.1. t_uac_dlg
+   5.2. t_uac_cancel
+   5.3. t_hash
+   5.4. t_reply
+   5.5. t_reply_callid
 
 5.1.  t_uac_dlg
 
@@ -340,11 +373,11 @@ tcontinue('123', '456', 'MYROUTE');
      * method - request method
      * RURI - request SIP URI
      * NEXT HOP - next hop SIP URI (OBP); use "." if no value.
-     * socket  - local socket to be used for sending the request; use "."
+     * socket - local socket to be used for sending the request; use "."
        if no value.
      * headers - set of additional headers to be added to the request; at
        least "From" and "To" headers must be specify)
-     * body  -  (optional,  may not be present) request body (if present,
+     * body - (optional, may not be present) request body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
 5.2.  t_uac_cancel
@@ -369,12 +402,11 @@ tcontinue('123', '456', 'MYROUTE');
    Parameters:
      * code - reply code
      * reason - reason phrase.
-     * trans_id   -  transaction  identifier  (has  the  hash_entry:label
-       format)
+     * trans_id - transaction identifier (has the hash_entry:label format)
      * to_tag - To tag to be added to TO header
      * new_headers - extra headers to be appended to the reply; use a dot
        (".") char only if there are no headers;
-     * body  -  (optional,  may  not  be present) reply body (if present,
+     * body - (optional, may not be present) reply body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
 5.5.  t_reply_callid
@@ -389,7 +421,7 @@ tcontinue('123', '456', 'MYROUTE');
      * to_tag - To tag to be added to TO header
      * new_headers - extra headers to be appended to the reply; use a dot
        (".") char only if there are no headers;
-     * body  -  (optional,  may  not  be present) reply body (if present,
+     * body - (optional, may not be present) reply body (if present,
        requires the "Content-Type" and "Content-length" headers)
 
 6. Statistics
@@ -406,7 +438,7 @@ tcontinue('123', '456', 'MYROUTE');
    6.10. 6xx_transactions
    6.11. inuse_transactions
 
-   Exported  statistics  are  listed in the next sections. All statistics
+   Exported statistics are listed in the next sections. All statistics
    except "inuse_transactions" can be reset.
 
 6.1. received_replies

modules/tmx/doc/tmx.xml

@@ -24,11 +24,22 @@
 		</otheraddr>
 		</address>
 	    </author>
+	    <author>
+		<firstname>Juha</firstname>
+		<surname>Heinanen</surname>
+		<affiliation><orgname>TutPro Inc.</orgname></affiliation>
+		<email>[email protected]</email>
+	    </author>
 	    <editor>
 		<firstname>Daniel-Constantin</firstname>
 		<surname>Mierla</surname>
 		<email>[email protected]</email>
 	    </editor>
+	    <editor>
+		<firstname>Juha</firstname>
+		<surname>Heinanen</surname>
+		<email>[email protected]</email>
+	    </editor>
 	</authorgroup>
 	<copyright>
 	    <year>2009</year>

modules/tmx/doc/tmx_admin.xml

@@ -332,6 +332,36 @@ tcontinue('123', '456', 'MYROUTE');
 </programlisting>
 		</example>
 	</section>
+
+	<section>
+		<title>
+		<function moreinfo="none">t_reuse_branch()
+		</function>
+		</title>
+		<para>
+		Creates new "main" branch by making copy of branch-failure
+                branch. Currently the following branch attributes are copied
+		from branch-failure branch: request-uri, ruid, path, instance,
+		and branch flags.
+		</para>
+		<para>
+		This function can be used from tm:branch-failure event_route.
+		</para>
+		<example>
+		<title><function>t_reuse_branch</function> usage</title>
+		<programlisting format="linespecific">
+...
+event_route [tm:branch-failure:contact] {
+    t_reuse_branch();
+    setbflag(10);
+    t_relay();
+    exit;
+}
+...
+</programlisting>
+		</example>
+	</section>
+
 	</section>
 
 	<section>

modules/tmx/tmx_mod.c

@@ -30,6 +30,7 @@
 #include "../../route.h"
 #include "../../modules/tm/tm_load.h"
 #include "../../lib/kcore/kstats_wrapper.h"
+#include "../../dset.h"
 
 #include "t_var.h"
 #include "t_mi.h"
@@ -63,6 +64,7 @@ static int t_is_reply_route(struct sip_msg* msg, char*, char*);
 
 static int w_t_suspend(struct sip_msg* msg, char*, char*);
 static int w_t_continue(struct sip_msg* msg, char *idx, char *lbl, char *rtn);
+static int w_t_reuse_branch(struct sip_msg* msg, char*, char*);
 static int fixup_t_continue(void** param, int param_no);
 
 static int bind_tmx(tmx_api_t* api);
@@ -171,6 +173,8 @@ static cmd_export_t cmds[]={
 			0, ANY_ROUTE  },
 	{"t_continue", (cmd_function)w_t_continue,     3,
 		fixup_t_continue, 0, ANY_ROUTE },
+	{"t_reuse_branch", (cmd_function)w_t_reuse_branch, 0, 0, 0,
+	 EVENT_ROUTE },
 	{"bind_tmx", (cmd_function)bind_tmx, 1,
 		0, 0, ANY_ROUTE },
 	{0,0,0,0,0,0}
@@ -574,6 +578,49 @@ static int w_t_continue(struct sip_msg* msg, char *idx, char *lbl, char *rtn)
 	return 1;
 }
 
+/**
+ * Creates new "main" branch by making copy of branch-failure branch.
+ * Currently the following branch attributes are included:
+ * request-uri, ruid, path, instance, and branch flags.
+ */
+static int w_t_reuse_branch(struct sip_msg* msg, char *p1, char *p2)
+{
+	struct cell *t;
+	int branch;
+
+	if (msg == NULL) return -1;
+
+	/* first get the transaction */
+	if (_tmx_tmb.t_check(msg, 0) == -1) return -1;
+	if ((t = _tmx_tmb.t_gett()) == 0) {
+	    LM_ERR("no transaction\n");
+	    return -1;
+	}
+	switch (get_route_type()) {
+	case BRANCH_FAILURE_ROUTE:
+	    /* use the reason of the winning reply */
+	    if ((branch = _tmx_tmb.t_get_picked_branch()) < 0) {
+		LM_CRIT("no picked branch (%d) for a final response"
+			" in MODE_ONFAILURE\n", branch);
+		return -1;
+	    }
+	    rewrite_uri(msg, &(t->uac[branch].uri));
+	    set_ruid(msg, &(t->uac[branch].ruid));
+	    if (t->uac[branch].path.len) {
+		set_path_vector(msg, &(t->uac[branch].path));
+	    } else {
+		reset_path_vector(msg);
+	    }
+	    setbflagsval(0, t->uac[branch].flags);
+	    set_instance(msg, &(t->uac[branch].instance));
+	    return 1;
+	default:
+	    LM_ERR("unsupported route_type %d\n", get_route_type());
+	    return -1;
+	}
+}
+
+
 /**
  *
  */