tcpops Add simple function with true/false response for connection state checking - tcp_conid_alive

modules/tcpops/README

@@ -21,17 +21,19 @@ Olle E. Johansson
         2. Parameters
         3. Functions
 
-              3.1. tcp_conid_state(conid)
-              3.2. tcp_keepalive_enable([conid], idle, count, interval)
-              3.3. tcp_keepalive_disable([conid])
-              3.4. tcp_set_connection_lifetime([conid], lifetime)
+              3.1. tcp_conid_alive(conid)
+              3.2. tcp_conid_state(conid)
+              3.3. tcp_keepalive_enable([conid], idle, count, interval)
+              3.4. tcp_keepalive_disable([conid])
+              3.5. tcp_set_connection_lifetime([conid], lifetime)
 
    List of Examples
 
-   1.1. tcp_conid_state usage
-   1.2. tcp_keepalive_enable usage
-   1.3. tcp_keepalive_disable usage
-   1.4. tcp_set_connection_lifetime usage
+   1.1. tcp_conid_alive usage
+   1.2. tcp_conid_state usage
+   1.3. tcp_keepalive_enable usage
+   1.4. tcp_keepalive_disable usage
+   1.5. tcp_set_connection_lifetime usage
 
 Chapter 1. Admin Guide
 
@@ -41,10 +43,11 @@ Chapter 1. Admin Guide
    2. Parameters
    3. Functions
 
-        3.1. tcp_conid_state(conid)
-        3.2. tcp_keepalive_enable([conid], idle, count, interval)
-        3.3. tcp_keepalive_disable([conid])
-        3.4. tcp_set_connection_lifetime([conid], lifetime)
+        3.1. tcp_conid_alive(conid)
+        3.2. tcp_conid_state(conid)
+        3.3. tcp_keepalive_enable([conid], idle, count, interval)
+        3.4. tcp_keepalive_disable([conid])
+        3.5. tcp_set_connection_lifetime([conid], lifetime)
 
 1. Overview
 
@@ -60,12 +63,35 @@ Chapter 1. Admin Guide
 
 3. Functions
 
-   3.1. tcp_conid_state(conid)
-   3.2. tcp_keepalive_enable([conid], idle, count, interval)
-   3.3. tcp_keepalive_disable([conid])
-   3.4. tcp_set_connection_lifetime([conid], lifetime)
+   3.1. tcp_conid_alive(conid)
+   3.2. tcp_conid_state(conid)
+   3.3. tcp_keepalive_enable([conid], idle, count, interval)
+   3.4. tcp_keepalive_disable([conid])
+   3.5. tcp_set_connection_lifetime([conid], lifetime)
 
-3.1. tcp_conid_state(conid)
+3.1. tcp_conid_alive(conid)
+
+   Check the state of a TCP or WS connection ID
+
+   Meaning of the parameters is as follows:
+     * conid (optionnal): the Kamailio internal connection id (as in the
+       $conid pseudovariable).
+
+   Retuns values:
+
+   1: Connection is OK
+
+   -1: Connection has errors, does not exist or is about to be closed)
+
+   Example 1.1. tcp_conid_alive usage
+...
+        $var(conid) = $conid;
+        if(!tcp_conid_alive("$var(conid)")) {
+                xlog("L_ERR", "Connection $conid can no longer be used\n");
+        }
+...
+
+3.2. tcp_conid_state(conid)
 
    Check the state of a TCP or WS connection ID
 
@@ -89,14 +115,14 @@ Chapter 1. Admin Guide
 
    -4: Socket is in unknow bad state. Connection will likely close.
 
-   Example 1.1. tcp_conid_state usage
+   Example 1.2. tcp_conid_state usage
 ...
-        if(!tcp_conid_state($var(conid))) {
+        if(!tcp_conid_state("$var(conid)")) {
                 xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
         }
 ...
 
-3.2. tcp_keepalive_enable([conid], idle, count, interval)
+3.3. tcp_keepalive_enable([conid], idle, count, interval)
 
    Enables keepalive on a TCP connection.
 
@@ -112,7 +138,7 @@ Chapter 1. Admin Guide
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.2. tcp_keepalive_enable usage
+   Example 1.3. tcp_keepalive_enable usage
 request_route {
         if (is_method("INVITE")) {
                 $avp(caller_conid) = $conid;
@@ -131,7 +157,7 @@ onreply_route[foo] {
         ...
 }
 
-3.3. tcp_keepalive_disable([conid])
+3.4. tcp_keepalive_disable([conid])
 
    Disables keepalive on a TCP connection.
 
@@ -143,7 +169,7 @@ onreply_route[foo] {
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.3. tcp_keepalive_disable usage
+   Example 1.4. tcp_keepalive_disable usage
 request_route {
         ...
         if (is_method("BYE")) {
@@ -162,7 +188,7 @@ onreply_route[foo] {
         ...
 }
 
-3.4. tcp_set_connection_lifetime([conid], lifetime)
+3.5. tcp_set_connection_lifetime([conid], lifetime)
 
    Sets the connection lifetime of a connection (TCP).
 
@@ -174,7 +200,7 @@ onreply_route[foo] {
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.4. tcp_set_connection_lifetime usage
+   Example 1.5. tcp_set_connection_lifetime usage
 ...
 # use 10s as default lifetime
 tcp_connection_lifetime=10

modules/tcpops/doc/functions.xml

@@ -8,6 +8,36 @@
 
 	<title>Functions</title>
 
+	<section id="tcpops.f.tcp_conid_alive">
+		<title>
+			<function>tcp_conid_alive(conid)</function>
+		</title>
+		<para>
+				Check the state of a TCP or WS connection ID
+		</para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+			<listitem>
+				<para><emphasis>conid</emphasis> (optionnal): the Kamailio internal
+				connection id (as in the <emphasis>$conid</emphasis> pseudovariable).
+				</para>
+			</listitem>
+		</itemizedlist>
+		<para>Retuns values:</para>
+		<para>1: Connection is OK</para>
+		<para>-1: Connection has errors, does not exist or is about to be closed)</para>
+		<example>
+			<title><function>tcp_conid_alive</function> usage</title>
+			<programlisting><![CDATA[
+...
+	$var(conid) = $conid;
+	if(!tcp_conid_alive("$var(conid)")) {
+		xlog("L_ERR", "Connection $conid can no longer be used\n");
+	}
+...
+			]]></programlisting>
+		</example>
+	</section>
 	<section id="tcpops.f.tcp_conid_state">
 		<title>
 			<function>tcp_conid_state(conid)</function>
@@ -35,7 +65,7 @@
 			<title><function>tcp_conid_state</function> usage</title>
 			<programlisting><![CDATA[
 ...
-	if(!tcp_conid_state($var(conid))) {
+	if(!tcp_conid_state("$var(conid)")) {
 		xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
 	}
 ...

modules/tcpops/tcpops_mod.c

@@ -49,7 +49,8 @@ static int w_tcp_keepalive_disable1(sip_msg_t* msg, char* con);
 static int w_tcp_keepalive_disable0(sip_msg_t* msg);
 static int w_tcpops_set_connection_lifetime2(sip_msg_t* msg, char* con, char* time);
 static int w_tcpops_set_connection_lifetime1(sip_msg_t* msg, char* time);
-static int w_tcp_conid_state(sip_msg_t* msg, char* con, char* p2);
+static int w_tcp_conid_state(sip_msg_t* msg, char* con, char *p2);
+static int w_tcp_conid_alive(sip_msg_t* msg, char* con, char *p2);
 
 static int fixup_numpv(void** param, int param_no);
 
@@ -69,6 +70,8 @@ static cmd_export_t cmds[]={
 		0, REQUEST_ROUTE|ONREPLY_ROUTE},
 	{"tcp_conid_state", (cmd_function)w_tcp_conid_state, 1, fixup_numpv,
 		0, ANY_ROUTE},
+	{"tcp_conid_alive", (cmd_function)w_tcp_conid_alive, 1, fixup_numpv,
+		0, ANY_ROUTE},
 	{0, 0, 0, 0, 0, 0}
 };
 
@@ -222,6 +225,7 @@ static int w_tcp_keepalive_disable0(sip_msg_t* msg)
 	return tcpops_keepalive_disable(fd, 0);
 }
 
+/*! \brief Check the state of the TCP connection */
 static int w_tcp_conid_state(sip_msg_t* msg, char* conid, char *p2)
 {
 	struct tcp_connection *s_con;
@@ -270,6 +274,19 @@ done:
 	return ret;
 }
 
+/*! \brief A simple check to see if a connection is alive or not,
+	avoiding all the various connection states
+ */
+static int w_tcp_conid_alive(sip_msg_t* msg, char* conid, char *p2)
+{
+	int ret = w_tcp_conid_state(msg, conid, p2);
+	if (ret >= 1) {
+		return 1;	/* TRUE */
+	} 
+	/* We have some kind of problem */
+	return -1;
+}
+
 static int w_tcpops_set_connection_lifetime2(sip_msg_t* msg, char* conid, char* time)
 {
 	struct tcp_connection *s_con;