src/modules/rtpproxy/README
03d5fa36
 rtpproxy Module
cef5d23c
 
 Maxim Sobolev
 
    Sippy Software, Inc.
 
 Juha Heinanen
 
    TuTPro, Inc.
 
 Edited by
 
 Maxim Sobolev
 
 Edited by
 
 Bogdan-Andrei Iancu
 
 Edited by
 
 Juha Heinanen
 
03d5fa36
 Edited by
 
 Sas Ovidiu
 
5b597906
 Edited by
 
 Carsten Bock
 
    ng-voice GmbH
 
9cb2a163
    Copyright © 2003-2008 Sippy Software, Inc.
cef5d23c
 
9cb2a163
    Copyright © 2005 Voice Sistem SRL
cef5d23c
 
9cb2a163
    Copyright © 2009-2012 TuTPro Inc.
03d5fa36
 
9cb2a163
    Copyright © 2010 VoIPEmbedded Inc.
7a78bdff
      __________________________________________________________________
cef5d23c
 
    Table of Contents
 
    1. Admin Guide
 
4efa4b21
         1. Overview
         2. Multiple RTPProxy usage
         3. Dependencies
cef5d23c
 
4efa4b21
               3.1. Kamailio Modules
               3.2. External Libraries or Applications
03d5fa36
 
4bdd3b99
         4. Parameters
03d5fa36
 
4efa4b21
               4.1. rtpproxy_sock (string)
               4.2. rtpproxy_disable_tout (integer)
               4.3. rtpproxy_tout (integer)
               4.4. rtpproxy_retr (integer)
1cfa90d1
               4.5. nortpproxy_str (string)
               4.6. timeout_socket (string)
75fde552
               4.7. ice_candidate_priority_avp (string)
a2d09db9
               4.8. extra_id_pv (string)
9a0e5866
               4.9. db_url (string)
               4.10. table_name (string)
221cdf84
               4.11. rtp_inst_pvar (string)
03d5fa36
 
4bdd3b99
         5. Functions
03d5fa36
 
7a78bdff
               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. rtpproxy_stream2uac(prompt_name, count),
               5.8. rtpproxy_stream2uas(prompt_name, count)
               5.9. rtpproxy_stop_stream2uac(),
5508e6d6
               5.10. rtpproxy_stop_stream2uas()
               5.11. start_recording()
cef5d23c
 
4efa4b21
         6. Exported Pseudo Variables
94c8e2f4
 
a0b01f77
               6.1. $rtpstat
94c8e2f4
 
c665d73d
         7. RPC Commands
cef5d23c
 
c665d73d
               7.1. rtpproxy.enable
               7.2. rtpproxy.list
cef5d23c
 
    2. Frequently Asked Questions
 
    List of Examples
 
03d5fa36
    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
1cfa90d1
    1.5. Set nortpproxy_str parameter
    1.6. Set timeout_socket parameter
75fde552
    1.7. Set ice_candidate_priority_avp parameter
a2d09db9
    1.8. Set extra_id_pv parameter
9a0e5866
    1.9. Set db_url parameter
    1.10. Set table_name parameter
221cdf84
    1.11. Set rtp_inst_pvar parameter
37e8d647
    1.12. rtp_inst_pvar usage
    1.13. set_rtp_proxy_set usage
    1.14. rtpproxy_offer usage
    1.15. rtpproxy_answer usage
    1.16. rtpproxy_destroy usage
    1.17. rtpproxy_manage usage
    1.18. rtpproxy_stream2xxx usage
5508e6d6
    1.19. rtpproxy_stop_stream2uas usage
    1.20. start_recording usage
    1.21. $rtpstat-Usage
    1.22. rtpproxy.enable usage
    1.23. rtpproxy.list usage
cef5d23c
 
 Chapter 1. Admin Guide
 
4efa4b21
    Table of Contents
 
    1. Overview
    2. Multiple RTPProxy usage
    3. Dependencies
 
         3.1. Kamailio Modules
         3.2. External Libraries or Applications
 
4bdd3b99
    4. Parameters
4efa4b21
 
         4.1. rtpproxy_sock (string)
         4.2. rtpproxy_disable_tout (integer)
         4.3. rtpproxy_tout (integer)
         4.4. rtpproxy_retr (integer)
1cfa90d1
         4.5. nortpproxy_str (string)
         4.6. timeout_socket (string)
75fde552
         4.7. ice_candidate_priority_avp (string)
a2d09db9
         4.8. extra_id_pv (string)
9a0e5866
         4.9. db_url (string)
         4.10. table_name (string)
221cdf84
         4.11. rtp_inst_pvar (string)
4efa4b21
 
4bdd3b99
    5. Functions
4efa4b21
 
7a78bdff
         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. rtpproxy_stream2uac(prompt_name, count),
         5.8. rtpproxy_stream2uas(prompt_name, count)
         5.9. rtpproxy_stop_stream2uac(),
5508e6d6
         5.10. rtpproxy_stop_stream2uas()
         5.11. start_recording()
4efa4b21
 
    6. Exported Pseudo Variables
94c8e2f4
 
a0b01f77
         6.1. $rtpstat
94c8e2f4
 
c665d73d
    7. RPC Commands
4efa4b21
 
c665d73d
         7.1. rtpproxy.enable
         7.2. rtpproxy.list
4efa4b21
 
 1. Overview
03d5fa36
 
7a78bdff
    This is a module that enables media streams to be proxied via an
    rtpproxy. Rtpproxies know to work with this module are Sippy RTPproxy
a041479b
    http://www.rtpproxy.org and ngcp-rtpproxy-ng
7a78bdff
    http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng. Some
    features of the rtpproxy module apply only to one of the two
1cfa90d1
    rtpproxies.
cef5d23c
 
4efa4b21
 2. Multiple RTPProxy usage
03d5fa36
 
7a78bdff
    The rtpproxy module can support multiple rtpproxies for
cef5d23c
    balancing/distribution and control/selection purposes.
 
7a78bdff
    The module allows definition of several sets of rtpproxies.
    Load-balancing will be performed over a set and the admin has the
cef5d23c
    ability to choose what set should be used. The set is selected via its
9cb2a163
    id - the id being defined with the set. Refer to the “rtpproxy_sock”
1cfa90d1
    module parameter definition for syntax description.
cef5d23c
 
7a78bdff
    The balancing inside a set is done automatically by the module based on
    the weight of each rtpproxy from the set.
cef5d23c
 
7a78bdff
    The selection of the set is done from script prior using
bf155292
    unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() functions -
    see the set_rtp_proxy_set() function.
cef5d23c
 
7a78bdff
    For backward compatibility reasons, a set with no id take by default
bf155292
    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.
cef5d23c
 
7a78bdff
    IMPORTANT: if you use multiple sets, take care and use the same set for
    both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
cef5d23c
 
4efa4b21
 3. Dependencies
cef5d23c
 
4efa4b21
    3.1. Kamailio Modules
    3.2. External Libraries or Applications
 
 3.1. Kamailio Modules
cef5d23c
 
    The following modules must be loaded before this module:
96db2732
      * tm module - (optional) if you want to have rtpproxy_manage() fully
        functional
cef5d23c
 
4efa4b21
 3.2. External Libraries or Applications
cef5d23c
 
7a78bdff
    The following libraries or applications must be installed before
cef5d23c
    running Kamailio with this module loaded:
      * None.
 
4bdd3b99
 4. Parameters
4efa4b21
 
    4.1. rtpproxy_sock (string)
    4.2. rtpproxy_disable_tout (integer)
    4.3. rtpproxy_tout (integer)
    4.4. rtpproxy_retr (integer)
1cfa90d1
    4.5. nortpproxy_str (string)
    4.6. timeout_socket (string)
75fde552
    4.7. ice_candidate_priority_avp (string)
a2d09db9
    4.8. extra_id_pv (string)
9a0e5866
    4.9. db_url (string)
    4.10. table_name (string)
221cdf84
    4.11. rtp_inst_pvar (string)
cef5d23c
 
4efa4b21
 4.1. rtpproxy_sock (string)
cef5d23c
 
9a0e5866
    Used to define the list of RTPPRoxy instances to connect to. These can
7a78bdff
    be UNIX sockets or IPv4/IPv6 UDP sockets. Each modparam entry will
    insert sockets into a single set. If no set ID is given, the default
9a0e5866
    set ID '0' will be used. To define multiple sets add the set number at
7a78bdff
    the beginning of each parameter followed by '=='. Sockets can be
    weighted by adding '=#' to a socket where # is an integer. A socket
    with a weight of 2 will be chosen twice as often as one with a weight
9a0e5866
    of 1.
cef5d23c
 
9cb2a163
    Default value is “NONE” (disabled).
cef5d23c
 
03d5fa36
    Example 1.1. Set rtpproxy_sock parameter
cef5d23c
 ...
 # single rtproxy
03d5fa36
 modparam("rtpproxy", "rtpproxy_sock", "udp:localhost:12221")
9a0e5866
 
cef5d23c
 # multiple rtproxies for LB
03d5fa36
 modparam("rtpproxy", "rtpproxy_sock",
cef5d23c
         "udp:localhost:12221 udp:localhost:12222")
9a0e5866
 
cef5d23c
 # multiple sets of multiple rtproxies
03d5fa36
 modparam("rtpproxy", "rtpproxy_sock",
cef5d23c
         "1 == udp:localhost:12221 udp:localhost:12222")
03d5fa36
 modparam("rtpproxy", "rtpproxy_sock",
cef5d23c
         "2 == udp:localhost:12225")
 ...
 
4efa4b21
 4.2. rtpproxy_disable_tout (integer)
cef5d23c
 
7a78bdff
    Once RTPProxy was found unreachable and marked as disabled, the
    rtpproxy module will not attempt to establish communication to RTPProxy
    for rtpproxy_disable_tout seconds.
cef5d23c
 
9cb2a163
    Default value is “60”.
cef5d23c
 
03d5fa36
    Example 1.2. Set rtpproxy_disable_tout parameter
cef5d23c
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_disable_tout", 20)
cef5d23c
 ...
 
4efa4b21
 4.3. rtpproxy_tout (integer)
cef5d23c
 
    Timeout value in waiting for reply from RTPProxy.
 
9cb2a163
    Default value is “1”.
cef5d23c
 
03d5fa36
    Example 1.3. Set rtpproxy_tout parameter
cef5d23c
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_tout", 2)
cef5d23c
 ...
 
4efa4b21
 4.4. rtpproxy_retr (integer)
cef5d23c
 
7a78bdff
    How many times the module should retry to send and receive after
1cfa90d1
    timeout was generated.
cef5d23c
 
9cb2a163
    Default value is “5”.
cef5d23c
 
03d5fa36
    Example 1.4. Set rtpproxy_retr parameter
cef5d23c
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_retr", 2)
cef5d23c
 ...
 
1cfa90d1
 4.5. nortpproxy_str (string)
cef5d23c
 
7a78bdff
    This parameter sets the SDP attribute used by rtpproxy to mark the
8868e624
    message's SDP attachment with information that it have already been
1cfa90d1
    changed.
cef5d23c
 
    If empty string, no marker will be added or checked.
 
 Note
 
    The string must be a complete SDP line, including the EOH (\r\n).
 
9cb2a163
    Default value is “a=nortpproxy:yes\r\n”.
cef5d23c
 
1cfa90d1
    Example 1.5. Set nortpproxy_str parameter
cef5d23c
 ...
03d5fa36
 modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
cef5d23c
 ...
 
1cfa90d1
 4.6. timeout_socket (string)
94c8e2f4
 
1cfa90d1
    The parameter sets the RTP timeout socket, which is transmitted to the
7a78bdff
    RTP-Proxy. It will be used by the RTP proxy to signal back that a media
    stream timed out.
94c8e2f4
 
    If it is an empty string, no timeout socket will be transmitted to the
    RTP-Proxy.
 
9cb2a163
    Default value is “” (nothing).
94c8e2f4
 
1cfa90d1
    Example 1.6. Set timeout_socket parameter
94c8e2f4
 ...
9a0e5866
 modparam("rtpproxy", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
94c8e2f4
 ...
 
75fde552
 4.7. ice_candidate_priority_avp (string)
 
7a78bdff
    If specified and if value of the avp value is not 0, rtpproxy_manage
    function adds ICE relay candidate attributes to sdp stream(s)
75fde552
    containing ICE candidate attributes.
 
7a78bdff
    If value of the avp is 1, added candidates have high priority. If value
    of the avp is 2 (default), added candidates have low priority.
75fde552
 
7a78bdff
    There is no default value meaning that no ICE relay candidates are
    added in any circumstance.
75fde552
 
    Example 1.7. Set ice_candidate_priority_avp parameter
 ...
 modparam("rtpproxy", "ice_candidate_priority_avp", "$avp(ice_priority)")
 ...
 
a2d09db9
 4.8. extra_id_pv (string)
 
8868e624
    The parameter sets the PV definition to use when the “b” parameter is
7a78bdff
    used on unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
a2d09db9
    rtpproxy_manage() command.
 
9cb2a163
    Default is empty, the “b” parameter may not be used then.
a2d09db9
 
    Example 1.8. Set extra_id_pv parameter
 ...
 modparam("rtpproxy", "extra_id_pv", "$avp(extra_id)")
 ...
 
9a0e5866
 4.9. db_url (string)
 
7a78bdff
    The database URL to load rtp_proxy sets from. If this parameter is set,
    the module will attempt to load the rtpproxy sets from the specified
    database and will ignore any 'rtpproxy_sock' modparams.
9a0e5866
 
    Default is empty, a database will not be used.
 
    Example 1.9. Set db_url parameter
 ...
 modparam("rtpproxy", "db_url", "mysql://user:passwb@localhost/database")
 ...
 
 4.10. table_name (string)
 
    The name of the table containing the rtpproxy sets.
 
9cb2a163
    Default value is “rtpproxy”.
9a0e5866
 
    Example 1.10. Set table_name parameter
 ...
 modparam("rtpproxy", "table_name", "my_rtpp_sets")
 ...
 
221cdf84
 4.11. rtp_inst_pvar (string)
146e2b09
 
7a78bdff
    A pseudo variable to store the chosen RTPProxy address. If this
    parameter is set, the instance URL will be stored in the given
37e8d647
    variable.
146e2b09
 
    By default, this parameter is not set.
 
221cdf84
    Example 1.11. Set rtp_inst_pvar parameter
146e2b09
 ...
221cdf84
 modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
37e8d647
 ...
 
    Example 1.12. rtp_inst_pvar usage
 modparam("rtpproxy", "rtpproxy_sock",
         "udp:localhost:12221 udp:localhost:12222")
 modparam("rtpproxy", "rtp_inst_pvar", "$var(RTP_INSTANCE)")
 ...
 rtpproxy_manage("eiro");
 xlog("L_INFO", "Chose rtpp instance $var(RTP_INSTANCE)\n");
 # This will display 'udp:localhost:12222'
146e2b09
 ...
 
4bdd3b99
 5. Functions
cef5d23c
 
7a78bdff
    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. rtpproxy_stream2uac(prompt_name, count),
    5.8. rtpproxy_stream2uas(prompt_name, count)
    5.9. rtpproxy_stop_stream2uac(),
5508e6d6
    5.10. rtpproxy_stop_stream2uas()
    5.11. start_recording()
7a78bdff
 
9cb2a163
 5.1.  set_rtp_proxy_set(setid)
7a78bdff
 
    Sets the Id of the rtpproxy set to be used for the next
    unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
a4e2c43c
    rtpproxy_manage() command. The parameter can be an integer or a config
    variable holding an integer.
cef5d23c
 
7a78bdff
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
cef5d23c
    BRANCH_ROUTE.
 
37e8d647
    Example 1.13. set_rtp_proxy_set usage
cef5d23c
 ...
 set_rtp_proxy_set("2");
bf155292
 rtpproxy_offer();
cef5d23c
 ...
 
9cb2a163
 5.2.  rtpproxy_offer([flags [, ip_address]])
cef5d23c
 
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
7a78bdff
    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.
cef5d23c
 
    Meaning of the parameters is as follows:
      * flags - flags to turn on some features.
7a78bdff
           + 1 - append first Via branch to Call-ID when sending command to
             rtpproxy. This can be used to create one media session per
9cb2a163
             branch on the rtpproxy. When sending a subsequent “delete”
7a78bdff
             command to the rtpproxy, you can then stop just the session
4bdd3b99
             for a specific branch when passing the flag '1' or '2' in the
9cb2a163
             “unforce_rtpproxy”, or stop all sessions for a call when not
7a78bdff
             passing one of those two flags there. This is especially
             useful if you have serially forked call scenarios where
9cb2a163
             rtpproxy gets an “update” command for a new branch, and then a
             “delete” command for the previous branch, which would
7a78bdff
             otherwise delete the full call, breaking the subsequent
9cb2a163
             “lookup” for the new branch. This flag is only supported by
483c26b8
             the ngcp-mediaproxy-ng rtpproxy (now named rtpengine) at the
             moment!
7a78bdff
           + 2 - append second Via branch to Call-ID when sending command
4bdd3b99
             to rtpproxy. See flag '1' for its meaning.
7a78bdff
           + 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
cef5d23c
             support symmetric RTP. (automatically sets the 'r' flag)
7a78bdff
           + 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,
8868e624
             but is useful when forking to multiple destinations on
7a78bdff
             different address families or network segments, requiring
             different rtpproxy parameters. The variable value is taken
9cb2a163
             from the “extra_id_pv”. When used, it must be used in every
7a78bdff
             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.
9cb2a163
           + l - force “lookup”, that is, only rewrite SDP when
7a78bdff
             corresponding session already exists in the RTP proxy. By
bf155292
             default is on when the session is to be completed.
7a78bdff
           + 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.
c28450c0
             Note: As rtpproxy in bridge mode is asymmetric per default,
             you have to specify the 'w' flag for clients behind NAT! See
             also above notes!
7a78bdff
           + x - this flag a shortcut for using the "ie" or "ei"-flags of
             RTP-Proxy, in order to do automatic bridging between IPv4 on
             the "internal network" and IPv6 on the "external network". The
             distinction is done by the given IP in the SDP, e.g. a IPv4
             Address will always call "ie" to the RTPProxy (IPv4(i) to
             IPv6(e)) and an IPv6Address will always call "ei" to the
5b597906
             RTPProxy (IPv6(e) to IPv4(i)).
7a78bdff
             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
1cfa90d1
             together.
7a78bdff
           + 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
1cfa90d1
             proxies.
7a78bdff
           + 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
cef5d23c
             also changed.
7a78bdff
           + c - flags to change the session-level SDP connection (c=) IP
cef5d23c
             if media-description also includes connection information.
7a78bdff
           + w - flags that for the UA from which message is received,
cef5d23c
             support symmetric RTP must be forced.
7a78bdff
           + 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
8868e624
             could be used for significantly reducing bandwidth overhead
             for low bitrate codecs, for example with G.729 going from 10ms
             to 100ms saves two thirds of the network bandwidth.
cef5d23c
      * ip_address - new SDP IP address.
 
96db2732
    This function can be used from ANY_ROUTE.
cef5d23c
 
37e8d647
    Example 1.14. rtpproxy_offer usage
cef5d23c
 route {
 ...
     if (is_method("INVITE")) {
aa15067b
         if (has_body("application/sdp")) {
cef5d23c
             if (rtpproxy_offer())
                 t_on_reply("1");
         } else {
             t_on_reply("2");
         }
     }
aa15067b
     if (is_method("ACK") && has_body("application/sdp"))
cef5d23c
         rtpproxy_answer();
 ...
 }
 
 onreply_route[1]
 {
 ...
aa15067b
     if (has_body("application/sdp"))
cef5d23c
         rtpproxy_answer();
 ...
 }
 
 onreply_route[2]
 {
 ...
aa15067b
     if (has_body("application/sdp"))
cef5d23c
         rtpproxy_offer();
 ...
 }
 
9cb2a163
 5.3.  rtpproxy_answer([flags [, ip_address]])
cef5d23c
 
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
7a78bdff
    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.
cef5d23c
 
7a78bdff
    See rtpproxy_answer() function description above for the meaning of the
    parameters.
cef5d23c
 
7a78bdff
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
cef5d23c
    FAILURE_ROUTE, BRANCH_ROUTE.
 
37e8d647
    Example 1.15. rtpproxy_answer usage
cef5d23c
 
    See rtpproxy_offer() function example above for example.
 
9cb2a163
 5.4.  rtpproxy_destroy([flags])
cef5d23c
 
    Tears down the RTPProxy session for the current call.
 
41df4971
    This function can be used from ANY_ROUTE.
cef5d23c
 
4bdd3b99
    Meaning of the parameters is as follows:
      * flags - flags to turn on some features.
7a78bdff
           + 1 - append first Via branch to Call-ID when sending command to
             rtpproxy. This can be used to create one media session per
9cb2a163
             branch on the rtpproxy. When sending a subsequent “delete”
7a78bdff
             command to the rtpproxy, you can then stop just the session
4bdd3b99
             for a specific branch when passing the flag '1' or '2' in the
9cb2a163
             “unforce_rtpproxy”, or stop all sessions for a call when not
7a78bdff
             passing one of those two flags there. This is especially
             useful if you have serially forked call scenarios where
9cb2a163
             rtpproxy gets an “update” command for a new branch, and then a
             “delete” command for the previous branch, which would
7a78bdff
             otherwise delete the full call, breaking the subsequent
9cb2a163
             “lookup” for the new branch. This flag is only supported by
483c26b8
             the ngcp-mediaproxy-ng rtpproxy (now named rtpengine) at the
             moment!
7a78bdff
           + 2 - append second Via branch to Call-ID when sending command
4bdd3b99
             to rtpproxy. See flag '1' for its meaning.
7a78bdff
           + b - append branch specific variable to Call-ID when sending
             command to rtpproxy. See rtpproxy_offer() for details.
49362355
           + t - do not include To tag to “delete” command to rtpproxy thus
7a78bdff
             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.
4bdd3b99
 
37e8d647
    Example 1.16. rtpproxy_destroy usage
cef5d23c
 ...
41df4971
 rtpproxy_destroy();
cef5d23c
 ...
 
9cb2a163
 5.5.  unforce_rtp_proxy()
41df4971
 
    Same as rtpproxy_destroy().
 
9cb2a163
 5.6.  rtpproxy_manage([flags [, ip_address]])
96db2732
 
7a78bdff
    Manage the RTPProxy session - it combines the functionality of
    rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
222166ef
    internally based on message type and method which one to execute.
96db2732
 
7a78bdff
    It can take the same parameters as rtpproxy_offer(). The flags
    parameter to rtpproxy_manage() can be a configuration variable
222166ef
    containing the flags as a string.
1cfa90d1
 
    Functionality:
      * If INVITE with SDP, then do rtpproxy_offer()
      * If INVITE with SDP, when the tm module is loaded, mark transaction
7a78bdff
        with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
        rtpproxy_answer()
1cfa90d1
      * If ACK with SDP, then do rtpproxy_answer()
650087d6
      * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
        unforce_rtpproxy(). Be careful with calling this function after
        resuming a suspended transaction (e.g., after t_continue()),
        because the context of executed route is FAILURE ROUTE (in other
        words, rtpproxy_manage() in the route block of t_continue() does
        the same as in failure_route).
1cfa90d1
      * If reply to INVITE with code >= 300 do unforce_rtpproxy()
7a78bdff
      * 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,
1cfa90d1
        otherwise do rtpproxy_offer()
96db2732
 
    This function can be used from ANY_ROUTE.
 
37e8d647
    Example 1.17. rtpproxy_manage usage
96db2732
 ...
 rtpproxy_manage();
 ...
 
9cb2a163
 5.7.  rtpproxy_stream2uac(prompt_name, count),
cef5d23c
 
7a78bdff
    Instruct the RTPproxy to stream prompt/announcement pre-encoded with
cef5d23c
    the makeann command from the RTPproxy distribution. The uac/uas suffix
7a78bdff
    selects who will hear the announcement relatively to the current
cef5d23c
    transaction - UAC or UAS. For example invoking the rtpproxy_stream2uac
7a78bdff
    in the request processing block on ACK transaction will play the prompt
    to the UA that has generated original INVITE and ACK while
    rtpproxy_stop_stream2uas on 183 in reply processing block will play the
    prompt to the UA that has generated 183.
 
    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
cef5d23c
    appropriate rtpproxy_stop_stream2xxx is issued.
 
7a78bdff
    In order to work correctly, these functions require that a session in
1cfa90d1
    the RTPproxy already exists. Also those functions don't alter the SDP,
7a78bdff
    so that they are not a substitute for calling rtpproxy_offer or
1cfa90d1
    rtpproxy_answer.
cef5d23c
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
 
    Meaning of the parameters is as follows:
7a78bdff
      * prompt_name - name of the prompt to stream. Should be either
        absolute pathname or pathname relative to the directory where
cef5d23c
        RTPproxy runs.
7a78bdff
      * count - number of times the prompt should be repeated. A value of
        -1 means that it will be streaming in a loop indefinitely, until
1cfa90d1
        the appropriate rtpproxy_stop_stream2xxx is issued.
cef5d23c
 
37e8d647
    Example 1.18. rtpproxy_stream2xxx usage
cef5d23c
 ...
     if (is_method("INVITE")) {
         rtpproxy_offer();
c28450c0
         if (is_audio_on_hold()) {
cef5d23c
             rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
         } else {
             rtpproxy_stop_stream2uas();
         };
     };
 ...
 
9cb2a163
 5.8.  rtpproxy_stream2uas(prompt_name, count)
9f5e182d
 
    See function rtpproxy_stream2uac(prompt_name, count).
 
9cb2a163
 5.9.  rtpproxy_stop_stream2uac(),
cef5d23c
 
7a78bdff
    Stop streaming of announcement/prompt/MOH started previously by the
    respective rtpproxy_stream2xxx. The uac/uas suffix selects whose
cef5d23c
    announcement relatively to tha current transaction should be stopped -
    UAC or UAS.
 
    These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
 
5508e6d6
 5.10.  rtpproxy_stop_stream2uas()
 
    See function rtpproxy_stop_stream2uac().
 
    Example 1.19. rtpproxy_stop_stream2uas usage
 ...
     if (is_method("INVITE")) {
         rtpproxy_offer();
         if (is_audio_on_hold()) {
             rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
         } else {
             rtpproxy_stop_stream2uas();
         };
     };
 ...
 
 5.11.  start_recording()
cef5d23c
 
7a78bdff
    This function will send a signal to the RTP-Proxy to record the RTP
    stream on the RTP-Proxy. This function is only supported by Sippy
a041479b
    RTPproxy at the moment!
cef5d23c
 
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
 
5508e6d6
    Example 1.20. start_recording usage
cef5d23c
 ...
 start_recording();
 ...
 
4efa4b21
 6. Exported Pseudo Variables
cef5d23c
 
a0b01f77
    6.1. $rtpstat
94c8e2f4
 
a0b01f77
 6.1. $rtpstat
94c8e2f4
 
    Returns the RTP-Statistics from the RTP-Proxy. The RTP-Statistics from
7a78bdff
    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()).
94c8e2f4
 
5508e6d6
    Example 1.21. $rtpstat-Usage
94c8e2f4
 ...
     append_hf("X-RTP-Statistics: $rtpstat\r\n");
 ...
 
c665d73d
 7. RPC Commands
cef5d23c
 
c665d73d
    7.1. rtpproxy.enable
    7.2. rtpproxy.list
4efa4b21
 
c665d73d
 7.1. rtpproxy.enable
cef5d23c
 
7a78bdff
    Enables a rtp proxy if parameter value is greater than 0. Disables it
cef5d23c
    if a zero value is given.
 
7a78bdff
    The first parameter is the rtp proxy url (exactly as defined in the
cef5d23c
    config file).
 
    The second parameter value must be a number in decimal.
 
7a78bdff
    NOTE: if a rtpproxy is defined multiple times (in the same or different
    sets), all of its instances will be enabled/disabled.
cef5d23c
 
5508e6d6
    Example 1.22.  rtpproxy.enable usage
cef5d23c
 ...
c665d73d
 $ kamcmd rtpproxy.enable udp:192.168.2.133:8081 0
cef5d23c
 ...
 
c665d73d
 7.2. rtpproxy.list
cef5d23c
 
7a78bdff
    Displays all the rtp proxies and their information: set and status
cef5d23c
    (disabled or not, weight and recheck_ticks).
 
    No parameter.
 
5508e6d6
    Example 1.23.  rtpproxy.list usage
cef5d23c
 ...
c665d73d
 $ kamcmd rtpproxy.list
cef5d23c
 ...
 
 Chapter 2. Frequently Asked Questions
 
ced3cb8a
    2.1. What happened with “rtpproxy_disable” parameter?
4efa4b21
    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?
 
cef5d23c
    2.1.
 
ced3cb8a
        What happened with “rtpproxy_disable” parameter?
cef5d23c
 
9cb2a163
        It was removed as it became obsolete - now “rtpproxy_sock” can take
        empty value to disable the rtpproxy functionality.
cef5d23c
 
    2.2.
 
9cb2a163
        Where can I find more about Kamailio?
cef5d23c
 
ff1bcdb4
        Take a look at https://www.kamailio.org/.
cef5d23c
 
    2.3.
 
9cb2a163
        Where can I post a question about this module?
cef5d23c
 
9cb2a163
        First at all check if your question was already answered on one of our
        mailing lists:
          * User Mailing List -
ff1bcdb4
            https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
9cb2a163
          * Developer Mailing List -
ff1bcdb4
            https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
cef5d23c
 
9cb2a163
        E-mails regarding any stable Kamailio release should be sent to
ff1bcdb4
        <sr-users@lists.kamailio.org> and e-mails regarding development
        versions should be sent to <sr-dev@lists.kamailio.org>.
cef5d23c
 
    2.4.
 
9cb2a163
        How can I report a bug?
cef5d23c
 
9cb2a163
        Please follow the guidelines provided at:
        https://github.com/kamailio/kamailio/issues.