iptrtpproxy doc: regenerated README

modules_s/iptrtpproxy/README

@@ -1,32 +1,51 @@
-
-Iptrtpproxy module
+1. Iptrtpproxy module
 
 Tomas Mandys
 
    Iptel.org
 
-   Copyright © 2007 Tomas Mandys
+   Copyright © 2007 Tomas Mandys
    Revision History
    Revision $Revision$ $Date$
-     _________________________________________________________________
-
-Overview
-
-   It  provides  similar functionality as nathelper but communicates with
-   netfilter kernel xt_RTPPROXY module using libipt_RTPPROXY userspace library.
-   See http://www.2p.cz/en/netfilter_rtp_proxy All RTP streams are manipulated
-   directly in kernel space, no data are copied from kernel to userspace and
-   back, it reduces load and delay.
-
-   The ser module is written as light-weighted, there is not implemented any
-   dialog managment as in nathelper, the reason is that such API should be
-   provided by core or specialized dialog manager module. Because such module
-   is not in CVS, session information may be stored in extra attributes of
-   avp_db  module and session id itself in record route as cookie, see rr
-   module.
-
-   It should be able to support all cases as re-invites when SIP client offers
-   media change in SDP and when number of medias in offer/answer are different.
+     __________________________________________________________________
+
+   1.1. Overview
+   1.2. Dependencies
+   1.3. Parameters
+
+        1.3.1. config (string)
+        1.3.2. switchboard (string)
+
+   1.4. Functions
+
+        1.4.1. iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
+        1.4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
+        1.4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
+        1.4.4. iptrtpproxy_delete(session_ids)
+        1.4.5. iptrtpproxy_find(gate_a, gate_b)
+        1.4.6. @iptrtpproxy.session_ids
+        1.4.7. @iptrtpproxy.sdp_ip
+        1.4.8. @iptrtpproxy.switchboard
+        1.4.9. @iptrtpproxy.direction
+
+1.1. Overview
+
+   It provides similar functionality as nathelper but communicates with
+   netfilter kernel xt_RTPPROXY module using libipt_RTPPROXY userspace
+   library. See http://www.2p.cz/en/netfilter_rtp_proxy All RTP streams
+   are manipulated directly in kernel space, no data are copied from
+   kernel to userspace and back, it reduces load and delay.
+
+   The ser module is written as light-weighted, there is not implemented
+   any dialog managment as in nathelper, the reason is that such API
+   should be provided by core or specialized dialog manager module.
+   Because such module is not in CVS, session information may be stored in
+   extra attributes of avp_db module and session id itself in record route
+   as cookie, see rr module.
+
+   It should be able to support all cases as re-invites when SIP client
+   offers media change in SDP and when number of medias in offer/answer
+   are different.
 
    Nathelper may be still used for testing if client is behind the NAT.
 
@@ -34,49 +53,61 @@ Overview
      * only IPv4 addresses are supported.
      * more media streams per session supported
 
-Dependencies
+1.2. Dependencies
 
-   The following libraries or applications must be installed before running SER
-   with this module loaded:
-     * netfilter       xt_RTPROXY       &       libipt_RTPPROXY,      see
+   The following libraries or applications must be installed before
+   running SER with this module loaded:
+     * netfilter xt_RTPROXY & libipt_RTPPROXY, see
        http://www.2p.cz/en/netfilter_rtp_proxy
 
-Parameters
+1.3. Parameters
+
+1.3.1. config (string)
+
+   References iptrtpproxy.cfg, see iptrtpproxy_helper. Default value is
+   /etc/iptrtpproxy.cfg.
 
-switchboard (string)
+1.3.2. switchboard (string)
 
    References xt_RTPPROXY switchboard for usage by ser module.
 
    The format is:
   name "=" value * ( ";" name "=" value )
 
-  name =  "name" | ( ( "addr-" | "port-" | "learning-timeout-" | "always-learn-
-") ("a" | "b") )
+  name =  "name" | "*" | ( "ringing-timeout " ) | ( ( "learning-timeout-" | "alw
+ays-learn-") ("a" | "b") )
 
-   The meaning of parameters is described in libipt_RTPROXY and iptrtpproxy
-   documentation.
+   The meaning of parameters is described in libipt_RTPROXY and
+   iptrtpproxy documentation. ringing timeout is explicit timeout in sec
+   regarding ringing. Ringing requires manual callee action, i.e. it may
+   takes long time. Default value is 60 sec.
 
-   The name" is identifier that will be used by script functions and references
-   switchboard. It's mandatory parameter. More switchboards may be declared.
+   The name" is identifier that will be used by script functions and
+   references switchboard. It's mandatory parameter. More switchboards may
+   be declared. The special name * set values for all switchboards.
 
    Example 1. Declare switchboard
         ...
-        modparam("iptrtpproxy", "switchboard", "name=my;addr-a=1.2.3.4;port-a=5
-0000");
+        modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
+        modparam("iptrtpproxy", "switchboard", "name=*;learning-timeout-a=10;lea
+rning-timeout-b=10;ringing-timeout=90");
+        modparam("iptrtpproxy", "switchboard", "name=my;ringing-timeout=60");
         ...
 
-Functions
+1.4. Functions
 
-iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
+1.4.1.  iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
 
-   Parses SDP content and allocates for each RTP media stream one RTP proxy
-   session. SDP is updates to reflect allocated sessions.
-     * if gate_a_to_b non equal to zero then SDP regards to gate-a to gate-b
-       direction.
+   Parses SDP content and allocates for each RTP media stream one RTP
+   proxy session. SDP is updates to reflect allocated sessions.
+     * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
+       direction. If bit 1 is set then ringing timeout is used instead of
+       learning timeout for particular gate timeout.
      * switchboard_id is reference to a switchboard with name declared as
-       switchboard modparam.
-     * function returns true is a session was created, identifier is available
-       via select @iptrtpproxy.session_ids.
+       switchboard modparam. If empty then use switchboard found by
+       iptrtpproxy_find (equal using @iptrtpproxy.switchboard).
+     * function returns true is a session was created, identifier is
+       available via select @iptrtpproxy.session_ids.
 
    Example 2. iptrtpproxy_alloc usage
         ...
@@ -86,14 +117,16 @@ iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
         }
         ...
 
-iptrtpproxy_update(gate_a_to_b, session_ids)
+1.4.2.  iptrtpproxy_update(gate_a_to_b, session_ids)
 
-   Parses SDP content and updates sessions provided by session_ids and updates
-   SDP. If succesfull then session_ids may be changed (in case e.g. media
-   stream  has  port  zero particular session is released), the result of
-   @iptrtpproxy.session_ids should be stored for future in-dialog usage.
-     * if gate_a_to_b non equal to zero then SDP regards to gate-a to gate-b
-       direction.
+   Parses SDP content and updates sessions provided by session_ids and
+   updates SDP. If succesfull then session_ids may be changed (in case
+   e.g. media stream has port zero particular session is released), the
+   result of @iptrtpproxy.session_ids should be stored for future
+   in-dialog usage.
+     * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
+       direction. If bit 1 is set then ringing timeout is used instead of
+       learning timeout for particular gate timeout.
 
    Example 3. iptrtpproxy_update usage
         ...
@@ -104,18 +137,50 @@ iptrtpproxy_update(gate_a_to_b, session_ids)
         }
         ...
 
-iptrtpproxy_delete(session_ids)
+1.4.3.  iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
 
-   Delete sessions identified by session_ids. May be used when dialog is being
-   destroyed (BYE) or when INVITE failed in failure route.
+   Adjust timeout for particular gate. It's useful in "200 OK" decrease
+   timeout to learning timeout if INVITE has set (long) ringing timeout.
+     * if gate_a_to_b bit 0 is set then it regards to gate-a to gate-b
+       direction. If bit 1 is set then ringing timeout is used instead of
+       learning timeout for particular gate timeout.
 
-   Example 4. iptrtpproxy_delete usage
+   Example 4. iptrtpproxy_adjust_timeout usage
+        ...
+        # load $sess_ids from dialog
+        if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
+        }
+        ...
+
+1.4.4.  iptrtpproxy_delete(session_ids)
+
+   Delete sessions identified by session_ids. May be used when dialog is
+   being destroyed (BYE) or when INVITE failed in failure route.
+
+   Example 5. iptrtpproxy_delete usage
         ...
         # load $sess_ids from dialog
         iptrtpproxy_delete($sess_ids);
         ...
 
[email protected]_ids
+1.4.5.  iptrtpproxy_find(gate_a, gate_b)
+
+   Find corresponding switchboard and set @iptrtpproxy.switchboard and
+   @iptrtpproxy.direction.
+     * if gate_a/b switchboard identification
+     * function returns true if switch was found
+
+   Example 6. iptrtpproxy_find usage
+        ...
+        if (iptrtpproxy_find("@received.ip", "@next_hop.src_ip")) {
+                if (iptrtpproxy_alloc("1", "")) {
+                          $sess_ids = @iptrtpproxy.session_ids;
+
+                }
+        }
+        ...
+
+1.4.6.  @iptrtpproxy.session_ids
 
    Returns sessions allocated/updated in iptrtpproxy_alloc/update.
 
@@ -123,6 +188,14 @@ iptrtpproxy_delete(session_ids)
         switchboard_name [ ":" [ session_id *( "," session_id) ] ]
         session_id = *( [0-9] )   ; empty when no session allocated
 
[email protected]_ip
+1.4.7.  @iptrtpproxy.sdp_ip
 
    Return first rewritten IP provided in SDP c= line.
+
+1.4.8.  @iptrtpproxy.switchboard
+
+   Switchboard found by iptrtpproxy_find.
+
+1.4.9.  @iptrtpproxy.direction
+
+   Direction determined by iptrtpproxy_find. 1..gate A->B, 0..gate B->A