[sr-dev] git:master:d6e94d07: tcpops: docs for tcp_set_otcpid() and tcp_set_otcpid_flag() functions

[Daniel-Constantin Mierla]

Module: kamailio
Branch: master
Commit: d6e94d074a2a1f1af2964f1ed7f24602a8dd295a
URL: https://github.com/kamailio/kamailio/commit/d6e94d074a2a1f1af2964f1ed7f24602a8dd295a

Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date: 2020-03-31T11:23:20+02:00

tcpops: docs for tcp_set_otcpid() and tcp_set_otcpid_flag() functions

---

Modified: src/modules/tcpops/doc/functions.xml

---

Diff:  https://github.com/kamailio/kamailio/commit/d6e94d074a2a1f1af2964f1ed7f24602a8dd295a.diff
Patch: https://github.com/kamailio/kamailio/commit/d6e94d074a2a1f1af2964f1ed7f24602a8dd295a.patch

---

diff --git a/src/modules/tcpops/doc/functions.xml b/src/modules/tcpops/doc/functions.xml
index 9c6409c4e6..94cefaa776 100644
--- a/src/modules/tcpops/doc/functions.xml
+++ b/src/modules/tcpops/doc/functions.xml
@@ -290,6 +290,87 @@ event_route[tcp:closed] {
 	if(tcp_get_conid("127.0.0.1:5060", "$var(conid)")) {
 		xlog("connection id is: $var(conid)\n");
 	}
+...
+			]]></programlisting>
+		</example>
+	</section>
+	<section id="tcpops.f.tcp_set_otcpid">
+		<title>
+			<function>tcp_set_otcpid(conid)</function>
+		</title>
+		<para>
+			Set the value for outbound tcp connection id.
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+			<listitem>
+				<para><emphasis>conid</emphasis> - the value of tcp connection id.
+				It can be an integer number or a variable holding an interver value.
+				</para>
+			</listitem>
+		</itemizedlist>
+		<para>Return values:</para>
+		<itemizedlist>
+			<listitem>
+			<para>1: success</para>
+			</listitem>
+			<listitem>
+			<para>-1: failure</para>
+			</listitem>
+		</itemizedlist>
+		<example>
+			<title><function>tcp_set_otcpid</function> usage</title>
+			<programlisting><![CDATA[
+...
+	$var(conid) = 10;
+	tcp_set_otcpid("$var(conid)");
+...
+			]]></programlisting>
+		</example>
+	</section>
+	<section id="tcpops.f.tcp_set_otcpid_flag">
+		<title>
+			<function>tcp_set_otcpid_flag(mode)</function>
+		</title>
+		<para>
+			Set or reset the internal flag for using or not the outbound tcp
+			connection id for sending out. The outbound connection id can be
+			set by module or by config using tcp_set_otcpid(...) function. An
+			example of a module setting the otcpid is register via lookup location
+			function, which sets the filed to the connection id used to receive
+			the registration request.
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+			<listitem>
+				<para><emphasis>mode</emphasis> - if 0, then the flag is reset,
+				otherwise it is set.
+				</para>
+			</listitem>
+		</itemizedlist>
+		<para>Return values:</para>
+		<itemizedlist>
+			<listitem>
+			<para>1: success</para>
+			</listitem>
+			<listitem>
+			<para>-1: failure</para>
+			</listitem>
+		</itemizedlist>
+		<para>
+			Note: if you set the flag to use the outbound tcp connection id,
+			then custom config changes to the destination address, like
+			updating the r-uri ($ru) or dst uri ($du) are not resetting it, so
+			the same already set connection id is used and the SIP request
+			might be sent to the unexpected destination. Reset the flag in such
+			case, if you set it previously.
+		</para>
+		<example>
+			<title><function>tcp_set_otcpid_flag</function> usage</title>
+			<programlisting><![CDATA[
+...
+	$var(cmode) = 1;
+	tcp_set_otcpid_flag("$var(cmode)");
 ...
 			]]></programlisting>
 		</example>