src/modules/rtpproxy/doc/rtpproxy_admin.xml
cef5d23c
 <?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 -->
6deb5fcf
 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
cef5d23c
 %docentities;
 
 ]>
 
 <!-- Module User's Guide -->
 
 <chapter>
daa89b4e
 
cef5d23c
 	<title>&adminguide;</title>
daa89b4e
 
cef5d23c
 	<section>
 	<title>Overview</title>
 	<para>
03d5fa36
 		This is a module that enables media streams to be proxied
a041479b
 		via an rtpproxy.  Rtpproxies know to work with this module
 		are Sippy RTPproxy <ulink url="http://www.rtpproxy.org"></ulink>
daa89b4e
 		and ngcp-rtpproxy-ng
1cfa90d1
 		<ulink url="http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng"></ulink>.
 		Some features of the rtpproxy module apply only to one of the two rtpproxies.
cef5d23c
 	</para>
 	</section>
 
 	<section>
 	<title>Multiple RTPProxy usage</title>
 	<para>
1cfa90d1
 		The rtpproxy module can support multiple rtpproxies for
cef5d23c
 		balancing/distribution and control/selection purposes.
 	</para>
 	<para>
1cfa90d1
 		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
1cfa90d1
 		its id - the id being defined with the set. Refer to the
cef5d23c
 		<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>
5004a60a
 		The selection of the set is done from script prior using
bf155292
 		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
cef5d23c
 		functions - see the set_rtp_proxy_set() function.
 	</para>
 	<para>
5004a60a
 		For backward compatibility reasons, a set with no id take by default
 		the id 0. Also if no set is explicitly set before
bf155292
 		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
cef5d23c
 		the 0 id set will be used.
 	</para>
 	<para>
 		IMPORTANT: if you use multiple sets, take care and use the same set for
bf155292
 		both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
cef5d23c
 	</para>
 	</section>
 
 	<section>
 	<title>Dependencies</title>
 	<section>
 		<title>&kamailio; Modules</title>
 		<para>
 		The following modules must be loaded before this module:
 			<itemizedlist>
 			<listitem>
 			<para>
96db2732
 				<emphasis>tm module</emphasis> - (optional) if you want to
 				have rtpproxy_manage() fully functional
cef5d23c
 			</para>
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
 	<section>
 		<title>External Libraries or Applications</title>
 		<para>
5004a60a
 		The following libraries or applications must be installed before
cef5d23c
 		running &kamailio; with this module loaded:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>None</emphasis>.
 			</para>
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
 	</section>
 
 	<section>
9114eebc
 	<title>Parameters</title>
daa89b4e
 	<section id="rtpproxy.p.rtpproxy_sock">
cef5d23c
 		<title><varname>rtpproxy_sock</varname> (string)</title>
 		<para>
9a0e5866
 		Used to define the list of RTPPRoxy instances to connect to.
 		These can 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 set ID '0' will be used. To define multiple sets add the set number at 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 of 1.
cef5d23c
 		</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
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")
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.rtpproxy_disable_tout">
cef5d23c
 		<title><varname>rtpproxy_disable_tout</varname> (integer)</title>
 		<para>
1cfa90d1
 		Once RTPProxy was found unreachable and marked as disabled, the rtpproxy
 		module will not attempt to establish communication to RTPProxy for
cef5d23c
 		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">
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_disable_tout", 20)
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.rtpproxy_tout">
cef5d23c
 		<title><varname>rtpproxy_tout</varname> (integer)</title>
 		<para>
 		Timeout value in waiting for reply from RTPProxy.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>1</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>rtpproxy_tout</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_tout", 2)
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.rtpproxy_retr">
cef5d23c
 		<title><varname>rtpproxy_retr</varname> (integer)</title>
 		<para>
1cfa90d1
 		How many times the module should retry to send and receive after
cef5d23c
 		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">
 ...
03d5fa36
 modparam("rtpproxy", "rtpproxy_retr", 2)
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.nortpproxy_str">
cef5d23c
 		<title><varname>nortpproxy_str</varname> (string)</title>
 		<para>
1cfa90d1
 		This parameter sets the SDP attribute used by rtpproxy to mark
daa89b4e
 		the message's SDP attachemnt with information that it have
1cfa90d1
 		already been changed.
cef5d23c
 		</para>
 		<para>
 		If empty string, no marker will be added or checked.
 		</para>
 		<note><para>
 		The string must be a complete SDP line, including the EOH (\r\n).
 		</para></note>
 		<para>
 		<emphasis>
 			Default value is <quote>a=nortpproxy:yes\r\n</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>nortpproxy_str</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
03d5fa36
 modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.timeout_socket">
ac84acd5
 		<title><varname>timeout_socket</varname> (string)</title>
 		<para>
1cfa90d1
 		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.
ac84acd5
 		</para>
 		<para>
 		If it is an empty string, no timeout socket will be transmitted to the RTP-Proxy.
 		</para>
 		<para>
 		<emphasis>
e5552b2b
 			Default value is <quote></quote> (nothing).
ac84acd5
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>timeout_socket</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
9a0e5866
 modparam("rtpproxy", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
ac84acd5
 ...
75fde552
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.ice_candidate_priority_avp">
75fde552
 		<title><varname>ice_candidate_priority_avp</varname> (string)</title>
 		<para>
 		If specified and if value of the avp value is not 0,
 		<function>rtpproxy_manage</function> function adds
 		ICE relay candidate attributes
 		to sdp stream(s) containing ICE candidate attributes.
 		</para>
 		<para>
 		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.
 		</para>
 		<para>
 		<emphasis>
 		There is no default value meaning that no ICE relay
 		candidates are added in any circumstance.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>ice_candidate_priority_avp</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("rtpproxy", "ice_candidate_priority_avp", "$avp(ice_priority)")
 ...
a2d09db9
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.extra_id_pv">
a2d09db9
 		<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", "extra_id_pv", "$avp(extra_id)")
 ...
9a0e5866
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.db_url">
9a0e5866
 		<title><varname>db_url</varname> (string)</title>
 		<para>
 			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.
 		</para>
 		<para>
 			Default is empty, a database will not be used.
 		</para>
 		<example>
 		<title>Set <varname>db_url</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("rtpproxy", "db_url", "mysql://user:passwb@localhost/database")
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.table_name">
9a0e5866
 		<title><varname>table_name</varname> (string)</title>
 		<para>
 			The name of the table containing the rtpproxy sets.
 		</para>
 		<para>
 			Default value is <quote>rtpproxy</quote>.
 		</para>
 		<example>
 		<title>Set <varname>table_name</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("rtpproxy", "table_name", "my_rtpp_sets")
 ...
146e2b09
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.p.rtp_inst_pvar">
221cdf84
 		<title><varname>rtp_inst_pvar</varname> (string)</title>
146e2b09
 		<para>
37e8d647
 			A pseudo variable to store the chosen RTPProxy address.
 			If this parameter is set, the instance URL will be stored in the given variable.
146e2b09
 		</para>
 		<para>
 			By default, this parameter is not set.
 		</para>
 		<example>
221cdf84
 		<title>Set <varname>rtp_inst_pvar</varname> parameter</title>
146e2b09
 		<programlisting format="linespecific">
 ...
221cdf84
 modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
146e2b09
 ...
37e8d647
 </programlisting>
 		</example>
 		<example>
 		<title><varname>rtp_inst_pvar</varname> usage</title>
 		<programlisting format="linespecific">
 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'
 ...
ac84acd5
 </programlisting>
 		</example>
 	</section>
 	</section>
cef5d23c
 
 	<section>
9114eebc
 	<title>Functions</title>
daa89b4e
 	<section id="rtpproxy.f.set_rtp_proxy_set">
cef5d23c
 		<title>
a4e2c43c
 		<function moreinfo="none">set_rtp_proxy_set(setid)</function>
cef5d23c
 		</title>
 		<para>
5004a60a
 		Sets the Id of the rtpproxy set to be used for the next
a4e2c43c
 		unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer()
 		or rtpproxy_manage() command. The parameter can be an integer or
 		a config variable holding an integer.
cef5d23c
 		</para>
 		<para>
5004a60a
 		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
cef5d23c
 		BRANCH_ROUTE.
 		</para>
 		<example>
1cfa90d1
 		<title><function>set_rtp_proxy_set</function> usage</title>
cef5d23c
 		<programlisting format="linespecific">
 ...
 set_rtp_proxy_set("2");
bf155292
 rtpproxy_offer();
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
         <section id="rtpproxy.f.rtpproxy_ofrer">
bf155292
                 <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>
cef5d23c
 		<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>
c4ea4250
 				<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
daa89b4e
 				gets an <quote>update</quote> command for a new branch, and then a
c4ea4250
 				<quote>delete</quote> command for the previous branch, which would otherwise
 				delete the full call, breaking the subsequent <quote>lookup</quote> for the
daa89b4e
 				new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
 				rtpproxy (now named rtpengine) at the moment!</emphasis>
c4ea4250
 				</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>
63d57773
 				<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>
cef5d23c
 				<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>
a2d09db9
 				<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>
cef5d23c
 				<emphasis>l</emphasis> - force <quote>lookup</quote>, that is,
1cfa90d1
 				only rewrite SDP when corresponding session already exists
cef5d23c
 				in the RTP proxy. By default is on when the session is to be
bf155292
 				completed.
cef5d23c
 				</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>
8bd3b8ff
 				Note: As rtpproxy in bridge mode is asymmetric per default, you have to specify
cef5d23c
 				the 'w' flag for clients behind NAT! See also above notes!
 				</para></listitem>
 				<listitem><para>
5b6f68ae
 				<emphasis>x</emphasis> - this flag a shortcut for using the "ie" or "ei"-flags of RTP-Proxy,
 				in order to do automatic bridging between IPv4 on the
2750e03d
 				"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 RTPProxy (IPv6(e)
 				to IPv4(i)).
5b6f68ae
 				</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.
2750e03d
 				</para></listitem>
 				<listitem><para>
5004a60a
 				<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
1cfa90d1
 				a chain of proxies.
cef5d23c
 				</para></listitem>
 				<listitem><para>
5004a60a
 				<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
cef5d23c
 				address which is passed to the RTP proxy.
 				</para></listitem>
 				<listitem><para>
5004a60a
 				<emphasis>o</emphasis> - flags that IP from the origin
cef5d23c
 				description (o=) should be also changed.
 				</para></listitem>
 				<listitem><para>
5004a60a
 				<emphasis>c</emphasis> - flags to change the session-level
 				SDP connection (c=) IP if media-description also includes
cef5d23c
 				connection information.
 				</para></listitem>
 				<listitem><para>
5004a60a
 				<emphasis>w</emphasis> - flags that for the UA from which
cef5d23c
 				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>
 			</itemizedlist>
 		</listitem>
 		<listitem><para>
 		<emphasis>ip_address</emphasis> - new SDP IP address.
 		</para></listitem>
 		</itemizedlist>
 		<para>
96db2732
 		This function can be used from ANY_ROUTE.
cef5d23c
                 </para>
 		<example>
 		<title><function>rtpproxy_offer</function> usage</title>
 		<programlisting format="linespecific">
 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") &amp;&amp; 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();
 ...
 }
 </programlisting>
                 </example>
 	</section>
daa89b4e
         <section id="rtpproxy.f.rtpproxy_answer">
cef5d23c
                 <title>
                 <function moreinfo="none">rtpproxy_answer([flags [, ip_address]])</function>
                 </title>
 		<para>
 		Rewrites &sdp; body to ensure that media is passed through
bf155292
 		an &rtp; proxy. To be invoked
cef5d23c
 		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>
bf155292
 		See rtpproxy_answer() function description above for the meaning of the
cef5d23c
 		parameters.
 		</para>
 		<para>
 		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
 		FAILURE_ROUTE, BRANCH_ROUTE.
 		</para>
 		<example>
bf155292
 		 <title><function>rtpproxy_answer</function> usage</title>
cef5d23c
 		<para>
 		See rtpproxy_offer() function example above for example.
 		</para>
 		</example>
         </section>
daa89b4e
 	<section id="rtpproxy.f.rtpproxy_destroy">
cef5d23c
 		<title>
c4ea4250
 		<function moreinfo="none">rtpproxy_destroy([flags])</function>
cef5d23c
 		</title>
 		<para>
 		Tears down the RTPProxy session for the current call.
 		</para>
 		<para>
41df4971
 		This function can be used from ANY_ROUTE.
cef5d23c
 		</para>
c4ea4250
 		<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
daa89b4e
 				gets an <quote>update</quote> command for a new branch, and then a
c4ea4250
 				<quote>delete</quote> command for the previous branch, which would otherwise
 				delete the full call, breaking the subsequent <quote>lookup</quote> for the
daa89b4e
 				new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
 				rtpproxy (now named rtpengine) at the moment!</emphasis>
c4ea4250
 				</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>
d8d80082
 				<listitem><para>
a2d09db9
 				<emphasis>b</emphasis> - append branch specific variable to Call-ID when sending
 				command to rtpproxy. See rtpproxy_offer() for details.
 				<listitem><para>
 				</para></listitem>
d8d80082
 				<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>
c4ea4250
 			</itemizedlist>
 		</listitem>
 		</itemizedlist>
cef5d23c
 		<example>
41df4971
 		<title><function>rtpproxy_destroy</function> usage</title>
cef5d23c
 		<programlisting format="linespecific">
 ...
41df4971
 rtpproxy_destroy();
cef5d23c
 ...
 </programlisting>
 		</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.f.unforce_rtp_proxy">
41df4971
 		<title>
 		<function moreinfo="none">unforce_rtp_proxy()</function>
 		</title>
 		<para>
 			Same as rtpproxy_destroy().
 		</para>
 	</section>
96db2732
 
daa89b4e
     <section id="rtpproxy.f.rtpproxy_manage">
96db2732
         <title>
         <function moreinfo="none">rtpproxy_manage([flags [, ip_address]])</function>
         </title>
 		<para>
 		Manage the RTPProxy session - it combines the functionality of
1cfa90d1
 		rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
222166ef
 		internally based on message type and method which one to execute.
96db2732
 		</para>
 		<para>
1cfa90d1
 		It can take the same parameters as <function>rtpproxy_offer().</function>
222166ef
 		The flags parameter to rtpproxy_manage() can be a configuration variable
 		containing the flags as a string.
96db2732
 		</para>
 		<para>
1cfa90d1
 		Functionality:
96db2732
 		</para>
 		<itemizedlist>
 		<listitem>
 			<para>
1cfa90d1
 			If INVITE with SDP, then do <function>rtpproxy_offer()</function>
96db2732
 			</para>
 		</listitem>
 		<listitem>
 			<para>
1cfa90d1
 			If INVITE with SDP, when the tm module is loaded, mark transaction with
96db2732
 			internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
1cfa90d1
 			<function>rtpproxy_answer()</function>
96db2732
 			</para>
 		</listitem>
 		<listitem>
 			<para>
1cfa90d1
 			If ACK with SDP, then do <function>rtpproxy_answer()</function>
96db2732
 			</para>
 		</listitem>
 		<listitem>
 			<para>
e128d46e
 			If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
 			<function>unforce_rtpproxy()</function>. 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).
96db2732
 			</para>
 		</listitem>
 		<listitem>
 			<para>
1cfa90d1
 			If reply to INVITE with code >= 300 do <function>unforce_rtpproxy()</function>
96db2732
 			</para>
 		</listitem>
 		<listitem>
 			<para>
1cfa90d1
 			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>
96db2732
 			</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>
 
daa89b4e
 	<section id="rtpproxy.f.rtpproxy_stream2uac">
cef5d23c
 	<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>
1cfa90d1
 	    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>
bf155292
 	    or <function>rtpproxy_answer</function>.
cef5d23c
 	</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
1cfa90d1
 		    stream. Should be either absolute pathname or pathname
cef5d23c
 		    relative to the directory where RTPproxy runs.
 		</para>
 	    </listitem>
 	    <listitem>
 		<para>
 		    <emphasis>count</emphasis> - number of times the prompt
1cfa90d1
 		    should be repeated. A value of -1 means that it will
 		    be streaming in a loop indefinitely, until the appropriate
cef5d23c
 		    <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();
8bd3b8ff
         if (is_audio_on_hold()) {
cef5d23c
             rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
         } else {
             rtpproxy_stop_stream2uas();
         };
     };
 ...
 	    </programlisting>
 	</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.f.rtpproxy_stream2uas">
9f5e182d
 	<title>
 	    <function>rtpproxy_stream2uas(prompt_name, count)</function>
 	</title>
 	<para>
 		See function <function>rtpproxy_stream2uac(prompt_name, count)</function>.
 	</para>
 	</section>
daa89b4e
 	<section id="rtpproxy.f.rtpproxy_stop_stream2uac">
cef5d23c
 	<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>
bfe2cec3
 	<section id="rtpproxy.f.rtpproxy_stop_stream2uas">
 	<title>
 	    <function>rtpproxy_stop_stream2uas()</function>
 	</title>
 	<para>
 		See function <function>rtpproxy_stop_stream2uac()</function>.
 	</para>
 	<example>
 	    <title><function>rtpproxy_stop_stream2uas</function> usage</title>
 	    <programlisting>
 ...
     if (is_method("INVITE")) {
         rtpproxy_offer();
         if (is_audio_on_hold()) {
             rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
         } else {
             rtpproxy_stop_stream2uas();
         };
     };
 ...
 	    </programlisting>
 	</example>
 	</section>
daa89b4e
 	<section id="rtpproxy.f.start_recording">
cef5d23c
 		<title>
 		<function moreinfo="none">start_recording()</function>
 		</title>
 		<para>
a041479b
 		This function will send a signal to the RTP-Proxy to record
daa89b4e
 		the RTP stream on the RTP-Proxy.
1cfa90d1
 		<emphasis>This function is only supported by Sippy RTPproxy at the moment!</emphasis>
cef5d23c
 		</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>
daa89b4e
 		<section id="rtpproxy.pv.rtpstat">
a0b01f77
 			<title><function moreinfo="none">$rtpstat</function></title>
ac84acd5
 			<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
1cfa90d1
 			must be retrieved before the session is deleted	(before <function>unforce_rtpproxy()</function>).
ac84acd5
 			</para>
 
 		<example>
 		<title>$rtpstat-Usage</title>
 		<programlisting format="linespecific">
 ...
     append_hf("X-RTP-Statistics: $rtpstat\r\n");
 ...
 		</programlisting>
 		</example>
 	        </section>
 
cef5d23c
 	</section>
 
 	<section>
9492c748
 		<title>RPC Commands</title>
 		<section id="rtpproxy.r.enable">
 			<title>rtpproxy.enable</title>
cef5d23c
 			<para>
 			Enables a rtp proxy if parameter value is greater than 0.
 			Disables it if a zero value is given.
 			</para>
 			<para>
5004a60a
 			The first parameter is the rtp proxy url (exactly as defined in
cef5d23c
 			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
37e8d647
 			different sets), all of its instances will be enabled/disabled.
cef5d23c
 			</para>
 			<example>
 			<title>
9492c748
 			<function moreinfo="none">rtpproxy.enable</function> usage</title>
cef5d23c
 			<programlisting format="linespecific">
 ...
9492c748
 $ &kamcmd; rtpproxy.enable udp:192.168.2.133:8081 0
cef5d23c
 ...
 			</programlisting>
 			</example>
 		</section>
daa89b4e
 
9492c748
 			<section id="rtpproxy.r.list">
 			<title><function moreinfo="none">rtpproxy.list</function></title>
cef5d23c
 			<para>
5004a60a
 			Displays all the rtp proxies and their information: set and
cef5d23c
 			status (disabled or not, weight and recheck_ticks).
 			</para>
 			<para>
 			No parameter.
 			</para>
 			<example>
 			<title>
9492c748
 				<function moreinfo="none">rtpproxy.list</function> usage</title>
cef5d23c
 			<programlisting format="linespecific">
 ...
9492c748
 $ &kamcmd; rtpproxy.list
cef5d23c
 ...
 			</programlisting>
 			</example>
 		</section>
 	</section>
 
 </chapter>