Merge branch 'rfuchs/rtpengine'

Makefile.groups

@@ -13,7 +13,7 @@ mod_list_basic=async auth benchmark blst cfg_rpc cfgutils corex counters \
 				   mediaproxy mi_datagram mi_fifo mi_rpc mqueue \
 				   nat_traversal nathelper path pike pv ratelimit rr rtimer \
 				   rtpproxy sanity sdpops siputils sl statistics textops \
-				   textopsx tm tmx topoh xlog rtpproxy-ng stun sipt
+				   textopsx tm tmx topoh xlog rtpengine stun sipt
 
 # - extra used modules, with no extra dependency
 mod_list_extra=avp auth_diameter call_control cnxcc dmq domainpolicy msrp pdb \

modules/rtpproxy-ng/Makefile → modules/rtpengine/Makefile

@@ -7,7 +7,7 @@
 
 include ../../Makefile.defs
 auto_gen=
-NAME=rtpproxy-ng.so
+NAME=rtpengine.so
 LIBS=
 
 DEFS+=-DKAMAILIO_MOD_INTERFACE

modules/rtpengine/README

@@ -0,0 +1,690 @@
+rtpengine Module
+
+Maxim Sobolev
+
+   Sippy Software, Inc.
+
+Juha Heinanen
+
+   TuTPro, Inc.
+
+Edited by
+
+Maxim Sobolev
+
+Edited by
+
+Bogdan-Andrei Iancu
+
+Edited by
+
+Juha Heinanen
+
+Edited by
+
+Sas Ovidiu
+
+Edited by
+
+Carsten Bock
+
+   ng-voice GmbH
+
+Edited by
+
+Richard Fuchs
+
+   Sipwise GmbH
+
+   Copyright © 2003-2008 Sippy Software, Inc.
+
+   Copyright © 2005 Voice Sistem SRL
+
+   Copyright © 2009-2014 TuTPro Inc.
+
+   Copyright © 2010 VoIPEmbedded Inc.
+
+   Copyright © 2013-2014 Sipwise GmbH
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Multiple RTP proxy usage
+        3. Dependencies
+
+              3.1. Kamailio Modules
+              3.2. External Libraries or Applications
+
+        4. Parameters
+
+              4.1. rtpengine_sock (string)
+              4.2. rtpengine_disable_tout (integer)
+              4.3. rtpengine_tout (integer)
+              4.4. rtpengine_retr (integer)
+              4.5. extra_id_pv (string)
+              4.6. setid_avp (string)
+
+        5. Functions
+
+              5.1. set_rtpengine_set(setid)
+              5.2. rtpengine_offer([flags])
+              5.3. rtpengine_answer([flags])
+              5.4. rtpengine_delete([flags])
+              5.5. rtpengine_manage([flags])
+              5.6. start_recording()
+
+        6. Exported Pseudo Variables
+
+              6.1. $rtpstat
+
+        7. MI Commands
+
+              7.1. nh_enable_rtpp
+              7.2. nh_show_rtpp
+
+   2. Frequently Asked Questions
+
+   List of Examples
+
+   1.1. Set rtpengine_sock parameter
+   1.2. Set rtpengine_disable_tout parameter
+   1.3. Set rtpengine_tout parameter
+   1.4. Set rtpengine_retr parameter
+   1.5. Set extra_id_pv parameter
+   1.6. Set setid_avp parameter
+   1.7. set_rtpengine_set usage
+   1.8. rtpengine_offer usage
+   1.9. rtpengine_answer usage
+   1.10. rtpengine_delete usage
+   1.11. rtpengine_manage usage
+   1.12. start_recording usage
+   1.13. $rtpstat Usage
+   1.14. nh_enable_rtpp usage
+   1.15. nh_show_rtpp usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Multiple RTP proxy usage
+   3. Dependencies
+
+        3.1. Kamailio Modules
+        3.2. External Libraries or Applications
+
+   4. Parameters
+
+        4.1. rtpengine_sock (string)
+        4.2. rtpengine_disable_tout (integer)
+        4.3. rtpengine_tout (integer)
+        4.4. rtpengine_retr (integer)
+        4.5. extra_id_pv (string)
+        4.6. setid_avp (string)
+
+   5. Functions
+
+        5.1. set_rtpengine_set(setid)
+        5.2. rtpengine_offer([flags])
+        5.3. rtpengine_answer([flags])
+        5.4. rtpengine_delete([flags])
+        5.5. rtpengine_manage([flags])
+        5.6. start_recording()
+
+   6. Exported Pseudo Variables
+
+        6.1. $rtpstat
+
+   7. MI Commands
+
+        7.1. nh_enable_rtpp
+        7.2. nh_show_rtpp
+
+1. Overview
+
+   This is a module that enables media streams to be proxied via an RTP
+   proxy. The only RTP proxy currently known to work with this module is
+   the Sipwise rtpengine https://github.com/sipwise/rtpengine. The
+   rtpengine module is a modified version of the original rtpproxy module
+   using a new control protocol. The module is designed to be a drop-in
+   replacement for the old module from a configuration file point of view,
+   however due to the incompatible control protocol, it only works with
+   RTP proxies which specifically support it.
+
+2. Multiple RTP proxy usage
+
+   The rtpengine module can support multiple RTP proxies for
+   balancing/distribution and control/selection purposes.
+
+   The module allows definition of several sets of rtpproxies.
+   Load-balancing will be performed over a set and the admin has the
+   ability to choose what set should be used. The set is selected via its
+   id - the id being defined with the set. Refer to the “rtpengine_sock”
+   module parameter definition for syntax description.
+
+   The balancing inside a set is done automatically by the module based on
+   the weight of each RTP proxy from the set.
+
+   The selection of the set is done from script prior using
+   rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions -
+   see the set_rtpengine_set() function.
+
+   Another way to select the set is to define setid_avp module parameter
+   and assign setid to the defined avp before calling rtpengine_offer() or
+   rtpengine_manage() function. If forwarding of the requests fails and
+   there is another branch to try, remember to unset the avp after calling
+   rtpengine_delete() function.
+
+   For backward compatibility reasons, a set with no id take by default
+   the id 0. Also if no set is explicitly set before rtpengine_delete(),
+   rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
+
+   IMPORTANT: if you use multiple sets, take care and use the same set for
+   both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
+   the set was selected using setid_avp, the avp needs to be set only once
+   before rtpengine_offer() or rtpengine_manage() call.
+
+3. Dependencies
+
+   3.1. Kamailio Modules
+   3.2. External Libraries or Applications
+
+3.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * tm module - (optional) if you want to have rtpengine_manage() fully
+       functional
+
+3.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * None.
+
+4. Parameters
+
+   4.1. rtpengine_sock (string)
+   4.2. rtpengine_disable_tout (integer)
+   4.3. rtpengine_tout (integer)
+   4.4. rtpengine_retr (integer)
+   4.5. extra_id_pv (string)
+   4.6. setid_avp (string)
+
+4.1. rtpengine_sock (string)
+
+   Definition of socket(s) used to connect to (a set) RTP proxy. It may
+   specify a UNIX socket or an IPv4/IPv6 UDP socket.
+
+   Default value is “NONE” (disabled).
+
+   Example 1.1. Set rtpengine_sock parameter
+...
+# single rtproxy
+modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
+# multiple rtproxies for LB
+modparam("rtpengine", "rtpengine_sock",
+        "udp:localhost:12221 udp:localhost:12222")
+# multiple sets of multiple rtproxies
+modparam("rtpengine", "rtpengine_sock",
+        "1 == udp:localhost:12221 udp:localhost:12222")
+modparam("rtpengine", "rtpengine_sock",
+        "2 == udp:localhost:12225")
+...
+
+4.2. rtpengine_disable_tout (integer)
+
+   Once an RTP proxy was found unreachable and marked as disabled, the
+   rtpengine module will not attempt to establish communication to that
+   RTP proxy for rtpengine_disable_tout seconds.
+
+   Default value is “60”.
+
+   Example 1.2. Set rtpengine_disable_tout parameter
+...
+modparam("rtpengine", "rtpengine_disable_tout", 20)
+...
+
+4.3. rtpengine_tout (integer)
+
+   Timeout value in waiting for reply from RTP proxy.
+
+   Default value is “1”.
+
+   Example 1.3. Set rtpengine_tout parameter
+...
+modparam("rtpengine", "rtpengine_tout", 2)
+...
+
+4.4. rtpengine_retr (integer)
+
+   How many times the module should retry to send and receive after
+   timeout was generated.
+
+   Default value is “5”.
+
+   Example 1.4. Set rtpengine_retr parameter
+...
+modparam("rtpengine", "rtpengine_retr", 2)
+...
+
+4.5. extra_id_pv (string)
+
+   The parameter sets the PV defination to use when the “b” parameter is
+   used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
+   rtpengine_manage() command.
+
+   Default is empty, the “b” parameter may not be used then.
+
+   Example 1.5. Set extra_id_pv parameter
+...
+modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
+...
+
+4.6. setid_avp (string)
+
+   The parameter defines an AVP that, if set, determines which RTP proxy
+   set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
+   rtpengine_manage() functions use.
+
+   There is no default value.
+
+   Example 1.6. Set setid_avp parameter
+...
+modparam("rtpengine", "setid_avp", "$avp(setid)")
+...
+
+5. Functions
+
+   5.1. set_rtpengine_set(setid)
+   5.2. rtpengine_offer([flags])
+   5.3. rtpengine_answer([flags])
+   5.4. rtpengine_delete([flags])
+   5.5. rtpengine_manage([flags])
+   5.6. start_recording()
+
+5.1.  set_rtpengine_set(setid)
+
+   Sets the ID of the RTP proxy set to be used for the next
+   rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
+   rtpengine_manage() command. The parameter can be an integer or a config
+   variable holding an integer.
+
+   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+   BRANCH_ROUTE.
+
+   Example 1.7. set_rtpengine_set usage
+...
+set_rtpengine_set("2");
+rtpengine_offer();
+...
+
+5.2.  rtpengine_offer([flags])
+
+   Rewrites SDP body to ensure that media is passed through an RTP proxy.
+   To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK
+   and on 200 OK when SDPs are in 200 OK and ACK.
+
+   Meaning of the parameters is as follows:
+     * flags - flags to turn on some features.
+       The “flags” string is a list of space-separated items. Each item is
+       either an individual token, or a token in “key=value” format. The
+       possible tokens are described below.
+          + via-branch=... - Include the “branch” value of one of the
+            “Via” headers in the request to the RTP proxy. Possible values
+            are: “1” - use the first “Via” header; “2” - use the second
+            “Via” header; “auto” - use the first “Via” header if this is a
+            request, or the second one if this is a reply; “extra” - don't
+            take the value from a header, but instead use the value of the
+            “extra_id_pv” variable. This can be used to create one media
+            session per branch on the RTP proxy. When sending a subsequent
+            “delete” command to the RTP proxy, you can then stop just the
+            session for a specific branch when passing the flag '1' or '2'
+            in the “rtpengine_delete”, or stop all sessions for a call
+            when not passing one of those two flags there. This is
+            especially useful if you have serially forked call scenarios
+            where the RTP proxy gets an “offer” command for a new branch,
+            and then a “delete” command for the previous branch, which
+            would otherwise delete the full call, breaking the subsequent
+            “answer” for the new branch. This flag is only supported by
+            the Sipwise rtpengine RTP proxy at the moment!
+          + asymmetric - flags that UA from which message is received
+            doesn't support symmetric RTP. (automatically sets the 'r'
+            flag)
+          + force-answer - force “answer”, that is, only rewrite SDP when
+            corresponding session already exists in the RTP proxy. By
+            default is on when the session is to be completed.
+          + internal, external - these flags specify the direction of the
+            SIP message. These flags only make sense when the RTP proxy is
+            running in bridge mode. “internal” corresponds to the proxy's
+            first interface, “external” corresponds to the RTP proxy's
+            second interface. You always have to specify two flags to
+            define the incoming network and the outgoing network. For
+            example, “internal external” should be used for SIP message
+            received from the local interface and sent out on the external
+            interface, and “external internal” vice versa. Other options
+            are “internal internal” and “external external”. So, for
+            example if a SIP requests is processed with “internal
+            external” flags, the corresponding response must be processed
+            with “internal external” flags.
+          + auto-bridge - this flag an alternative to the “internal” and
+            “external” flags in order to do automatic bridging between
+            IPv4 on the "internal network" and IPv6 on the "external
+            network". Instead of explicitly instructing the RTP proxy to
+            select a particular address family, the distinction is done by
+            the given IP in the SDP body by the RTP proxy itself. Not
+            supported by Sipwise rtpengine.
+          + address-family=... - instructs the RTP proxy that the
+            recipient of this SDP body expects to see addresses of a
+            particular family. Possible values are “IP4” and “IP6”. For
+            example, if the SDP body contains IPv4 addresses but the
+            recipient only speaks IPv6, you would use “address-family=IP6”
+            to bridge between the two address families.
+            Sipwise rtpengine remembers the address family preference of
+            each party after it has seen an SDP body from them. This means
+            that normally it is only necessary to explicitly specify the
+            address family in the “offer”, but not in the “answer”.
+            Note: Please note, that this will only work properly with
+            non-dual-stack user-agents or with dual-stack clients
+            according to RFC6157 (which suggest ICE for Dual-Stack
+            implementations). This short-cut will not work properly with
+            RFC4091 (ANAT) compatible clients, which suggests having
+            different m-lines with different IP-protocols grouped
+            together.
+          + force - instructs the RTP proxy to ignore marks inserted by
+            another RTP proxy in transit to indicate that the session is
+            already goes through another proxy. Allows creating a chain of
+            proxies. Not supported and ignored by Sipwise rtpengine.
+          + trust-address - flags that IP address in SDP should be
+            trusted. Without this flag, the RTP proxy ignores address in
+            the SDP and uses source address of the SIP message as media
+            address which is passed to the RTP proxy.
+          + replace-origin - flags that IP from the origin description
+            (o=) should be also changed.
+          + replace-session-connection - flags to change the session-level
+            SDP connection (c=) IP if media description also includes
+            connection information.
+          + symmetric - flags that for the UA from which message is
+            received, support symmetric RTP must be forced.
+          + repacketize=NN - requests the RTP proxy to perform
+            re-packetization of RTP traffic coming from the UA which has
+            sent the current message to increase or decrease payload size
+            per each RTP packet forwarded if possible. The NN is the
+            target payload size in ms, for the most codecs its value
+            should be in 10ms increments, however for some codecs the
+            increment could differ (e.g. 30ms for GSM or 20ms for G.723).
+            The RTP proxy would select the closest value supported by the
+            codec. This feature could be used for significantly reducing
+            bandwith overhead for low bitrate codecs, for example with
+            G.729 going from 10ms to 100ms saves two thirds of the network
+            bandwith. Not supported by Sipwise rtpengine.
+          + ICE=... - controls the RTP proxy's behaviour regarding ICE
+            attributes within the SDP body. Possible values are: “force” -
+            discard any ICE attributes already present in the SDP body and
+            then generate and insert new ICE data, leaving itself as the
+            only ICE candidates; “remove” instructs the RTP proxy to
+            discard any ICE attributes and not insert any new ones into
+            the SDP. The default (if no “ICE=...” is given at all), new
+            ICE data will only be generated if no ICE was present in the
+            SDP originally; otherwise the RTP proxy will only insert
+            itself as an additional ICE candidate. Other SDP substitutions
+            (c=, m=, etc) are unaffected by this flag.
+          + RTP, SRTP, AVP, AVPF - These flags control the RTP transport
+            protocol that should be used towards the recipient of the SDP.
+            If none of them are specified, the protocol given in the SDP
+            is left untouched. Otherwise, the “SRTP” flag indicates that
+            SRTP should be used, while “RTP” indicates that SRTP should
+            not be used. “AVPF” indicates that the advanced RTCP profile
+            with feedback messages should be used, and “AVP” indicates
+            that the regular RTCP profile should be used. See also the
+            next set of flags below.
+          + RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve as an
+            alternative, more explicit way to select between the different
+            RTP protocols and profiles supported by the RTP proxy. For
+            example, giving the flag “RTP/SAVPF” has the same effect as
+            giving the two flags “SRTP AVPF”.
+          + to-tag - force inclusion of the “To” tag. Normally, the “To”
+            tag is always included when present, except for “delete”
+            messages. Including the “To” tag in a “delete” messages allows
+            you to be more selective about which dialogues within a call
+            are being torn down.
+          + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
+            RTP proxy accept the offer, but not offer it to the recipient
+            of this message.
+          + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
+            reject the offer, but still offer it to the recipient. Can be
+            combined with “rtcp-mux-offer” to always offer it.
+          + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
+            recipient of this message, regardless of whether it was
+            offered originally or not.
+          + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
+            accept the offer and also offer it to the recipient of this
+            message. Can be combined with “rtcp-mux-offer” to always offer
+            it.
+          + media-address=... - force a particular media address to be
+            used in the SDP body. Address family is detected
+            automatically.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.8. rtpengine_offer usage
+route {
+...
+    if (is_method("INVITE")) {
+        if (has_body("application/sdp")) {
+            if (rtpengine_offer())
+                t_on_reply("1");
+        } else {
+            t_on_reply("2");
+        }
+    }
+    if (is_method("ACK") && has_body("application/sdp"))
+        rtpengine_answer();
+...
+}
+
+onreply_route[1]
+{
+...
+    if (has_body("application/sdp"))
+        rtpengine_answer();
+...
+}
+
+onreply_route[2]
+{
+...
+    if (has_body("application/sdp"))
+        rtpengine_offer();
+...
+}
+
+5.3.  rtpengine_answer([flags])
+
+   Rewrites SDP body to ensure that media is passed through an RTP proxy.
+   To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK
+   and on ACK when SDPs are in 200 OK and ACK.
+
+   See rtpengine_offer() function description above for the meaning of the
+   parameters.
+
+   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+   FAILURE_ROUTE, BRANCH_ROUTE.
+
+   Example 1.9. rtpengine_answer usage
+
+   See rtpengine_offer() function example above for example.
+
+5.4.  rtpengine_delete([flags])
+
+   Tears down the RTPProxy session for the current call.
+
+   See rtpengine_offer() function description above for the meaning of the
+   parameters. Note that not all flags make sense for a “delete”.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.10. rtpengine_delete usage
+...
+rtpengine_delete();
+...
+
+5.5.  rtpengine_manage([flags])
+
+   Manage the RTPProxy session - it combines the functionality of
+   rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
+   internally based on message type and method which one to execute.
+
+   It can take the same parameters as rtpengine_offer(). The flags
+   parameter to rtpengine_manage() can be a configuration variable
+   containing the flags as a string.
+
+   Functionality:
+     * If INVITE with SDP, then do rtpengine_offer()
+     * If INVITE with SDP, when the tm module is loaded, mark transaction
+       with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
+       rtpengine_answer()
+     * If ACK with SDP, then do rtpengine_answer()
+     * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
+       rtpengine_delete()
+     * If reply to INVITE with code >= 300 do rtpengine_delete()
+     * If reply with SDP to INVITE having code 1xx and 2xx, then do
+       rtpengine_answer() if the request had SDP or tm is not loaded,
+       otherwise do rtpengine_offer()
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.11. rtpengine_manage usage
+...
+rtpengine_manage();
+...
+
+5.6.  start_recording()
+
+   This function will send a signal to the RTP proxy to record the RTP
+   stream on the RTP proxy. This function is not supported by Sipwise
+   rtpengine at the moment!
+
+   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
+
+   Example 1.12. start_recording usage
+...
+start_recording();
+...
+
+6. Exported Pseudo Variables
+
+   6.1. $rtpstat
+
+6.1. $rtpstat
+
+   Returns the RTP statistics from the RTP proxy. The RTP statistics from
+   the RTP proxy are provided as a string and it does contain several
+   packet counters. The statistics must be retrieved before the session is
+   deleted (before rtpengine_delete()).
+
+   Example 1.13. $rtpstat Usage
+...
+    append_hf("X-RTP-Statistics: $rtpstat\r\n");
+...
+
+7. MI Commands
+
+   7.1. nh_enable_rtpp
+   7.2. nh_show_rtpp
+
+7.1. nh_enable_rtpp
+
+   Enables a RTP proxy if parameter value is greater than 0. Disables it
+   if a zero value is given.
+
+   The first parameter is the RTP proxy url (exactly as defined in the
+   config file).
+
+   The second parameter value must be a number in decimal.
+
+   NOTE: if a RTP proxy is defined multiple times (in the same or
+   diferente sete), all of its instances will be enables/disabled.
+
+   Example 1.14.  nh_enable_rtpp usage
+...
+$ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
+...
+
+7.2. nh_show_rtpp
+
+   Displays all the RTP proxies and their information: set and status
+   (disabled or not, weight and recheck_ticks).
+
+   No parameter.
+
+   Example 1.15.  nh_show_rtpp usage
+...
+$ kamctl fifo nh_show_rtpp
+...
+
+Chapter 2. Frequently Asked Questions
+
+   2.1. How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
+   2.2. Where can I find more about Kamailio?
+   2.3. Where can I post a question about this module?
+   2.4. How can I report a bug?
+
+   2.1.
+
+   How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
+
+   For the most part, only the names of the functions have changed, with
+   “rtpproxy” in each name replaced with “rtpengine”. For example,
+   “rtpproxy_manage()” has become “rtpengine_manage()”. A few name
+   duplications have also been resolved, for example there is now a single
+   “rtpengine_delete()” instead of “unforce_rtp_proxy()” and the identical
+   “rtpproxy_destroy()”.
+
+   The largest difference to the old module is how flags are passed to
+   “rtpengine_offer()”, “rtpengine_answer()”, “rtpengine_manage()” and
+   “rtpengine_delete()”. Instead of having a string of single-letter
+   flags, they now take a string of space-separated items, with each item
+   being either a single token (word) or a “key=value” pair.
+
+   For example, if you had a call “rtpproxy_offer("FRWOC+PS");”, this
+   would then become:
+rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
+nnection ICE=force RTP/SAVPF");
+
+   Finally, if you were using the second paramater (explicit media
+   address) to any of these functions, this has been replaced by the
+   “media-address=...” option within the first string of flags.
+
+   2.2.
+
+   Where can I find more about Kamailio?
+
+   Take a look at http://www.kamailio.org/.
+
+   2.3.
+
+   Where can I post a question about this module?
+
+   First at all check if your question was already answered on one of our
+   mailing lists:
+     * User Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
+     * Developer Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
+
+   E-mails regarding any stable Kamailio release should be sent to
+   <[email protected]> and e-mails regarding development
+   versions should be sent to <[email protected]>.
+
+   If you want to keep the mail private, send it to
+   <[email protected]>.
+
+   2.4.
+
+   How can I report a bug?
+
+   Please follow the guidelines provided at:
+   http://sip-router.org/tracker.

modules/rtpproxy-ng/doc/Makefile → modules/rtpengine/doc/Makefile

@@ -1,4 +1,4 @@
-docs = rtpproxy-ng.xml
+docs = rtpengine.xml
 
 docbook_dir = ../../../docbook
 include $(docbook_dir)/Makefile.module

modules/rtpproxy-ng/doc/rtpproxy-ng.xml → modules/rtpengine/doc/rtpengine.xml

@@ -10,7 +10,7 @@
 
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
 	<bookinfo>
-	<title>rtpproxy-ng Module</title>
+	<title>rtpengine Module</title>
 	<productname class="trade">&kamailioname;</productname>
 	<authorgroup>
 		<author>
@@ -91,13 +91,13 @@
 		<holder><ulink url='http://www.voipembedded.com'>VoIPEmbedded Inc.</ulink></holder>
 	</copyright>
 	<copyright>
-		<year>2013</year>
+		<year>2013-2014</year>
 		<holder>Sipwise GmbH</holder>
 	</copyright>
 	</bookinfo>
 	<toc></toc>
 
-	<xi:include href="rtpproxy_admin.xml"/>
-	<xi:include href="rtpproxy_faq.xml"/>
+	<xi:include href="rtpengine_admin.xml"/>
+	<xi:include href="rtpengine_faq.xml"/>
 
 </book>

modules/rtpengine/doc/rtpengine_admin.xml

@@ -0,0 +1,725 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<!-- Module User's Guide -->
+
+<chapter>
+
+	<title>&adminguide;</title>
+
+	<section>
+	<title>Overview</title>
+	<para>
+		This is a module that enables media streams to be proxied
+		via an &rtp; proxy. The only &rtp; proxy currently known to work
+		with this module is the Sipwise rtpengine
+		<ulink url="https://github.com/sipwise/rtpengine"></ulink>.
+		The rtpengine module is a modified version of the original
+		rtpproxy module using a new control protocol. The module is
+		designed to be a drop-in replacement for the old module from
+		a configuration file point of view, however due to the
+		incompatible control protocol, it only works with &rtp; proxies
+		which specifically support it.
+	</para>
+	</section>
+
+	<section>
+	<title>Multiple &rtp; proxy usage</title>
+	<para>
+		The rtpengine module can support multiple &rtp; proxies for
+		balancing/distribution and control/selection purposes.
+	</para>
+	<para>
+		The module allows definition of several sets of rtpproxies.
+		Load-balancing will be performed over a set and the admin has the
+		ability to choose what set should be used. The set is selected via
+		its id - the id being defined with the set. Refer to the
+		<quote>rtpengine_sock</quote> module parameter definition for syntax
+		description.
+	</para>
+	<para>
+		The balancing inside a set is done automatically by the module based on
+		the weight of each &rtp; proxy from the set.
+	</para>
+	<para>
+		The selection of the set is done from script prior using
+		rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
+		functions - see the set_rtpengine_set() function.
+	</para>
+	<para>
+	        Another way to select the set is to define setid_avp
+	        module parameter and assign setid to the defined avp
+	        before calling rtpengine_offer() or rtpengine_manage()
+	        function.  If forwarding of the requests fails and
+	        there is another branch to try, remember to unset the
+	        avp after calling rtpengine_delete() function.
+	</para>
+	<para>
+		For backward compatibility reasons, a set with no id take by default
+		the id 0. Also if no set is explicitly set before
+		rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
+		the 0 id set will be used.
+	</para>
+	<para>
+		IMPORTANT: if you use multiple sets, take care and use the same set for
+		both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!!
+		If the set was selected using setid_avp, the avp needs to be
+		set only once before rtpengine_offer() or rtpengine_manage() call.
+	</para>
+	</section>
+
+	<section>
+	<title>Dependencies</title>
+	<section>
+		<title>&kamailio; Modules</title>
+		<para>
+		The following modules must be loaded before this module:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>tm module</emphasis> - (optional) if you want to
+				have rtpengine_manage() fully functional
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	<section>
+		<title>External Libraries or Applications</title>
+		<para>
+		The following libraries or applications must be installed before
+		running &kamailio; with this module loaded:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>None</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	</section>
+
+	<section>
+	<title>Parameters</title>
+	<section id="rtpengine.p.rtpengine_sock">
+		<title><varname>rtpengine_sock</varname> (string)</title>
+		<para>
+		Definition of socket(s) used to connect to (a set) &rtp; proxy. It may
+		specify a UNIX socket or an IPv4/IPv6 UDP socket.
+		</para>
+		<para>
+		<emphasis>
+			Default value is <quote>NONE</quote> (disabled).
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>rtpengine_sock</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+# single rtproxy
+modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
+# multiple rtproxies for LB
+modparam("rtpengine", "rtpengine_sock",
+	"udp:localhost:12221 udp:localhost:12222")
+# multiple sets of multiple rtproxies
+modparam("rtpengine", "rtpengine_sock",
+	"1 == udp:localhost:12221 udp:localhost:12222")
+modparam("rtpengine", "rtpengine_sock",
+	"2 == udp:localhost:12225")
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="rtpengine.p.rtpengine_disable_tout">
+		<title><varname>rtpengine_disable_tout</varname> (integer)</title>
+		<para>
+		Once an &rtp; proxy was found unreachable and marked as disabled, the rtpengine
+		module will not attempt to establish communication to that &rtp; proxy for
+		rtpengine_disable_tout seconds.
+		</para>
+		<para>
+		<emphasis>
+			Default value is <quote>60</quote>.
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>rtpengine_disable_tout</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("rtpengine", "rtpengine_disable_tout", 20)
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="rtpengine.p.rtpengine_tout">
+		<title><varname>rtpengine_tout</varname> (integer)</title>
+		<para>
+		Timeout value in waiting for reply from &rtp; proxy.
+		</para>
+		<para>
+		<emphasis>
+			Default value is <quote>1</quote>.
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>rtpengine_tout</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("rtpengine", "rtpengine_tout", 2)
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="rtpengine.p.rtpengine_retr">
+		<title><varname>rtpengine_retr</varname> (integer)</title>
+		<para>
+		How many times the module should retry to send and receive after
+		timeout was generated.
+		</para>
+		<para>
+		<emphasis>
+			Default value is <quote>5</quote>.
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>rtpengine_retr</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("rtpengine", "rtpengine_retr", 2)
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="rtpengine.p.extra_id_pv">
+		<title><varname>extra_id_pv</varname> (string)</title>
+		<para>
+			The parameter sets the PV defination to use when the <quote>b</quote>
+			parameter is used on rtpengine_delete(), rtpengine_offer(),
+			rtpengine_answer() or rtpengine_manage() command.
+		</para><para>
+			Default is empty, the <quote>b</quote> parameter may not be used then.
+		</para>
+		<example>
+		<title>Set <varname>extra_id_pv</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section id="rtpengine.p.setid_pv">
+		<title><varname>setid_avp</varname> (string)</title>
+		<para>
+			The parameter defines an AVP that, if set,
+			determines which &rtp; proxy set
+			rtpengine_offer(), rtpengine_answer(),
+			rtpengine_delete(), and rtpengine_manage()
+			functions use.
+		</para>
+		<para>
+			There is no default value.
+		</para>
+		<example>
+		<title>Set <varname>setid_avp</varname> parameter</title>
+<programlisting format="linespecific">
+...
+modparam("rtpengine", "setid_avp", "$avp(setid)")
+...
+</programlisting>
+		</example>
+	</section>
+
+	</section>
+
+	<section>
+	<title>Functions</title>
+	<section id="rtpengine.f.set_rtpengine_set">
+		<title>
+		<function moreinfo="none">set_rtpengine_set(setid)</function>
+		</title>
+		<para>
+		Sets the ID of the &rtp; proxy set to be used for the next
+		rtpengine_delete(), rtpengine_offer(), rtpengine_answer()
+		or rtpengine_manage() command. The parameter can be an integer or
+		a config variable holding an integer.
+		</para>
+		<para>
+		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+		BRANCH_ROUTE.
+		</para>
+		<example>
+		<title><function>set_rtpengine_set</function> usage</title>
+		<programlisting format="linespecific">
+...
+set_rtpengine_set("2");
+rtpengine_offer();
+...
+</programlisting>
+		</example>
+	</section>
+        <section id="rtpengine.f.rtpengine_offer">
+                <title>
+                <function moreinfo="none">rtpengine_offer([flags])</function>
+                </title>
+                <para>
+                Rewrites &sdp; body to ensure that media is passed through
+                an &rtp; proxy. To be invoked
+		on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK
+		when SDPs are in 200 OK and ACK.
+                </para>
+		<para>Meaning of the parameters is as follows:</para>
+		<itemizedlist>
+		<listitem>
+			<para>
+			<emphasis>flags</emphasis> - flags to turn on some features.
+			</para>
+			<para>The <quote>flags</quote> string is a list of space-separated items. Each item
+			is either an individual token, or a token in <quote>key=value</quote> format. The
+			possible tokens are described below.</para>
+			<itemizedlist>
+				<listitem><para>
+				<emphasis>via-branch=...</emphasis> - Include the <quote>branch</quote>
+				value of one of the <quote>Via</quote> headers in the request to the
+				&rtp; proxy. Possible values are:
+				<quote>1</quote> - use the first <quote>Via</quote> header;
+				<quote>2</quote> - use the second <quote>Via</quote> header;
+				<quote>auto</quote> - use the first <quote>Via</quote> header if this is
+				a request, or the second one if this is a reply;
+				<quote>extra</quote> - don't take the value from a header, but instead use
+				the value of the <quote>extra_id_pv</quote> variable.
+				This can be used to create one media session per branch
+				on the &rtp; proxy. When sending a subsequent <quote>delete</quote> command to
+				the &rtp; proxy, you can then stop just the session for a specific branch when
+				passing the flag '1' or '2' in the <quote>rtpengine_delete</quote>, or stop
+				all sessions for a call when not passing one of those two flags there. This is
+				especially useful if you have serially forked call scenarios where the &rtp; proxy
+				gets an <quote>offer</quote> command for a new branch, and then a
+				<quote>delete</quote> command for the previous branch, which would otherwise
+				delete the full call, breaking the subsequent <quote>answer</quote> for the
+				new branch. <emphasis>This flag is only supported by the Sipwise rtpengine
+				&rtp; proxy at the moment!</emphasis>
+				</para></listitem>
+				<listitem><para>
+				<emphasis>asymmetric</emphasis> - flags that UA from which message is
+				received doesn't support symmetric RTP. (automatically sets the 'r' flag)
+				</para></listitem>
+				<listitem><para>
+				<emphasis>force-answer</emphasis> - force <quote>answer</quote>, that is,
+				only rewrite &sdp; when corresponding session already exists
+				in the &rtp; proxy. By default is on when the session is to be
+				completed.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>internal, external</emphasis> - these flags specify the direction of
+				the SIP message. These flags only make sense when the &rtp; proxy is running
+				in bridge mode. <quote>internal</quote> corresponds to the proxy's first
+				interface, <quote>external</quote> corresponds to the &rtp; proxy's
+				second interface. You always have to specify two flags to define
+				the incoming network and the outgoing network. For example, <quote>internal
+				external</quote> should be
+				used for SIP message received from the local interface and sent out on the
+				external interface, and <quote>external internal</quote> vice versa. Other
+				options are <quote>internal internal</quote> and <quote>external
+				external</quote>.
+				So, for example if a SIP requests is processed with <quote>internal
+				external</quote> flags, the corresponding
+				response must be processed with <quote>internal external</quote> flags.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>auto-bridge</emphasis> - this flag an alternative to the
+				<quote>internal</quote> and <quote>external</quote> flags
+				in order to do automatic bridging between IPv4 on the
+				"internal network" and IPv6 on the "external network". Instead of
+				explicitly instructing the &rtp; proxy to select a particular address
+				family, the distinction is done by the given IP in the SDP body by
+				the RTP proxy itself. Not supported by Sipwise rtpengine.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>address-family=...</emphasis> - instructs the &rtp; proxy that the
+				recipient of this &sdp; body expects to see addresses of a particular family.
+				Possible values are <quote>IP4</quote> and <quote>IP6</quote>. For example,
+				if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6,
+				you would use <quote>address-family=IP6</quote> to bridge between the two
+				address families.
+				</para><para>
+				Sipwise rtpengine remembers the address family preference of each party after
+				it has seen an &sdp; body from them. This means that normally it is only
+				necessary to explicitly specify the address family in the <quote>offer</quote>,
+				but not in the <quote>answer</quote>.
+				</para><para>
+				Note: Please note, that this will only work properly with non-dual-stack user-agents or with
+				dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
+				This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
+				having different m-lines with different IP-protocols grouped together.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>force</emphasis> - instructs the &rtp; proxy to ignore marks
+				inserted by another &rtp; proxy in transit to indicate that the
+				session is already goes through another proxy. Allows creating
+				a chain of proxies. Not supported and ignored by Sipwise rtpengine.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>trust-address</emphasis> - flags that IP address in SDP should
+				be trusted. Without this flag, the &rtp; proxy ignores address in
+				the SDP and uses source address of the SIP message as media
+				address which is passed to the RTP proxy.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>replace-origin</emphasis> - flags that IP from the origin
+				description (o=) should be also changed.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>replace-session-connection</emphasis> - flags to change the session-level
+				SDP connection (c=) IP if media description also includes
+				connection information.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>symmetric</emphasis> - flags that for the UA from which
+				message is received, support symmetric RTP must be forced.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>repacketize=NN</emphasis> - requests the &rtp; proxy to perform
+				re-packetization of RTP traffic coming from the UA which
+				has sent the current message to increase or decrease payload
+				size per each RTP packet forwarded if possible.  The NN is the
+				target payload size in ms, for the most codecs its value should
+				be in 10ms increments, however for some codecs the increment
+				could differ (e.g. 30ms for GSM or 20ms for G.723).  The
+				&rtp; proxy would select the closest value supported by the codec.
+				This feature could be used for significantly reducing bandwith
+				overhead for low bitrate codecs, for example with G.729 going
+				from 10ms to 100ms saves two thirds of the network bandwith.
+				Not supported by Sipwise rtpengine.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>ICE=...</emphasis> - controls the &rtp; proxy's behaviour
+				regarding ICE attributes within the &sdp; body. Possible values
+				are: <quote>force</quote> - 
+				discard any ICE attributes already present in the &sdp; body
+				and then generate and insert new ICE data, leaving itself
+				as the <emphasis>only</emphasis> ICE candidates;
+				<quote>remove</quote> instructs the &rtp; proxy to discard
+				any ICE attributes and not insert any new ones into the &sdp;.
+				The default (if no <quote>ICE=...</quote> is given at all),
+				new ICE data will only be generated
+				if no ICE was present in the &sdp; originally; otherwise
+				the &rtp; proxy will only insert itself as an
+				<emphasis>additional</emphasis> ICE candidate. Other
+				&sdp; substitutions (c=, m=, etc) are unaffected by this flag.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>RTP, SRTP, AVP, AVPF</emphasis> - These flags control the &rtp;
+				transport protocol that should be used towards the recipient of
+				the &sdp;. If none of them are specified, the protocol given in
+				the &sdp; is left untouched. Otherwise, the <quote>SRTP</quote> flag indicates that
+				SRTP should be used, while <quote>RTP</quote> indicates that SRTP should not be used.
+				<quote>AVPF</quote> indicates that the advanced RTCP profile with feedback messages
+				should be used, and <quote>AVP</quote> indicates that the regular RTCP profile
+				should be used. See also the next set of flags below.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF</emphasis> - these serve as
+				an alternative, more explicit way to select between the different &rtp; protocols
+				and profiles supported by the &rtp; proxy. For example, giving the flag
+				<quote>RTP/SAVPF</quote> has the same effect as giving the two flags
+				<quote>SRTP AVPF</quote>.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>to-tag</emphasis> - force inclusion of the <quote>To</quote> tag.
+				Normally, the <quote>To</quote> tag is always included when present, except
+				for <quote>delete</quote> messages. Including the <quote>To</quote> tag in
+				a <quote>delete</quote> messages allows you to be more selective about which
+				dialogues within a call are being torn down.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>rtcp-mux-demux</emphasis> - if rtcp-mux (RFC 5761) was
+				offered, make the &rtp; proxy accept the offer, but not offer it to the
+				recipient of this message.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>rtcp-mux-reject</emphasis> - if rtcp-mux was offered, make the
+				&rtp; proxy reject the offer, but still offer it to the recipient. Can be
+				combined with <quote>rtcp-mux-offer</quote> to always offer it.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>rtcp-mux-offer</emphasis> - make the &rtp; proxy offer rtcp-mux
+				to the recipient of this message, regardless of whether it was offered
+				originally or not.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>rtcp-mux-accept</emphasis> - if rtcp-mux was offered, make the
+				&rtp; proxy accept the offer and also offer it to the recipient of this
+				message. Can be combined with <quote>rtcp-mux-offer</quote> to always offer it.
+				</para></listitem>
+				<listitem><para>
+				<emphasis>media-address=...</emphasis> - force a particular media address to
+				be used in the &sdp; body. Address family is detected automatically.
+				</para></listitem>
+			</itemizedlist>
+		</listitem>
+		</itemizedlist>
+		<para>
+		This function can be used from ANY_ROUTE.
+                </para>
+		<example>
+		<title><function>rtpengine_offer</function> usage</title>
+		<programlisting format="linespecific">
+route {
+...
+    if (is_method("INVITE")) {
+        if (has_body("application/sdp")) {
+            if (rtpengine_offer())
+                t_on_reply("1");
+        } else {
+            t_on_reply("2");
+        }
+    }
+    if (is_method("ACK") &amp;&amp; has_body("application/sdp"))
+        rtpengine_answer();
+...
+}
+
+onreply_route[1]
+{
+...
+    if (has_body("application/sdp"))
+        rtpengine_answer();
+...
+}
+
+onreply_route[2]
+{
+...
+    if (has_body("application/sdp"))
+        rtpengine_offer();
+...
+}
+</programlisting>
+                </example>
+	</section>
+        <section id="rtpengine.f.rtpengine_answer">
+                <title>
+                <function moreinfo="none">rtpengine_answer([flags])</function>
+                </title>
+		<para>
+		Rewrites &sdp; body to ensure that media is passed through
+		an &rtp; proxy. To be invoked
+		on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK
+		when SDPs are in 200 OK and ACK.
+		</para>
+		<para>
+		See rtpengine_offer() function description above for the meaning of the
+		parameters.
+		</para>
+		<para>
+		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+		FAILURE_ROUTE, BRANCH_ROUTE.
+		</para>
+		<example>
+		 <title><function>rtpengine_answer</function> usage</title>
+		<para>
+		See rtpengine_offer() function example above for example.
+		</para>
+		</example>
+        </section>
+	<section id="rtpengine.f.rtpengine_delete">
+		<title>
+		<function moreinfo="none">rtpengine_delete([flags])</function>
+		</title>
+		<para>
+		Tears down the RTPProxy session for the current call.
+		</para>
+		<para>
+		See rtpengine_offer() function description above for the meaning of the
+		parameters. Note that not all flags make sense for a <quote>delete</quote>.
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<example>
+		<title><function>rtpengine_delete</function> usage</title>
+		<programlisting format="linespecific">
+...
+rtpengine_delete();
+...
+</programlisting>
+		</example>
+	</section>
+
+    <section id="rtpengine.f.rtpengine_manage">
+        <title>
+        <function moreinfo="none">rtpengine_manage([flags])</function>
+        </title>
+		<para>
+		Manage the RTPProxy session - it combines the functionality of
+		rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
+		internally based on message type and method which one to execute.
+		</para>
+		<para>
+		It can take the same parameters as <function>rtpengine_offer().</function>
+		The flags parameter to rtpengine_manage() can be a configuration variable
+		containing the flags as a string.
+		</para>
+		<para>
+		Functionality:
+		</para>
+		<itemizedlist>
+		<listitem>
+			<para>
+			If INVITE with SDP, then do <function>rtpengine_offer()</function>
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			If INVITE with SDP, when the tm module is loaded, mark transaction with
+			internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
+			<function>rtpengine_answer()</function>
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			If ACK with SDP, then do <function>rtpengine_answer()</function>
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do <function>rtpengine_delete()</function>
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			If reply to INVITE with code >= 300 do <function>rtpengine_delete()</function>
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			If reply with SDP to INVITE having code 1xx and 2xx, then
+			do <function>rtpengine_answer()</function> if the request had SDP or tm is not loaded,
+			otherwise do <function>rtpengine_offer()</function>
+			</para>
+		</listitem>
+	</itemizedlist>
+
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<example>
+		 <title><function>rtpengine_manage</function> usage</title>
+		<programlisting format="linespecific">
+...
+rtpengine_manage();
+...
+</programlisting>
+		</example>
+        </section>
+
+	<section id="rtpengine.f.start_recording">
+		<title>
+		<function moreinfo="none">start_recording()</function>
+		</title>
+		<para>
+		This function will send a signal to the &rtp; proxy to record
+		the RTP stream on the &rtp; proxy.
+		<emphasis>This function is not supported by Sipwise rtpengine at the moment!</emphasis>
+		</para>
+		<para>
+		This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
+		</para>
+		<example>
+		<title><function>start_recording</function> usage</title>
+		<programlisting format="linespecific">
+...
+start_recording();
+...
+		</programlisting>
+		</example>
+	</section>
+
+
+	</section>
+
+	<section>
+		<title>Exported Pseudo Variables</title>
+		<section>
+			<title><function moreinfo="none">$rtpstat</function></title>
+			<para>
+			Returns the &rtp; statistics from the &rtp; proxy. The &rtp; statistics from the &rtp; proxy
+			are provided as a string and it does contain several packet counters. The statistics
+			must be retrieved before the session is deleted	(before <function>rtpengine_delete()</function>).
+			</para>
+
+		<example>
+		<title>$rtpstat Usage</title>
+		<programlisting format="linespecific">
+...
+    append_hf("X-RTP-Statistics: $rtpstat\r\n");
+...
+		</programlisting>
+		</example>
+	        </section>
+
+	</section>
+
+	<section>
+		<title><acronym>MI</acronym> Commands</title>
+		<section id="rtpengine.m.nh_enable_rtpp">
+			<title><function moreinfo="none">nh_enable_rtpp</function></title>
+			<para>
+			Enables a &rtp; proxy if parameter value is greater than 0.
+			Disables it if a zero value is given.
+			</para>
+			<para>
+			The first parameter is the &rtp; proxy url (exactly as defined in
+			the config file).
+			</para>
+			<para>
+			The second parameter value must be a number in decimal.
+			</para>
+			<para>
+			NOTE: if a &rtp; proxy is defined multiple times (in the same or
+			diferente sete), all of its instances will be enables/disabled.
+			</para>
+			<example>
+			<title>
+			<function moreinfo="none">nh_enable_rtpp</function> usage</title>
+			<programlisting format="linespecific">
+...
+$ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
+...
+			</programlisting>
+			</example>
+		</section>
+
+			<section id="rtpengine.m.nh_show_rtpp">
+			<title><function moreinfo="none">nh_show_rtpp</function></title>
+			<para>
+			Displays all the &rtp; proxies and their information: set and
+			status (disabled or not, weight and recheck_ticks).
+			</para>
+			<para>
+			No parameter.
+			</para>
+			<example>
+			<title>
+				<function moreinfo="none">nh_show_rtpp</function> usage</title>
+			<programlisting format="linespecific">
+...
+$ &ctltool; fifo nh_show_rtpp
+...
+			</programlisting>
+			</example>
+		</section>
+	</section>
+
+</chapter>
+

modules/rtpproxy-ng/doc/rtpproxy_faq.xml → modules/rtpengine/doc/rtpengine_faq.xml

@@ -15,13 +15,37 @@
     <qandaset defaultlabel="number">
 	<qandaentry>
 	    <question>
-		<para>What happend with <quote>rtpproxy_disable</quote> parameter?</para>
+		    <para>How do I migrate from <quote>rtpproxy</quote> or <quote>rtpproxy-ng</quote> to
+		    <quote>rtpengine</quote>?</para>
 	    </question>
 	    <answer>
 		<para>
-			It was removed as it became obsolete - now
-			<quote>rtpproxy_sock</quote> can take empty value to disable the
-			rtpproxy functionality.
+			For the most part, only the names of the functions have changed, with
+			<quote>rtpproxy</quote> in each name replaced with <quote>rtpengine</quote>.
+			For example, <quote>rtpproxy_manage()</quote> has become
+			<quote>rtpengine_manage()</quote>. A few name duplications have also been resolved,
+			for example there is now a single <quote>rtpengine_delete()</quote> instead of
+			<quote>unforce_rtp_proxy()</quote> and the identical <quote>rtpproxy_destroy()</quote>.
+		</para>
+		<para>
+			The largest difference to the old module is how flags are passed to
+			<quote>rtpengine_offer()</quote>, <quote>rtpengine_answer()</quote>,
+			<quote>rtpengine_manage()</quote> and <quote>rtpengine_delete()</quote>. Instead of
+			having a string of single-letter flags, they now take a string of space-separated
+			items, with each item being either a single token (word) or a <quote>key=value</quote>
+			pair.
+		</para>
+		<para>
+			For example, if you had a call <quote>rtpproxy_offer("FRWOC+PS");</quote>, this would
+			then become:
+		</para>
+		<programlisting>
+rtpengine_offer("force trust-address symmetric replace-origin replace-session-connection ICE=force RTP/SAVPF");
+		</programlisting>
+		<para>
+			Finally, if you were using the second paramater (explicit media address) to any of
+			these functions, this has been replaced by the <quote>media-address=...</quote>
+			option within the first string of flags.
 		</para>
 	    </answer>
 	</qandaentry>

modules/rtpproxy-ng/rtpproxy.h → modules/rtpengine/rtpengine.h

@@ -24,8 +24,8 @@
 */
 
 
-#ifndef _RTPPROXY_H
-#define _RTPPROXY_H
+#ifndef _RTPENGINE_H
+#define _RTPENGINE_H
 
 #include "bencode.h"
 #include "../../str.h"

modules/rtpproxy-ng/rtpproxy_funcs.c → modules/rtpengine/rtpengine_funcs.c

@@ -31,7 +31,7 @@
 #include <stdlib.h>
 #include <sys/types.h>
 #include <unistd.h>
-#include "rtpproxy_funcs.h"
+#include "rtpengine_funcs.h"
 #include "../../dprint.h"
 #include "../../config.h"
 #include "../../ut.h"

modules/rtpproxy-ng/rtpproxy_funcs.h → modules/rtpengine/rtpengine_funcs.h

@@ -21,8 +21,8 @@
  */
 
 
-#ifndef _RTPPROXY_FUNCS_H
-#define _RTPPROXY_FUNCS_H
+#ifndef _RTPENGINE_FUNCS_H
+#define _RTPENGINE_FUNCS_H
 
 #include "../../str.h"
 #include "../../parser/msg_parser.h"

modules/rtpproxy-ng/README

@@ -1,677 +0,0 @@
-rtpproxy-ng Module
-
-Maxim Sobolev
-
-   Sippy Software, Inc.
-
-Juha Heinanen
-
-   TuTPro, Inc.
-
-Edited by
-
-Maxim Sobolev
-
-Edited by
-
-Bogdan-Andrei Iancu
-
-Edited by
-
-Juha Heinanen
-
-Edited by
-
-Sas Ovidiu
-
-Edited by
-
-Carsten Bock
-
-   ng-voice GmbH
-
-Edited by
-
-Richard Fuchs
-
-   Sipwise GmbH
-
-   Copyright (c) 2003-2008 Sippy Software, Inc.
-
-   Copyright (c) 2005 Voice Sistem SRL
-
-   Copyright (c) 2009-2014 TuTPro Inc.
-
-   Copyright (c) 2010 VoIPEmbedded Inc.
-
-   Copyright (c) 2013 Sipwise GmbH
-     __________________________________________________________________
-
-   Table of Contents
-
-   1. Admin Guide
-
-        1. Overview
-        2. Multiple RTPProxy usage
-        3. Dependencies
-
-              3.1. Kamailio Modules
-              3.2. External Libraries or Applications
-
-        4. Parameters
-
-              4.1. rtpproxy_sock (string)
-              4.2. rtpproxy_disable_tout (integer)
-              4.3. rtpproxy_tout (integer)
-              4.4. rtpproxy_retr (integer)
-              4.5. extra_id_pv (string)
-              4.6. setid_avp (string)
-
-        5. Functions
-
-              5.1. set_rtp_proxy_set(setid)
-              5.2. rtpproxy_offer([flags [, ip_address]])
-              5.3. rtpproxy_answer([flags [, ip_address]])
-              5.4. rtpproxy_destroy([flags])
-              5.5. unforce_rtp_proxy()
-              5.6. rtpproxy_manage([flags [, ip_address]])
-              5.7. start_recording()
-
-        6. Exported Pseudo Variables
-
-              6.1. $rtpstat
-
-        7. MI Commands
-
-              7.1. nh_enable_rtpp
-              7.2. nh_show_rtpp
-
-   2. Frequently Asked Questions
-
-   List of Examples
-
-   1.1. Set rtpproxy_sock parameter
-   1.2. Set rtpproxy_disable_tout parameter
-   1.3. Set rtpproxy_tout parameter
-   1.4. Set rtpproxy_retr parameter
-   1.5. Set extra_id_pv parameter
-   1.6. Set setid_avp parameter
-   1.7. set_rtp_proxy_set usage
-   1.8. rtpproxy_offer usage
-   1.9. rtpproxy_answer usage
-   1.10. rtpproxy_destroy usage
-   1.11. rtpproxy_manage usage
-   1.12. start_recording usage
-   1.13. $rtpstat Usage
-   1.14. nh_enable_rtpp usage
-   1.15. nh_show_rtpp usage
-
-Chapter 1. Admin Guide
-
-   Table of Contents
-
-   1. Overview
-   2. Multiple RTPProxy usage
-   3. Dependencies
-
-        3.1. Kamailio Modules
-        3.2. External Libraries or Applications
-
-   4. Parameters
-
-        4.1. rtpproxy_sock (string)
-        4.2. rtpproxy_disable_tout (integer)
-        4.3. rtpproxy_tout (integer)
-        4.4. rtpproxy_retr (integer)
-        4.5. extra_id_pv (string)
-        4.6. setid_avp (string)
-
-   5. Functions
-
-        5.1. set_rtp_proxy_set(setid)
-        5.2. rtpproxy_offer([flags [, ip_address]])
-        5.3. rtpproxy_answer([flags [, ip_address]])
-        5.4. rtpproxy_destroy([flags])
-        5.5. unforce_rtp_proxy()
-        5.6. rtpproxy_manage([flags [, ip_address]])
-        5.7. start_recording()
-
-   6. Exported Pseudo Variables
-
-        6.1. $rtpstat
-
-   7. MI Commands
-
-        7.1. nh_enable_rtpp
-        7.2. nh_show_rtpp
-
-1. Overview
-
-   This is a module that enables media streams to be proxied via an RTP
-   proxy. The only RTP proxy currently known to work with this module is
-   the Sipwise ngcp-rtpproxy-ng https://github.com/sipwise/mediaproxy-ng.
-   The rtpproxy-ng module is a modified version of the original rtpproxy
-   module using a new control protocol. The module is designed to be a
-   drop-in replacement for the old module from a configuration file point
-   of view, however due to the incompatible control protocol, it only
-   works with RTP proxies which specifically support it.
-
-2. Multiple RTPProxy usage
-
-   The rtpproxy-ng module can support multiple RTP proxies for
-   balancing/distribution and control/selection purposes.
-
-   The module allows definition of several sets of rtpproxies.
-   Load-balancing will be performed over a set and the admin has the
-   ability to choose what set should be used. The set is selected via its
-   id - the id being defined with the set. Refer to the "rtpproxy_sock"
-   module parameter definition for syntax description.
-
-   The balancing inside a set is done automatically by the module based on
-   the weight of each rtpproxy from the set.
-
-   The selection of the set is done from script prior using
-   unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() functions -
-   see the set_rtp_proxy_set() function.
-
-   Another way to select the set is to define setid_avp module parameter
-   and assign setid to the defined avp before calling rtpproxy_offer() or
-   rtpproxy_manage() function. If forwarding of the requests fails and
-   there is another branch to try, remember to unset the avp after calling
-   rtpproxy_destroy() function.
-
-   For backward compatibility reasons, a set with no id take by default
-   the id 0. Also if no set is explicitly set before unforce_rtp_proxy(),
-   rtpproxy_offer() or rtpproxy_answer() the 0 id set will be used.
-
-   IMPORTANT: if you use multiple sets, take care and use the same set for
-   both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!! If the
-   set was selected using setid_avp, the avp needs to be set only once
-   before rtpproxy_offer() or rtpproxy_manage() call.
-
-3. Dependencies
-
-   3.1. Kamailio Modules
-   3.2. External Libraries or Applications
-
-3.1. Kamailio Modules
-
-   The following modules must be loaded before this module:
-     * tm module - (optional) if you want to have rtpproxy_manage() fully
-       functional
-
-3.2. External Libraries or Applications
-
-   The following libraries or applications must be installed before
-   running Kamailio with this module loaded:
-     * None.
-
-4. Parameters
-
-   4.1. rtpproxy_sock (string)
-   4.2. rtpproxy_disable_tout (integer)
-   4.3. rtpproxy_tout (integer)
-   4.4. rtpproxy_retr (integer)
-   4.5. extra_id_pv (string)
-   4.6. setid_avp (string)
-
-4.1. rtpproxy_sock (string)
-
-   Definition of socket(s) used to connect to (a set) RTPProxy. It may
-   specify a UNIX socket or an IPv4/IPv6 UDP socket.
-
-   Default value is "NONE" (disabled).
-
-   Example 1.1. Set rtpproxy_sock parameter
-...
-# single rtproxy
-modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221")
-# multiple rtproxies for LB
-modparam("rtpproxy-ng", "rtpproxy_sock",
-        "udp:localhost:12221 udp:localhost:12222")
-# multiple sets of multiple rtproxies
-modparam("rtpproxy-ng", "rtpproxy_sock",
-        "1 == udp:localhost:12221 udp:localhost:12222")
-modparam("rtpproxy-ng", "rtpproxy_sock",
-        "2 == udp:localhost:12225")
-...
-
-4.2. rtpproxy_disable_tout (integer)
-
-   Once an RTP proxy was found unreachable and marked as disabled, the
-   rtpproxy-ng module will not attempt to establish communication to that
-   RTP proxy for rtpproxy_disable_tout seconds.
-
-   Default value is "60".
-
-   Example 1.2. Set rtpproxy_disable_tout parameter
-...
-modparam("rtpproxy-ng", "rtpproxy_disable_tout", 20)
-...
-
-4.3. rtpproxy_tout (integer)
-
-   Timeout value in waiting for reply from RTP proxy.
-
-   Default value is "1".
-
-   Example 1.3. Set rtpproxy_tout parameter
-...
-modparam("rtpproxy-ng", "rtpproxy_tout", 2)
-...
-
-4.4. rtpproxy_retr (integer)
-
-   How many times the module should retry to send and receive after
-   timeout was generated.
-
-   Default value is "5".
-
-   Example 1.4. Set rtpproxy_retr parameter
-...
-modparam("rtpproxy-ng", "rtpproxy_retr", 2)
-...
-
-4.5. extra_id_pv (string)
-
-   The parameter sets the PV defination to use when the "b" parameter is
-   used on unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
-   rtpproxy_manage() command.
-
-   Default is empty, the "b" parameter may not be used then.
-
-   Example 1.5. Set extra_id_pv parameter
-...
-modparam("rtpproxy-ng", "extra_id_pv", "$avp(extra_id)")
-...
-
-4.6. setid_avp (string)
-
-   The parameter defines an AVP that, if set, determines which rtpproxy
-   set rtpproxy_offer(), rtpproxy_answer(), rtpproxy_destroy(), and
-   rtpproxy_manage() functions use.
-
-   There is no default value.
-
-   Example 1.6. Set setid_avp parameter
-...
-modparam("rtpproxy-ng", "setid_avp", "$avp(setid)")
-...
-
-5. Functions
-
-   5.1. set_rtp_proxy_set(setid)
-   5.2. rtpproxy_offer([flags [, ip_address]])
-   5.3. rtpproxy_answer([flags [, ip_address]])
-   5.4. rtpproxy_destroy([flags])
-   5.5. unforce_rtp_proxy()
-   5.6. rtpproxy_manage([flags [, ip_address]])
-   5.7. start_recording()
-
-5.1.  set_rtp_proxy_set(setid)
-
-   Sets the Id of the rtpproxy set to be used for the next
-   unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
-   rtpproxy_manage() command. The parameter can be an integer or a config
-   variable holding an integer.
-
-   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-   BRANCH_ROUTE.
-
-   Example 1.7. set_rtp_proxy_set usage
-...
-set_rtp_proxy_set("2");
-rtpproxy_offer();
-...
-
-5.2.  rtpproxy_offer([flags [, ip_address]])
-
-   Rewrites SDP body to ensure that media is passed through an RTP proxy.
-   To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK
-   and on 200 OK when SDPs are in 200 OK and ACK.
-
-   Meaning of the parameters is as follows:
-     * flags - flags to turn on some features.
-          + 1 - append first Via branch to Call-ID when sending command to
-            rtpproxy. This can be used to create one media session per
-            branch on the rtpproxy. When sending a subsequent "delete"
-            command to the rtpproxy, you can then stop just the session
-            for a specific branch when passing the flag '1' or '2' in the
-            "unforce_rtpproxy", or stop all sessions for a call when not
-            passing one of those two flags there. This is especially
-            useful if you have serially forked call scenarios where
-            rtpproxy gets an "offer" command for a new branch, and then a
-            "delete" command for the previous branch, which would
-            otherwise delete the full call, breaking the subsequent
-            "answer" for the new branch. This flag is only supported by
-            the ngcp-mediaproxy-ng rtpproxy at the moment!
-          + 2 - append second Via branch to Call-ID when sending command
-            to rtpproxy. See flag '1' for its meaning.
-          + 3 - behave like flag 1 is set for a request and like flag 2 is
-            set for a reply.
-          + a - flags that UA from which message is received doesn't
-            support symmetric RTP. (automatically sets the 'r' flag)
-          + b - append branch specific variable to Call-ID when sending
-            command to rtpproxy. This creates one rtpproxy session per
-            unique variable. Works similar to the 1, 2 and 3 parameter,
-            but is usefull when forking to multiple destinations on
-            different address families or network segments, requiring
-            different rtpproxy parameters. The variable value is taken
-            from the "extra_id_pv". When used, it must be used in every
-            call to rtpproxy_manage(), rtpproxy_offer(), rtpproxy_answer()
-            and rtpproxy_destroy() with the same contents of the PV. The b
-            parameter may not be used in conjunction with the 1, 2 or 3
-            parameter to use the Via branch in the Call-ID.
-          + l - force "lookup", that is, only rewrite SDP when
-            corresponding session already exists in the RTP proxy. By
-            default is on when the session is to be completed.
-          + i, e - these flags specify the direction of the SIP message.
-            These flags only make sense when rtpproxy is running in bridge
-            mode. 'i' means internal network (LAN), 'e' means external
-            network (WAN). 'i' corresponds to rtpproxy's first interface,
-            'e' corresponds to rtpproxy's second interface. You always
-            have to specify two flags to define the incoming network and
-            the outgoing network. For example, 'ie' should be used for SIP
-            message received from the local interface and sent out on the
-            external interface, and 'ei' vice versa. Other options are
-            'ii' and 'ee'. So, for example if a SIP requests is processed
-            with 'ie' flags, the corresponding response must be processed
-            with 'ie' flags.
-            For ngcp-mediaproxy-ng, these flags are used to select between
-            IPv4 and IPv6 addresses, corresponding to 'i' and 'e'
-            respectively. For example, if the request is coming from an
-            IPv4 host and is going to an IPv6 host, the flags should be
-            specified as 'ie'.
-            Note: As rtpproxy in bridge mode s per default asymmetric, you
-            have to specify the 'w' flag for clients behind NAT! See also
-            above notes!
-          + x - this flag an alternative to the 'ie' or 'ei'-flags in
-            order to do automatic bridging between IPv4 on the "internal
-            network" and IPv6 on the "external network". Instead of
-            explicitly instructing the RTP proxy to select a particular
-            address family, the distinction is done by the given IP in the
-            SDP body by the RTP proxy itself. Not supported by
-            ngcp-mediaproxy-ng.
-            Note: Please note, that this will only work properly with
-            non-dual-stack user-agents or with dual-stack clients
-            according to RFC6157 (which suggest ICE for Dual-Stack
-            implementations). This short-cut will not work properly with
-            RFC4091 (ANAT) compatible clients, which suggests having
-            different m-lines with different IP-protocols grouped
-            together.
-          + f - instructs rtpproxy to ignore marks inserted by another
-            rtpproxy in transit to indicate that the session is already
-            goes through another proxy. Allows creating a chain of
-            proxies.
-          + r - flags that IP address in SDP should be trusted. Without
-            this flag, rtpproxy ignores address in the SDP and uses source
-            address of the SIP message as media address which is passed to
-            the RTP proxy.
-          + o - flags that IP from the origin description (o=) should be
-            also changed.
-          + c - flags to change the session-level SDP connection (c=) IP
-            if media-description also includes connection information.
-          + w - flags that for the UA from which message is received,
-            support symmetric RTP must be forced.
-          + zNN - requests the RTPproxy to perform re-packetization of RTP
-            traffic coming from the UA which has sent the current message
-            to increase or decrease payload size per each RTP packet
-            forwarded if possible. The NN is the target payload size in
-            ms, for the most codecs its value should be in 10ms
-            increments, however for some codecs the increment could differ
-            (e.g. 30ms for GSM or 20ms for G.723). The RTPproxy would
-            select the closest value supported by the codec. This feature
-            could be used for significantly reducing bandwith overhead for
-            low bitrate codecs, for example with G.729 going from 10ms to
-            100ms saves two thirds of the network bandwith.
-          + + - instructs the RTP proxy to discard any ICE attributes
-            already present in the SDP body and then generate and insert
-            new ICE data, leaving itself as the only ICE candidates.
-            Without this flag, new ICE data will only be generated if no
-            ICE was present in the SDP originally; otherwise the RTP proxy
-            will only insert itself as an additional ICE candidate. Other
-            SDP substitutions (c=, m=, etc) are unaffected by this flag.
-          + - - instructs the RTP proxy to discard any ICE attributes and
-            not insert any new ones into the SDP. Mutually exclusive with
-            the '+' flag.
-          + s, S, p, P - These flags control the RTP transport protocol
-            that should be used towards the recipient of the SDP. If none
-            of them are specified, the protocol given in the SDP is left
-            untouched. Otherwise, the "S" flag indicates that SRTP should
-            be used, while "s" indicates that SRTP should not be used. "P"
-            indicates that the advanced RTCP profile with feedback
-            messages should be used, and "p" indicates that the regular
-            RTCP profile should be used. As such, the combinations "sp",
-            "sP", "Sp" and "SP" select between RTP/AVP, RTP/AVPF, RTP/SAVP
-            and RTP/SAVPF, respectively.
-     * ip_address - new SDP IP address.
-
-   This function can be used from ANY_ROUTE.
-
-   Example 1.8. rtpproxy_offer usage
-route {
-...
-    if (is_method("INVITE")) {
-        if (has_body("application/sdp")) {
-            if (rtpproxy_offer())
-                t_on_reply("1");
-        } else {
-            t_on_reply("2");
-        }
-    }
-    if (is_method("ACK") && has_body("application/sdp"))
-        rtpproxy_answer();
-...
-}
-
-onreply_route[1]
-{
-...
-    if (has_body("application/sdp"))
-        rtpproxy_answer();
-...
-}
-
-onreply_route[2]
-{
-...
-    if (has_body("application/sdp"))
-        rtpproxy_offer();
-...
-}
-
-5.3.  rtpproxy_answer([flags [, ip_address]])
-
-   Rewrites SDP body to ensure that media is passed through an RTP proxy.
-   To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK
-   and on ACK when SDPs are in 200 OK and ACK.
-
-   See rtpproxy_answer() function description above for the meaning of the
-   parameters.
-
-   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-   FAILURE_ROUTE, BRANCH_ROUTE.
-
-   Example 1.9. rtpproxy_answer usage
-
-   See rtpproxy_offer() function example above for example.
-
-5.4.  rtpproxy_destroy([flags])
-
-   Tears down the RTPProxy session for the current call.
-
-   This function can be used from ANY_ROUTE.
-
-   Meaning of the parameters is as follows:
-     * flags - flags to turn on some features.
-          + 1 - append first Via branch to Call-ID when sending command to
-            rtpproxy. This can be used to create one media session per
-            branch on the rtpproxy. When sending a subsequent "delete"
-            command to the rtpproxy, you can then stop just the session
-            for a specific branch when passing the flag '1' or '2' in the
-            "unforce_rtpproxy", or stop all sessions for a call when not
-            passing one of those two flags there. This is especially
-            useful if you have serially forked call scenarios where
-            rtpproxy gets an "update" command for a new branch, and then a
-            "delete" command for the previous branch, which would
-            otherwise delete the full call, breaking the subsequent
-            "lookup" for the new branch. This flag is only supported by
-            the ngcp-mediaproxy-ng rtpproxy at the moment!
-          + 2 - append second Via branch to Call-ID when sending command
-            to rtpproxy. See flag '1' for its meaning.
-          + b - append branch specific variable to Call-ID when sending
-            command to rtpproxy. See rtpproxy_offer() for details.
-            <listitem>
-            </listitem>
-            t - do not include To tag to "delete" command to rtpproxy thus
-            causing full call to be deleted. Useful for deleting unused
-            rtpproxy call when 200 OK is received on a branch, where
-            rtpproxy is not needed.
-
-   Example 1.10. rtpproxy_destroy usage
-...
-rtpproxy_destroy();
-...
-
-5.5.  unforce_rtp_proxy()
-
-   Same as rtpproxy_destroy().
-
-5.6.  rtpproxy_manage([flags [, ip_address]])
-
-   Manage the RTPProxy session - it combines the functionality of
-   rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
-   internally based on message type and method which one to execute.
-
-   It can take the same parameters as rtpproxy_offer(). The flags
-   parameter to rtpproxy_manage() can be a configuration variable
-   containing the flags as a string.
-
-   Functionality:
-     * If INVITE with SDP, then do rtpproxy_offer()
-     * If INVITE with SDP, when the tm module is loaded, mark transaction
-       with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
-       rtpproxy_answer()
-     * If ACK with SDP, then do rtpproxy_answer()
-     * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
-       unforce_rtpproxy()
-     * If reply to INVITE with code >= 300 do unforce_rtpproxy()
-     * If reply with SDP to INVITE having code 1xx and 2xx, then do
-       rtpproxy_answer() if the request had SDP or tm is not loaded,
-       otherwise do rtpproxy_offer()
-
-   This function can be used from ANY_ROUTE.
-
-   Example 1.11. rtpproxy_manage usage
-...
-rtpproxy_manage();
-...
-
-5.7.  start_recording()
-
-   This function will send a signal to the RTP Proxy to record the RTP
-   stream on the RTP Proxy. This function is not supported by
-   ngcp-mediaproxy-ng at the moment!
-
-   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
-
-   Example 1.12. start_recording usage
-...
-start_recording();
-...
-
-6. Exported Pseudo Variables
-
-   6.1. $rtpstat
-
-6.1. $rtpstat
-
-   Returns the RTP Statistics from the RTP Proxy. The RTP Statistics from
-   the RTP Proxy are provided as a string and it does contain several
-   packet counters. The statistics must be retrieved before the session is
-   deleted (before unforce_rtpproxy()).
-
-   Example 1.13. $rtpstat Usage
-...
-    append_hf("X-RTP-Statistics: $rtpstat\r\n");
-...
-
-7. MI Commands
-
-   7.1. nh_enable_rtpp
-   7.2. nh_show_rtpp
-
-7.1. nh_enable_rtpp
-
-   Enables a rtp proxy if parameter value is greater than 0. Disables it
-   if a zero value is given.
-
-   The first parameter is the rtp proxy url (exactly as defined in the
-   config file).
-
-   The second parameter value must be a number in decimal.
-
-   NOTE: if a rtpproxy is defined multiple times (in the same or diferente
-   sete), all of its instances will be enables/disabled.
-
-   Example 1.14.  nh_enable_rtpp usage
-...
-$ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
-...
-
-7.2. nh_show_rtpp
-
-   Displays all the rtp proxies and their information: set and status
-   (disabled or not, weight and recheck_ticks).
-
-   No parameter.
-
-   Example 1.15.  nh_show_rtpp usage
-...
-$ kamctl fifo nh_show_rtpp
-...
-
-Chapter 2. Frequently Asked Questions
-
-   2.1. What happend with "rtpproxy_disable" parameter?
-   2.2. Where can I find more about Kamailio?
-   2.3. Where can I post a question about this module?
-   2.4. How can I report a bug?
-
-   2.1.
-
-       What happend with "rtpproxy_disable" parameter?
-
-       It was removed as it became obsolete - now "rtpproxy_sock" can take
-       empty value to disable the rtpproxy functionality.
-
-   2.2.
-
-       Where can I find more about Kamailio?
-
-       Take a look at http://www.kamailio.org/.
-
-   2.3.
-
-       Where can I post a question about this module?
-
-       First at all check if your question was already answered on one of our
-       mailing lists:
-         * User Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
-         * Developer Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
-
-       E-mails regarding any stable Kamailio release should be sent to
-       <[email protected]> and e-mails regarding development
-       versions should be sent to <[email protected]>.
-
-       If you want to keep the mail private, send it to
-       <[email protected]>.
-
-   2.4.
-
-       How can I report a bug?
-
-       Please follow the guidelines provided at:
-       http://sip-router.org/tracker.

modules/rtpproxy-ng/doc/rtpproxy_admin.xml

@@ -1,856 +0,0 @@
-<?xml version="1.0" encoding='ISO-8859-1'?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-
-<!-- Include general documentation entities -->
-<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
-%docentities;
-
-]>
-
-<!-- Module User's Guide -->
-
-<chapter>
-
-	<title>&adminguide;</title>
-
-	<section>
-	<title>Overview</title>
-	<para>
-		This is a module that enables media streams to be proxied
-		via an RTP proxy. The only RTP proxy currently known to work
-		with this module is the Sipwise ngcp-rtpproxy-ng
-		<ulink url="https://github.com/sipwise/mediaproxy-ng"></ulink>.
-		The rtpproxy-ng module is a modified version of the original
-		rtpproxy module using a new control protocol. The module is
-		designed to be a drop-in replacement for the old module from
-		a configuration file point of view, however due to the
-		incompatible control protocol, it only works with RTP proxies
-		which specifically support it.
-	</para>
-	</section>
-
-	<section>
-	<title>Multiple RTPProxy usage</title>
-	<para>
-		The rtpproxy-ng module can support multiple RTP proxies for
-		balancing/distribution and control/selection purposes.
-	</para>
-	<para>
-		The module allows definition of several sets of rtpproxies.
-		Load-balancing will be performed over a set and the admin has the
-		ability to choose what set should be used. The set is selected via
-		its id - the id being defined with the set. Refer to the
-		<quote>rtpproxy_sock</quote> module parameter definition for syntax
-		description.
-	</para>
-	<para>
-		The balancing inside a set is done automatically by the module based on
-		the weight of each rtpproxy from the set.
-	</para>
-	<para>
-		The selection of the set is done from script prior using
-		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
-		functions - see the set_rtp_proxy_set() function.
-	</para>
-	<para>
-	        Another way to select the set is to define setid_avp
-	        module parameter and assign setid to the defined avp
-	        before calling rtpproxy_offer() or rtpproxy_manage()
-	        function.  If forwarding of the requests fails and
-	        there is another branch to try, remember to unset the
-	        avp after calling rtpproxy_destroy() function.
-	</para>
-	<para>
-		For backward compatibility reasons, a set with no id take by default
-		the id 0. Also if no set is explicitly set before
-		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
-		the 0 id set will be used.
-	</para>
-	<para>
-		IMPORTANT: if you use multiple sets, take care and use the same set for
-		both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
-		If the set was selected using setid_avp, the avp needs to be
-		set only once before rtpproxy_offer() or rtpproxy_manage() call.
-	</para>
-	</section>
-
-	<section>
-	<title>Dependencies</title>
-	<section>
-		<title>&kamailio; Modules</title>
-		<para>
-		The following modules must be loaded before this module:
-			<itemizedlist>
-			<listitem>
-			<para>
-				<emphasis>tm module</emphasis> - (optional) if you want to
-				have rtpproxy_manage() fully functional
-			</para>
-			</listitem>
-			</itemizedlist>
-		</para>
-	</section>
-	<section>
-		<title>External Libraries or Applications</title>
-		<para>
-		The following libraries or applications must be installed before
-		running &kamailio; with this module loaded:
-			<itemizedlist>
-			<listitem>
-			<para>
-				<emphasis>None</emphasis>.
-			</para>
-			</listitem>
-			</itemizedlist>
-		</para>
-	</section>
-	</section>
-
-	<section>
-	<title>Parameters</title>
-	<section id="rtpproxy-ng.p.rtpproxy_sock">
-		<title><varname>rtpproxy_sock</varname> (string)</title>
-		<para>
-		Definition of socket(s) used to connect to (a set) RTPProxy. It may
-		specify a UNIX socket or an IPv4/IPv6 UDP socket.
-		</para>
-		<para>
-		<emphasis>
-			Default value is <quote>NONE</quote> (disabled).
-		</emphasis>
-		</para>
-		<example>
-		<title>Set <varname>rtpproxy_sock</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-# single rtproxy
-modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221")
-# multiple rtproxies for LB
-modparam("rtpproxy-ng", "rtpproxy_sock",
-	"udp:localhost:12221 udp:localhost:12222")
-# multiple sets of multiple rtproxies
-modparam("rtpproxy-ng", "rtpproxy_sock",
-	"1 == udp:localhost:12221 udp:localhost:12222")
-modparam("rtpproxy-ng", "rtpproxy_sock",
-	"2 == udp:localhost:12225")
-...
-</programlisting>
-		</example>
-	</section>
-	<section id="rtpproxy-ng.p.rtpproxy_disable_tout">
-		<title><varname>rtpproxy_disable_tout</varname> (integer)</title>
-		<para>
-		Once an RTP proxy was found unreachable and marked as disabled, the rtpproxy-ng
-		module will not attempt to establish communication to that RTP proxy for
-		rtpproxy_disable_tout seconds.
-		</para>
-		<para>
-		<emphasis>
-			Default value is <quote>60</quote>.
-		</emphasis>
-		</para>
-		<example>
-		<title>Set <varname>rtpproxy_disable_tout</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-modparam("rtpproxy-ng", "rtpproxy_disable_tout", 20)
-...
-</programlisting>
-		</example>
-	</section>
-	<section id="rtpproxy-ng.p.rtpproxy_tout">
-		<title><varname>rtpproxy_tout</varname> (integer)</title>
-		<para>
-		Timeout value in waiting for reply from RTP proxy.
-		</para>
-		<para>
-		<emphasis>
-			Default value is <quote>1</quote>.
-		</emphasis>
-		</para>
-		<example>
-		<title>Set <varname>rtpproxy_tout</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-modparam("rtpproxy-ng", "rtpproxy_tout", 2)
-...
-</programlisting>
-		</example>
-	</section>
-	<section id="rtpproxy-ng.p.rtpproxy_retr">
-		<title><varname>rtpproxy_retr</varname> (integer)</title>
-		<para>
-		How many times the module should retry to send and receive after
-		timeout was generated.
-		</para>
-		<para>
-		<emphasis>
-			Default value is <quote>5</quote>.
-		</emphasis>
-		</para>
-		<example>
-		<title>Set <varname>rtpproxy_retr</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-modparam("rtpproxy-ng", "rtpproxy_retr", 2)
-...
-</programlisting>
-		</example>
-	</section>
-<!--
-	<section>
-		<title><varname>timeout_socket</varname> (string)</title>
-		<para>
-		The parameter sets the RTP timeout socket, which is transmitted to the RTP Proxy.
-		It will be used by the RTP proxy to signal back that a media stream timed
-		out.
-		</para>
-		<para>
-		If it is an empty string, no timeout socket will be transmitted to the RTP-Proxy.
-		</para>
-		<para>
-		<emphasis>
-			Default value is <quote></quote> (nothing).
-		</emphasis>
-		</para>
-		<example>
-		<title>Set <varname>timeout_socket</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-modparam("nathelper", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
-...
-</programlisting>
-		</example>
-	</section>
--->
-	<section id="rtpproxy-ng.p.extra_id_pv">
-		<title><varname>extra_id_pv</varname> (string)</title>
-		<para>
-			The parameter sets the PV defination to use when the <quote>b</quote>
-			parameter is used on unforce_rtp_proxy(), rtpproxy_offer(),
-			rtpproxy_answer() or rtpproxy_manage() command.
-		</para><para>
-			Default is empty, the <quote>b</quote> parameter may not be used then.
-		</para>
-		<example>
-		<title>Set <varname>extra_id_pv</varname> parameter</title>
-		<programlisting format="linespecific">
-...
-modparam("rtpproxy-ng", "extra_id_pv", "$avp(extra_id)")
-...
-</programlisting>
-		</example>
-	</section>
-
-	<section id="rtpproxy-ng.p.setid_pv">
-		<title><varname>setid_avp</varname> (string)</title>
-		<para>
-			The parameter defines an AVP that, if set,
-			determines which rtpproxy set
-			rtpproxy_offer(), rtpproxy_answer(),
-			rtpproxy_destroy(), and rtpproxy_manage()
-			functions use.
-		</para>
-		<para>
-			There is no default value.
-		</para>
-		<example>
-		<title>Set <varname>setid_avp</varname> parameter</title>
-<programlisting format="linespecific">
-...
-modparam("rtpproxy-ng", "setid_avp", "$avp(setid)")
-...
-</programlisting>
-		</example>
-	</section>
-
-	</section>
-
-	<section>
-	<title>Functions</title>
-	<section id="rtpproxy-ng.f.set_rtp_proxy_set">
-		<title>
-		<function moreinfo="none">set_rtp_proxy_set(setid)</function>
-		</title>
-		<para>
-		Sets the Id of the rtpproxy set to be used for the next
-		unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer()
-		or rtpproxy_manage() command. The parameter can be an integer or
-		a config variable holding an integer.
-		</para>
-		<para>
-		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-		BRANCH_ROUTE.
-		</para>
-		<example>
-		<title><function>set_rtp_proxy_set</function> usage</title>
-		<programlisting format="linespecific">
-...
-set_rtp_proxy_set("2");
-rtpproxy_offer();
-...
-</programlisting>
-		</example>
-	</section>
-        <section id="rtpproxy-ng.f.rtpproxy_offer">
-                <title>
-                <function moreinfo="none">rtpproxy_offer([flags [, ip_address]])</function>
-                </title>
-                <para>
-                Rewrites &sdp; body to ensure that media is passed through
-                an &rtp; proxy. To be invoked
-		on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK
-		when SDPs are in 200 OK and ACK.
-                </para>
-		<para>Meaning of the parameters is as follows:</para>
-		<itemizedlist>
-		<listitem>
-			<para>
-			<emphasis>flags</emphasis> - flags to turn on some features.
-			</para>
-			<itemizedlist>
-				<listitem><para>
-				<emphasis>1</emphasis> - append first Via branch to Call-ID when sending
-				command to rtpproxy. This can be used to create one media session per branch
-				on the rtpproxy. When sending a subsequent <quote>delete</quote> command to
-				the rtpproxy, you can then stop just the session for a specific branch when
-				passing the flag '1' or '2' in the <quote>unforce_rtpproxy</quote>, or stop
-				all sessions for a call when not passing one of those two flags there. This is
-				especially useful if you have serially forked call scenarios where rtpproxy
-				gets an <quote>offer</quote> command for a new branch, and then a
-				<quote>delete</quote> command for the previous branch, which would otherwise
-				delete the full call, breaking the subsequent <quote>answer</quote> for the
-				new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
-				rtpproxy at the moment!</emphasis>
-				</para></listitem>
-				<listitem><para>
-				<emphasis>2</emphasis> - append second Via branch to Call-ID when sending
-				command to rtpproxy. See flag '1' for its meaning.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>3</emphasis> - behave like flag 1 is set for a request and
-				like flag 2 is set for a reply.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>a</emphasis> - flags that UA from which message is
-				received doesn't support symmetric RTP. (automatically sets the 'r' flag)
-				</para></listitem>
-				<listitem><para>
-				<emphasis>b</emphasis> - append branch specific variable to Call-ID when sending
-				command to rtpproxy. This creates one rtpproxy session per unique variable.
-
-				Works similar to the 1, 2 and 3 parameter, but is usefull when forking to multiple
-				destinations on different address families or network segments, requiring different
-				rtpproxy parameters.
-
-				The variable value is taken from the <quote>extra_id_pv</quote>.
-
-				When used, it must be used in every call to rtpproxy_manage(), rtpproxy_offer(),
-				rtpproxy_answer() and rtpproxy_destroy() with the same contents of the PV.
-				The b parameter may not be used in conjunction with the 1, 2 or 3 parameter
-				to use the Via branch in the Call-ID.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>l</emphasis> - force <quote>lookup</quote>, that is,
-				only rewrite SDP when corresponding session already exists
-				in the RTP proxy. By default is on when the session is to be
-				completed.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>i, e</emphasis> - these flags specify the direction of the SIP
-				message. These flags only make sense when rtpproxy is running in bridge mode.
-				'i' means internal network (LAN), 'e' means external network (WAN). 'i'
-				corresponds to rtpproxy's first interface, 'e' corresponds to rtpproxy's
-				second interface. You always have to specify two flags to define
-				the incoming network and the outgoing network. For example, 'ie' should be
-				used for SIP message received from the local interface and sent out on the
-				external interface, and 'ei' vice versa. Other options are 'ii' and 'ee'.
-				So, for example if a SIP requests is processed with 'ie' flags, the corresponding
-				response must be processed with 'ie' flags.
-				</para><para>
-				For ngcp-mediaproxy-ng, these flags are used to select between IPv4
-				and IPv6 addresses, corresponding to 'i' and 'e' respectively. For example,
-				if the request is coming from an IPv4 host and is going to an IPv6 host,
-				the flags should be specified as 'ie'.
-				</para><para>
-				Note: As rtpproxy in bridge mode s per default asymmetric, you have to specify
-				the 'w' flag for clients behind NAT! See also above notes!
-				</para></listitem>
-				<listitem><para>
-				<emphasis>x</emphasis> - this flag an alternative to the 'ie' or 'ei'-flags
-				in order to do automatic bridging between IPv4 on the
-				"internal network" and IPv6 on the "external network". Instead of
-				explicitly instructing the RTP proxy to select a particular address
-				family, the distinction is done by the given IP in the SDP body by
-				the RTP proxy itself. Not supported by ngcp-mediaproxy-ng.
-				</para><para>
-				Note: Please note, that this will only work properly with non-dual-stack user-agents or with
-				dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
-				This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
-				having different m-lines with different IP-protocols grouped together.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>f</emphasis> - instructs rtpproxy to ignore marks
-				inserted by another rtpproxy in transit to indicate that the
-				session is already goes through another proxy. Allows creating
-				a chain of proxies.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>r</emphasis> - flags that IP address in SDP should
-				be trusted. Without this flag, rtpproxy ignores address in
-				the SDP and uses source address of the SIP message as media
-				address which is passed to the RTP proxy.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>o</emphasis> - flags that IP from the origin
-				description (o=) should be also changed.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>c</emphasis> - flags to change the session-level
-				SDP connection (c=) IP if media-description also includes
-				connection information.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>w</emphasis> - flags that for the UA from which
-				message is received, support symmetric RTP must be forced.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>zNN</emphasis> - requests the RTPproxy to perform
-				re-packetization of RTP traffic coming from the UA which
-				has sent the current message to increase or decrease payload
-				size per each RTP packet forwarded if possible.  The NN is the
-				target payload size in ms, for the most codecs its value should
-				be in 10ms increments, however for some codecs the increment
-				could differ (e.g. 30ms for GSM or 20ms for G.723).  The
-				RTPproxy would select the closest value supported by the codec.
-				This feature could be used for significantly reducing bandwith
-				overhead for low bitrate codecs, for example with G.729 going
-				from 10ms to 100ms saves two thirds of the network bandwith.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>+</emphasis> - instructs the RTP proxy to
-				discard any ICE attributes already present in the SDP body
-				and then generate and insert new ICE data, leaving itself
-				as the <emphasis>only</emphasis> ICE candidates. Without
-				this flag, new ICE data will only be generated
-				if no ICE was present in the SDP originally; otherwise
-				the RTP proxy will only insert itself as an
-				<emphasis>additional</emphasis> ICE candidate. Other
-				SDP substitutions (c=, m=, etc) are unaffected by this flag.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>-</emphasis> - instructs the RTP proxy to discard
-				any ICE attributes and not insert any new ones into the SDP.
-				Mutually exclusive with the '+' flag.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>s, S, p, P</emphasis> - These flags control the RTP
-				transport protocol that should be used towards the recipient of
-				the SDP. If none of them are specified, the protocol given in
-				the SDP is left untouched. Otherwise, the "S" flag indicates that
-				SRTP should be used, while "s" indicates that SRTP should not be used.
-				"P" indicates that the advanced RTCP profile with feedback messages
-				should be used, and "p" indicates that the regular RTCP profile
-				should be used. As such, the combinations "sp", "sP", "Sp" and "SP"
-				select between RTP/AVP, RTP/AVPF, RTP/SAVP and RTP/SAVPF,
-				respectively.
-				</para></listitem>
-			</itemizedlist>
-		</listitem>
-		<listitem><para>
-		<emphasis>ip_address</emphasis> - new SDP IP address.
-		</para></listitem>
-		</itemizedlist>
-		<para>
-		This function can be used from ANY_ROUTE.
-                </para>
-		<example>
-		<title><function>rtpproxy_offer</function> usage</title>
-		<programlisting format="linespecific">
-route {
-...
-    if (is_method("INVITE")) {
-        if (has_body("application/sdp")) {
-            if (rtpproxy_offer())
-                t_on_reply("1");
-        } else {
-            t_on_reply("2");
-        }
-    }
-    if (is_method("ACK") &amp;&amp; has_body("application/sdp"))
-        rtpproxy_answer();
-...
-}
-
-onreply_route[1]
-{
-...
-    if (has_body("application/sdp"))
-        rtpproxy_answer();
-...
-}
-
-onreply_route[2]
-{
-...
-    if (has_body("application/sdp"))
-        rtpproxy_offer();
-...
-}
-</programlisting>
-                </example>
-	</section>
-        <section id="rtpproxy-ng.f.rtpproxy_answer">
-                <title>
-                <function moreinfo="none">rtpproxy_answer([flags [, ip_address]])</function>
-                </title>
-		<para>
-		Rewrites &sdp; body to ensure that media is passed through
-		an &rtp; proxy. To be invoked
-		on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK
-		when SDPs are in 200 OK and ACK.
-		</para>
-		<para>
-		See rtpproxy_answer() function description above for the meaning of the
-		parameters.
-		</para>
-		<para>
-		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-		FAILURE_ROUTE, BRANCH_ROUTE.
-		</para>
-		<example>
-		 <title><function>rtpproxy_answer</function> usage</title>
-		<para>
-		See rtpproxy_offer() function example above for example.
-		</para>
-		</example>
-        </section>
-	<section id="rtpproxy-ng.f.rtpproxy_destroy">
-		<title>
-		<function moreinfo="none">rtpproxy_destroy([flags])</function>
-		</title>
-		<para>
-		Tears down the RTPProxy session for the current call.
-		</para>
-		<para>
-		This function can be used from ANY_ROUTE.
-		</para>
-		<para>Meaning of the parameters is as follows:</para>
-		<itemizedlist>
-		<listitem>
-			<para>
-			<emphasis>flags</emphasis> - flags to turn on some features.
-			</para>
-			<itemizedlist>
-				<listitem><para>
-				<emphasis>1</emphasis> - append first Via branch to Call-ID when sending
-				command to rtpproxy. This can be used to create one media session per branch
-				on the rtpproxy. When sending a subsequent <quote>delete</quote> command to
-				the rtpproxy, you can then stop just the session for a specific branch when
-				passing the flag '1' or '2' in the <quote>unforce_rtpproxy</quote>, or stop
-				all sessions for a call when not passing one of those two flags there. This is
-				especially useful if you have serially forked call scenarios where rtpproxy
-				gets an <quote>update</quote> command for a new branch, and then a
-				<quote>delete</quote> command for the previous branch, which would otherwise
-				delete the full call, breaking the subsequent <quote>lookup</quote> for the
-				new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
-				rtpproxy at the moment!</emphasis>
-				</para></listitem>
-				<listitem><para>
-				<emphasis>2</emphasis> - append second Via branch to Call-ID when sending
-				command to rtpproxy. See flag '1' for its meaning.
-				</para></listitem>
-				<listitem><para>
-				<emphasis>b</emphasis> - append branch specific variable to Call-ID when sending
-				command to rtpproxy. See rtpproxy_offer() for details.
-				<listitem><para>
-				</para></listitem>
-				<emphasis>t</emphasis> - do not include To tag to <quote>delete</quote> command to rtpproxy thus causing full call to be deleted. Useful for deleting unused rtpproxy call when 200 OK is received on a branch, where rtpproxy is not needed.
-				</para></listitem>
-			</itemizedlist>
-		</listitem>
-		</itemizedlist>
-		<example>
-		<title><function>rtpproxy_destroy</function> usage</title>
-		<programlisting format="linespecific">
-...
-rtpproxy_destroy();
-...
-</programlisting>
-		</example>
-	</section>
-	<section id="rtpproxy-ng.f.unforce_rtp_proxy">
-		<title>
-		<function moreinfo="none">unforce_rtp_proxy()</function>
-		</title>
-		<para>
-			Same as rtpproxy_destroy().
-		</para>
-	</section>
-
-    <section id="rtpproxy-ng.f.rtpproxy_manage">
-        <title>
-        <function moreinfo="none">rtpproxy_manage([flags [, ip_address]])</function>
-        </title>
-		<para>
-		Manage the RTPProxy session - it combines the functionality of
-		rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
-		internally based on message type and method which one to execute.
-		</para>
-		<para>
-		It can take the same parameters as <function>rtpproxy_offer().</function>
-		The flags parameter to rtpproxy_manage() can be a configuration variable
-		containing the flags as a string.
-		</para>
-		<para>
-		Functionality:
-		</para>
-		<itemizedlist>
-		<listitem>
-			<para>
-			If INVITE with SDP, then do <function>rtpproxy_offer()</function>
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			If INVITE with SDP, when the tm module is loaded, mark transaction with
-			internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
-			<function>rtpproxy_answer()</function>
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			If ACK with SDP, then do <function>rtpproxy_answer()</function>
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do <function>unforce_rtpproxy()</function>
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			If reply to INVITE with code >= 300 do <function>unforce_rtpproxy()</function>
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			If reply with SDP to INVITE having code 1xx and 2xx, then
-			do <function>rtpproxy_answer()</function> if the request had SDP or tm is not loaded,
-			otherwise do <function>rtpproxy_offer()</function>
-			</para>
-		</listitem>
-	</itemizedlist>
-
-		<para>
-		This function can be used from ANY_ROUTE.
-		</para>
-		<example>
-		 <title><function>rtpproxy_manage</function> usage</title>
-		<programlisting format="linespecific">
-...
-rtpproxy_manage();
-...
-</programlisting>
-		</example>
-        </section>
-
-<!--
-	<section id="rtpproxy_stream2uac">
-	<title>
-	    <function>rtpproxy_stream2uac(prompt_name, count)</function>,
-	</title>
-	<para>
-	    Instruct the RTPproxy to stream prompt/announcement pre-encoded with
-	    the makeann command from the RTPproxy distribution. The uac/uas
-	    suffix selects who will hear the announcement relatively to the current
-	    transaction - UAC or UAS. For example invoking the
-	    <function>rtpproxy_stream2uac</function> in the request processing
-	    block on ACK transaction will play the prompt to the UA that has
-	    generated original INVITE and ACK while
-	    <function>rtpproxy_stop_stream2uas</function> on 183 in reply
-	    processing block will play the prompt to the UA that has generated 183.
-	</para>
-	<para>
-	    Apart from generating announcements, another possible application
-	    of this function is implementing music on hold (MOH) functionality.
-	    When count is -1, the streaming will be in loop indefinitely until
-	    the appropriate <function>rtpproxy_stop_stream2xxx</function> is issued.
-	</para>
-	<para>
-	    In order to work correctly, these functions require that a session in the
-	    RTPproxy already exists. Also those functions don't alter the SDP, so that
-	    they are not a substitute for calling <function>rtpproxy_offer</function>
-	    or <function>rtpproxy_answer</function>.
-	</para>
-	<para>
-	    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
-	</para>
-	<para>Meaning of the parameters is as follows:</para>
-	<itemizedlist>
-	    <listitem>
-		<para>
-		    <emphasis>prompt_name</emphasis> - name of the prompt to
-		    stream. Should be either absolute pathname or pathname
-		    relative to the directory where RTPproxy runs.
-		</para>
-	    </listitem>
-	    <listitem>
-		<para>
-		    <emphasis>count</emphasis> - number of times the prompt
-		    should be repeated. A value of -1 means that it will
-		    be streaming in a loop indefinitely, until the appropriate
-		    <function>rtpproxy_stop_stream2xxx</function> is issued.
-		</para>
-	    </listitem>
-	</itemizedlist>
-	<example>
-	    <title><function>rtpproxy_stream2xxx</function> usage</title>
-	    <programlisting>
-...
-    if (is_method("INVITE")) {
-        rtpproxy_offer();
-        if (detect_hold()) {
-            rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
-        } else {
-            rtpproxy_stop_stream2uas();
-        };
-    };
-...
-	    </programlisting>
-	</example>
-	</section>
-	<section id="rtpproxy_stream2uas">
-	<title>
-	    <function>rtpproxy_stream2uas(prompt_name, count)</function>
-	</title>
-	<para>
-		See function <function>rtpproxy_stream2uac(prompt_name, count)</function>.
-	</para>
-	</section>
-	<section id="rtpproxy_stop_stream2uac">
-	<title>
-	    <function>rtpproxy_stop_stream2uac()</function>,
-	</title>
-	<para>
-	    Stop streaming of announcement/prompt/MOH started previously by the
-	    respective <function>rtpproxy_stream2xxx</function>.  The uac/uas
-	    suffix selects whose announcement relatively to tha current
-	    transaction should be stopped - UAC or UAS.
-	</para>
-	<para>
-	    These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
-	</para>
-	</section>
--->
-	<section id="rtpproxy-ng.f.start_recording">
-		<title>
-		<function moreinfo="none">start_recording()</function>
-		</title>
-		<para>
-		This function will send a signal to the RTP Proxy to record
-		the RTP stream on the RTP Proxy.
-		<emphasis>This function is not supported by ngcp-mediaproxy-ng at the moment!</emphasis>
-		</para>
-		<para>
-		This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
-		</para>
-		<example>
-		<title><function>start_recording</function> usage</title>
-		<programlisting format="linespecific">
-...
-start_recording();
-...
-		</programlisting>
-		</example>
-	</section>
-<!--
-	<section id="rtpproxy_stop_stream2uas">
-	<title>
-	    <function>rtpproxy_stop_stream2uas(prompt_name, count)</function>
-	</title>
-	<para>
-		See function <function>rtpproxy_stop_stream2uac(prompt_name, count)</function>.
-	</para>
-	</section>
--->
-
-
-	</section>
-
-	<section>
-		<title>Exported Pseudo Variables</title>
-		<section>
-			<title><function moreinfo="none">$rtpstat</function></title>
-			<para>
-			Returns the RTP Statistics from the RTP Proxy. The RTP Statistics from the RTP Proxy
-			are provided as a string and it does contain several packet counters. The statistics
-			must be retrieved before the session is deleted	(before <function>unforce_rtpproxy()</function>).
-			</para>
-
-		<example>
-		<title>$rtpstat Usage</title>
-		<programlisting format="linespecific">
-...
-    append_hf("X-RTP-Statistics: $rtpstat\r\n");
-...
-		</programlisting>
-		</example>
-	        </section>
-
-	</section>
-
-	<section>
-		<title><acronym>MI</acronym> Commands</title>
-		<section id="rtpproxy-ng.m.nh_enable_rtpp">
-			<title><function moreinfo="none">nh_enable_rtpp</function></title>
-			<para>
-			Enables a rtp proxy if parameter value is greater than 0.
-			Disables it if a zero value is given.
-			</para>
-			<para>
-			The first parameter is the rtp proxy url (exactly as defined in
-			the config file).
-			</para>
-			<para>
-			The second parameter value must be a number in decimal.
-			</para>
-			<para>
-			NOTE: if a rtpproxy is defined multiple times (in the same or
-			diferente sete), all of its instances will be enables/disabled.
-			</para>
-			<example>
-			<title>
-			<function moreinfo="none">nh_enable_rtpp</function> usage</title>
-			<programlisting format="linespecific">
-...
-$ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
-...
-			</programlisting>
-			</example>
-		</section>
-
-			<section id="rtpproxy-ng.m.nh_show_rtpp">
-			<title><function moreinfo="none">nh_show_rtpp</function></title>
-			<para>
-			Displays all the rtp proxies and their information: set and
-			status (disabled or not, weight and recheck_ticks).
-			</para>
-			<para>
-			No parameter.
-			</para>
-			<example>
-			<title>
-				<function moreinfo="none">nh_show_rtpp</function> usage</title>
-			<programlisting format="linespecific">
-...
-$ &ctltool; fifo nh_show_rtpp
-...
-			</programlisting>
-			</example>
-		</section>
-	</section>
-
-</chapter>
-