tcpops: update README

modules/tcpops/README

@@ -8,9 +8,9 @@ Olle E. Johansson
 
    Edvina AB
 
-   Copyright © 2015 Orange
+   Copyright © 2015 Orange
 
-   Copyright © 2015 Edvina AB, Sollentuna, Sweden
+   Copyright © 2015 Edvina AB, Sollentuna, Sweden
      __________________________________________________________________
 
    Table of Contents
@@ -19,6 +19,9 @@ Olle E. Johansson
 
         1. Overview
         2. Parameters
+
+              2.1. closed_event (int)
+
         3. Functions
 
               3.1. tcp_conid_alive(conid)
@@ -26,14 +29,17 @@ Olle E. Johansson
               3.3. tcp_keepalive_enable([conid], idle, count, interval)
               3.4. tcp_keepalive_disable([conid])
               3.5. tcp_set_connection_lifetime([conid], lifetime)
+              3.6. tcp_enable_closed_event([conid])
 
    List of Examples
 
-   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
+   1.1. Set closed_event parameter
+   1.2. tcp_conid_alive usage
+   1.3. tcp_conid_state usage
+   1.4. tcp_keepalive_enable usage
+   1.5. tcp_keepalive_disable usage
+   1.6. tcp_set_connection_lifetime usage
+   1.7. tcp_set_closed_event usage
 
 Chapter 1. Admin Guide
 
@@ -41,6 +47,9 @@ Chapter 1. Admin Guide
 
    1. Overview
    2. Parameters
+
+        2.1. closed_event (int)
+
    3. Functions
 
         3.1. tcp_conid_alive(conid)
@@ -48,6 +57,7 @@ Chapter 1. Admin Guide
         3.3. tcp_keepalive_enable([conid], idle, count, interval)
         3.4. tcp_keepalive_disable([conid])
         3.5. tcp_set_connection_lifetime([conid], lifetime)
+        3.6. tcp_enable_closed_event([conid])
 
 1. Overview
 
@@ -61,6 +71,27 @@ Chapter 1. Admin Guide
 
 2. Parameters
 
+   2.1. closed_event (int)
+
+2.1. closed_event (int)
+
+   If set to 0 (gloabbly disabled), the "tcp:closed" event route will
+   never be called on TCP disconnections.
+
+   If set to 1 (globally enabled), the "tcp:closed" event route will
+   always be called on TCP disconnections.
+
+   If set to 2 ("manual" mode), the "tcp:closed" event route will only be
+   called on TCP connections for which tcp_enable_closed_event() has been
+   applied, when a disconnection occurs.
+
+   Default value is 1 (globally enabled).
+
+   Example 1.1. Set closed_event parameter
+...
+modparam("tcpops", "closed_event", 0)
+...
+
 3. Functions
 
    3.1. tcp_conid_alive(conid)
@@ -68,8 +99,9 @@ Chapter 1. Admin Guide
    3.3. tcp_keepalive_enable([conid], idle, count, interval)
    3.4. tcp_keepalive_disable([conid])
    3.5. tcp_set_connection_lifetime([conid], lifetime)
+   3.6. tcp_enable_closed_event([conid])
 
-3.1. tcp_conid_alive(conid)
+3.1.  tcp_conid_alive(conid)
 
    Check the state of a TCP or WS connection ID
 
@@ -83,7 +115,7 @@ Chapter 1. Admin Guide
 
    -1: Connection has errors, does not exist or is about to be closed)
 
-   Example 1.1. tcp_conid_alive usage
+   Example 1.2. tcp_conid_alive usage
 ...
         $var(conid) = $conid;
         if(!tcp_conid_alive("$var(conid)")) {
@@ -91,7 +123,7 @@ Chapter 1. Admin Guide
         }
 ...
 
-3.2. tcp_conid_state(conid)
+3.2.  tcp_conid_state(conid)
 
    Check the state of a TCP or WS connection ID
 
@@ -115,14 +147,14 @@ Chapter 1. Admin Guide
 
    -4: Socket is in unknow bad state. Connection will likely close.
 
-   Example 1.2. tcp_conid_state usage
+   Example 1.3. tcp_conid_state usage
 ...
         if(!tcp_conid_state("$var(conid)")) {
                 xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
         }
 ...
 
-3.3. tcp_keepalive_enable([conid], idle, count, interval)
+3.3.  tcp_keepalive_enable([conid], idle, count, interval)
 
    Enables keepalive on a TCP connection.
 
@@ -138,7 +170,7 @@ Chapter 1. Admin Guide
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.3. tcp_keepalive_enable usage
+   Example 1.4. tcp_keepalive_enable usage
 request_route {
         if (is_method("INVITE")) {
                 $avp(caller_conid) = $conid;
@@ -157,7 +189,7 @@ onreply_route[foo] {
         ...
 }
 
-3.4. tcp_keepalive_disable([conid])
+3.4.  tcp_keepalive_disable([conid])
 
    Disables keepalive on a TCP connection.
 
@@ -169,7 +201,7 @@ onreply_route[foo] {
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.4. tcp_keepalive_disable usage
+   Example 1.5. tcp_keepalive_disable usage
 request_route {
         ...
         if (is_method("BYE")) {
@@ -188,7 +220,7 @@ onreply_route[foo] {
         ...
 }
 
-3.5. tcp_set_connection_lifetime([conid], lifetime)
+3.5.  tcp_set_connection_lifetime([conid], lifetime)
 
    Sets the connection lifetime of a connection (TCP).
 
@@ -200,7 +232,7 @@ onreply_route[foo] {
 
    Retuns 1 on success, -1 on failure.
 
-   Example 1.5. tcp_set_connection_lifetime usage
+   Example 1.6. tcp_set_connection_lifetime usage
 ...
 # use 10s as default lifetime
 tcp_connection_lifetime=10
@@ -214,3 +246,34 @@ request_route {
         }
         ...
 }
+
+3.6.  tcp_enable_closed_event([conid])
+
+   Explicitly enables the "tcp:closed" event route on a TCP connection.
+
+   Meaning of the parameters is as follows:
+     * conid (optionnal): the kamailio internal connection id. If no
+       parameter is given, it will be enabled on the current message
+       source connection.
+
+   Retuns 1 on success, -1 on failure.
+
+   Example 1.7. tcp_set_closed_event usage
+...
+# "tcp:closed" event route is "manual" mode
+modparam("tcpops", "closed_event", 2)
+...
+
+request_route {
+        ...
+        if (is_method("REGISTER") && pv_www_authenticate("$td", "xxx", "0")) {
+                # it will be called for this specific connection
+                tcp_enable_closed_event();
+        }
+        ...
+
+}
+
+event_route[tcp:closed] {
+        xlog("connection $conid was closed");
+}