[tm] Changes on the new local_reply/request_route mod params

Improve the names of the variables.
Improve docs with more details.
Make `local_reply_route` a generic route, not a onreply route (as it taints the concept of onreply routes)
Related to #3329
Complets 57b122f29e0872b221e40fba6f9e900362f8c2ce

Author: bogdan-iancu

modules/tm/doc/tm_admin.xml

@@ -864,12 +864,29 @@ modparam("tm", "cluster_auto_cancel", no)
 	<section id="param_local_request_route" xreflabel="local_request_route">
 		<title><varname>local_request_route</varname> (string)</title>
 		<para>
-		This parameter points to a route, which is executed whenever TM creates
-		a new request (e.g., through the B2B modules or through MI).
+		This parameter points to a route, which is executed whenever TM is
+		about to send out a locally generated request (e.g., through the 
+		B2B modules or through MI).
 		</para>
 		<para>
-		The route is executed with the generated message by TM, incorporating all
-		modifications.
+		The purpose of this route is limited to exposing the content of the 
+		request as SIP message 
+		</para>
+		<para>
+		The route is executed with the generated message by TM, incorporating
+		all modifications.
+		</para>
+		<para>
+		IMPORTANT: this route is executed AFTER the local_route (if defined)
+		and it expose all the changes from that route.
+		</para>
+		<para>
+		IMPORTANT: this route is to be used in a read-only manner, inspection
+		only. Any changes you do here will discarded.
+		</para>
+		<para>
+		IMPORTANT: this route does not offer any message, transactional or
+		dialog context, so do not rely on any variables with scope (like AVPs).
 		</para>
 		<example>
 		<title>Set the <varname>local_request_route</varname> parameter</title>
@@ -879,7 +896,7 @@ modparam("tm", "cluster_auto_cancel", no)
 modparam("tm", "local_request_route", "tm_local_request")
 
 route[tm_local_request] {
-	if (is_method("INVITE") && $rb(application/sdp) && !has_totag()) {
+	if (is_method("INVITE") &amp;&amp; $rb(application/sdp) &amp;&amp; !has_totag()) {
 		$avp(sdp_request) := $rb(application/sdp);
 	}
 }
@@ -891,18 +908,30 @@ route[tm_local_request] {
 	<section id="param_local_reply_route" xreflabel="local_reply_route">
 		<title><varname>local_reply_route</varname> (string)</title>
 		<para>
-		This parameter points to a reply-route, which is executed whenever TM creates
-		a reply (e.g., through the B2B modules or through MI).
+		This parameter points to a route, which is executed whenever TM is
+		about to send out a locally generated reply (e.g., through the 
+		B2B modules or through MI).
+		</para>
+		<para>
+		The purpose of this route is limited to exposing the content of the 
+		reply as SIP message 
+		</para>
+		<para>
+		IMPORTANT: this route is to be used in a read-only manner, inspection
+		only. Any changes you do here will discarded.
+		</para>
+		<para>
+		IMPORTANT: this route does not offer any message, transactional or
+		dialog context, so do not rely on any variables with scope (like AVPs).
 		</para>
-
 		<example>
 		<title>Set the <varname>local_reply_route</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 # Execute the route "tm_local_reply" upon sending a request
 modparam("tm", "local_reply_route", "tm_local_reply")
 
-onreply_route[tm_local_reply] {
+route[tm_local_reply] {
 	if (is_method("BYE")) {
 		$var(rc) = rest_get("http://localhost/qos/delete",
 					$var(recv_body), $var(recv_ct), $var(rcode));

modules/tm/t_reply.c

@@ -441,16 +441,17 @@ static int _reply_light( struct cell *trans, char* buf, unsigned int len,
 	if(trans->uas.request && trans->uas.request->flags&tcp_no_new_conn_rplflag)
 		tcp_no_new_conn = 1;
 
-	if(ref_script_route_is_valid(tm_local_reply)) {
+	if(ref_script_route_is_valid(tm_local_reply_route)) {
 		LM_DBG("Found Local-Reply Route...\n");
-		LM_DBG("Message:\n-----------------\n%.*s\n--------------------\n", len, buf);
 		memset(&dummy_msg, 0, sizeof(struct sip_msg));
 		dummy_msg.buf = buf;
 		dummy_msg.len = len;
 
 		if (parse_msg(buf, len, &dummy_msg) == 0) {
-			LM_DBG("Parsed Message, executing Local-Reply Route with Message...\n");
-			run_top_route(sroutes->onreply[tm_local_reply->idx], &dummy_msg);
+			LM_DBG("Parsed Message, executing Local-Reply Route "
+				"with Message...\n");
+			run_top_route(sroutes->request[tm_local_reply_route->idx],
+				&dummy_msg);
 		}
 		free_sip_msg(&dummy_msg);
 	}

modules/tm/t_reply.h

@@ -30,7 +30,7 @@
 
 extern int restart_fr_on_each_reply;
 extern int onreply_avp_mode;
-extern struct script_route_ref *tm_local_reply;
+extern struct script_route_ref *tm_local_reply_route;
 
 /* reply processing status */
 enum rps {

modules/tm/tm.c

@@ -141,11 +141,11 @@ struct sip_msg* tm_pv_context_reply(struct sip_msg* msg);
 int fr_timeout;
 int fr_inv_timeout;
 
-static char* tm_local_reply_route;
-struct script_route_ref *tm_local_reply = NULL;
+static char* tm_local_reply_route_s;
+struct script_route_ref *tm_local_reply_route = NULL;
 
-static char* tm_local_request_route;
-struct script_route_ref *tm_local_request = NULL;
+static char* tm_local_request_route_s;
+struct script_route_ref *tm_local_request_route = NULL;
 
 #define TM_CANCEL_BRANCH_ALL    (1<<0)
 #define TM_CANCEL_BRANCH_OTHERS (1<<1)
@@ -346,10 +346,10 @@ static const param_export_t params[]={
 		&tm_cluster_param.s },
 	{ "cluster_auto_cancel",      INT_PARAM,
 		&tm_repl_auto_cancel },
-	{ "local_reply_route",		  STR_PARAM,
-        &tm_local_reply_route },
+	{ "local_reply_route",        STR_PARAM,
+		&tm_local_reply_route_s },
 	{ "local_request_route",      STR_PARAM,
-        &tm_local_request_route },
+		&tm_local_request_route_s },
 	{0,0,0}
 };
 
@@ -957,27 +957,29 @@ static int mod_init(void)
 		LM_WARN("running without cluster support for transactions!\n");
 	}
 
-	if (tm_local_reply_route)
+	if (tm_local_reply_route_s)
 	{
-		tm_local_reply = ref_script_route_by_name( tm_local_reply_route,
-			sroutes->onreply, ONREPLY_RT_NO, ONREPLY_ROUTE, 0);
-		if (!ref_script_route_is_valid(tm_local_reply))
+		tm_local_reply_route = ref_script_route_by_name(
+			tm_local_reply_route_s,
+			sroutes->onreply, RT_NO, REQUEST_ROUTE, 0);
+		if (!ref_script_route_is_valid(tm_local_reply_route))
 		{
-			LM_ERR("route <%s> does not exist\n",tm_local_reply_route);
+			LM_ERR("route <%s> does not exist\n",tm_local_reply_route_s);
 			return -1;
 		}
-	}       
+	}
 
-	if (tm_local_request_route)
+	if (tm_local_request_route_s)
 	{
-		tm_local_request = ref_script_route_by_name( tm_local_request_route,
+		tm_local_request_route = ref_script_route_by_name(
+			tm_local_request_route_s,
 			sroutes->request, RT_NO, REQUEST_ROUTE, 0);
-		if (!ref_script_route_is_valid(tm_local_request))
+		if (!ref_script_route_is_valid(tm_local_request_route))
 		{
-			LM_ERR("route <%s> does not exist\n",tm_local_request_route);
+			LM_ERR("route <%s> does not exist\n",tm_local_request_route_s);
 			return -1;
 		}
-	}   
+	}
 
 	return 0;
 }

modules/tm/uac.c

@@ -553,15 +553,17 @@ int t_uac(str* method, str* headers, str* body, dlg_t* dialog,
 		request->buffer.len = buf_len;
 	}
 
-	if (ref_script_route_is_valid(tm_local_request)) {
+	if (ref_script_route_is_valid(tm_local_request_route)) {
 		LM_DBG("Found Local-Request Route...\n");
 		memset(&dummy_msg, 0, sizeof(struct sip_msg));
 		dummy_msg.buf = request->buffer.s;
 		dummy_msg.len = request->buffer.len;
 
-		if (parse_msg(request->buffer.s, request->buffer.len, &dummy_msg) == 0) {
-			LM_DBG("Parsed Message, executing Local-Reply Route with Message...\n");
-			run_top_route(sroutes->request[tm_local_request->idx], &dummy_msg);
+		if (parse_msg(request->buffer.s, request->buffer.len, &dummy_msg)==0){
+			LM_DBG("Parsed Message, executing Local-Request Route "
+				"with Message...\n");
+			run_top_route(sroutes->request[tm_local_request_route->idx],
+				&dummy_msg);
 		}
 		free_sip_msg(&dummy_msg);
 	}

modules/tm/uac.h

@@ -34,7 +34,7 @@
 
 /* Pass provisional replies to fifo applications */
 extern int pass_provisional_replies;
-extern struct script_route_ref *tm_local_request;
+extern struct script_route_ref *tm_local_request_route;
 
 /*
  * Function prototypes