rtpengine_admin.xml

<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<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 rtpengines.
		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><xref linkend="param_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 rtpengine_use_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 id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; 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 &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section id="param_rtpengine_sock" xreflabel="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="param_rtpengine_disable_tout" xreflabel="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="param_rtpengine_tout" xreflabel="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="param_rtpengine_retr" xreflabel="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="param_extra_id_pv" xreflabel="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="param_setid_avp" xreflabel="setid_avp">
		<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 id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
			Database URL, used to load RTPEngines sockets
			from db, instead of specifying them in the
			script (<xref linkend="param_rtpengine_sock"/>
			module parameter).
		</para>
		<para>
			Default value is <quote>NULL</quote>, no database
			is used.
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("rtpengine", "db_url", 
		"mysql://opensips:opensipsrw@localhost/opensips")
...
</programlisting>
		</example>
	</section>

	<section id="param_db_table" xreflabel="db_table">
		<title><varname>db_table</varname> (string)</title>
		<para>
			The table where the RTPEngines sockets are stored.
			Used when Database URL is provisioned.
		</para>
		<para>
			Default value is <quote>rtpengines</quote>.
		</para>
		<example>
		<title>Set <varname>db_table</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("rtpengine", "db_table", "rtpengine_new")
...
</programlisting>
		</example>
	</section>

	<section id="param_socket_column" xreflabel="socket_column">
		<title><varname>socket_column</varname> (string)</title>
		<para>
			The name of the rtpengine socket column in the database table.
		</para>
		<para>
			Default value is <quote>socket</quote>.
		</para>
		<example>
		<title>Set <varname>socket_column</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("rtpengine", "socket_column", "sock")
...
</programlisting>
		</example>
	</section>

	<section id="param_set_column" xreflabel="set_column">
		<title><varname>set_column</varname> (string)</title>
		<para>
			The name of the rtpengine set column in the database table.
		</para>
		<para>
			Default value is <quote>set_id</quote>.
		</para>
		<example>
		<title>Set <varname>set_column</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("rtpengine", "set_column", "set_new")
...
</programlisting>
		</example>
	</section>

	</section>

	<section>
	<title>Exported Functions</title>
	<section id="func_rtpengine_use_set" xreflabel="rtpengine_use_set()">
		<title>
		<function moreinfo="none">rtpengine_use_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 is an integer.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>rtpengine_use_set</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_use_set(2);
rtpengine_offer();
...
</programlisting>
		</example>
	</section>
		<section id="func_rtpengine_offer" xreflabel="rtpengine_offer()">
                <title>
                <function moreinfo="none">rtpengine_offer([flags[, sock_var[, sdp_pvar[, body]]]])</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(string, optional)</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>
			<para> When passing an option that &osips; is not aware of, it will be
			blindly sent to the rtpengine daemon to be processed.</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><xref linkend="param_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>in-iface=..., out-iface=...</emphasis> - these flags specify the direction
				the SIP message. These flags only make sense when the &rtp; proxy is running
				in bridge mode. <quote>in-iface</quote> should indicate the proxy's inbound
				interface, and <quote>out-iface</quote> corresponds to the &rtp; proxy's
				outbound interface. You always have to specify two flags to define
				the incoming network and the outgoing network. For example,
				<quote>in-iface=internal out-iface=external</quote> should be
				used for SIP message received from the local interface and sent out on the
				external interface.
				</para></listitem>
				<listitem><para>
				<emphasis>internal, external</emphasis> - these the old flags used to
				specify the direction of call. They are now obsolate, being replaced by the
				<quote>in-iface=internal out-iface=external</quote> configuration.
				</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>loop-protect</emphasis> - flag that instructs &rtp; to
				avoid rewriting the SDP when looping the same message.
				</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>to-tag=...</emphasis> - use the specified string as <quote>To</quote>
				tag instead of the actual <quote>To</quote> tag from the &sip; message, and
				force inclusion of the tag in the message as per above.
				</para></listitem>
				<listitem><para>
				<emphasis>from-tag=...</emphasis> - use the specified string as
				<quote>From</quote> tag instead of the actual <quote>From</quote>
				tag from the &sip; message.
				</para></listitem>
				<listitem><para>
				<emphasis>call-id=...</emphasis> - use the specified string as
				<quote>Call-ID</quote> instead of the actual <quote>Call-ID</quote>
				from the &sip; message.
				</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-require</emphasis> - Similar to offer but pretends that
				the client has accepted rtcp-mux. This breaks RFC 5761 and will not advertise
				seperate RTCP ports. This option is necessary for WebRTC clients.
				</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>
				<listitem><para>
				<emphasis>record-call=yes/no</emphasis> - indicates whether rtpengine should
				record the call or not. When using this parameter, you may pass further
				information in the <quote>metadata</quote>.
				</para></listitem>
				<listitem><para>
				<emphasis>transcode-CODEC</emphasis> - used only for offer, indicates that
				rtpengine should transcode the CODEC towards the B-side. Example:
				<emphasis>transcode-PCMA</emphasis> will present to the B-side the PCMA codec.
				</para></listitem>
				<listitem><para>
				<emphasis>codec-strip-CODEC</emphasis> - used only for offer, indicates that
				the A-side of the call will not end up talking CODEC. Example:
				<emphasis>codec-strip-PCMA</emphasis> will prevent the A-side from receiving
				the PCMA codec.
				</para></listitem>
				<listitem><para>
				<emphasis>codec-mask-CODEC</emphasis> - used only for offer, indicates that
				the A-side will use the CODEC, but it will not be presented to the B-side. Example:
				<emphasis>codec-mask-PCMA</emphasis> will make the A-side receive the PCMA codec,
				but B-side will use something else.
				</para></listitem>
			</itemizedlist>
		</listitem>
		<listitem><para>
		<emphasis>sock_var(var, optional)</emphasis> - variable used to store the rtpengine
		socket chosen for this call.
		</para></listitem>
		<listitem><para>
		<emphasis>sdp_var(var, optional)</emphasis> - variable used to store the full SDP
		received from rtpengine. You can perform any additional changes on this
		string. <emphasis>Important: </emphasis> when providing this variable, the
		message body is no longer changed, so you have to manually replace it!.
		</para></listitem>
		<listitem><para>
		<emphasis>body(string, optional)</emphasis> - used to provide a specific body
		to the rtpengine_* function. If this parameter is missing the body of
		the current message is used.
		</para></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>
		<example>
		<title><function>rtpengine_offer</function> usage with body replace</title>
		<programlisting format="linespecific">
...
if (rtpengine_offer(, $var(socket), $var(body), $rb)) {
    xlog("Used rtpengine $var(socket)\n");
    # make all the changes on the resulted SDP in $var(body)
    ...
    remove_body_part();
    add_body_part($var(body), "application/sdp");
}
...
</programlisting>
                </example>
		<example>
		<title><function>rtpengine_offer</function> usage with call recording</title>
		<programlisting format="linespecific">
...
$var(rtpengine_flags) = $var(rtpengine_flags) + " record-call=yes";

$json(recording_keys) := "{}";
$json(recording_keys/callId) = $ci;
$json(recording_keys/fromUser) = $dlg_val(recording_from_user);
$json(recording_keys/fromDomain) = $dlg_val(recording_from_domain);
$json(recording_keys/fromTag) = $dlg_val(recording_from_tag);
$json(recording_keys/toUser) = $dlg_val(recording_to_user);
$json(recording_keys/toDomain) = $dlg_val(recording_to_domain);

$var(rtpengine_flags) = $var(rtpengine_flags) + " metadata=" + $(json(recording_keys){s.encode.hexa});
rtpengine_offer($var(rtpengine_flags));
...
</programlisting>
                </example>
		<example>
		<title><function>rtpengine_offer</function> usage for transcoding</title>
		<programlisting format="linespecific">
...
# Goal: make A-side talk PCMA and B-side talk opus
# * do not present PCMA to B-side: codec-mask-PCMA, but use it on A-side
# * do not use opus for A-side: codec-strip-opus
# * offer opus to B-side: transcode-opus
rtpengine_offer("... codec-mask-PCMA codec-strip-opus transcode-opus ...");
...
</programlisting>
                </example>

	</section>
		<section id="func_rtpengine_answer" xreflabel="rtpengine_answer()">
                <title>
                <function moreinfo="none">rtpengine_answer([flags[, sock_pvar[, sdp_pvar[, body]]]])</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 examples.
		</para>
		</example>
        </section>
	<section id="func_rtpengine_delete" xreflabel="rtpengine_delete()">
		<title>
		<function moreinfo="none">rtpengine_delete([flags[, sock_var]])</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="func_rtpengine_manage" xreflabel="rtpengine_manage()">
        <title>
        <function moreinfo="none">rtpengine_manage([flags[, sock_var[, sdp_var[, body]]]])</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="func_rtpengine_start_recording" xreflabel="rtpengine_start_recording()">
		<title>
		<function moreinfo="none">rtpengine_start_recording([flags [, sock_var]])</function>
		</title>
		<para>
		This function will send a signal to the &rtp; proxy to record
		the RTP stream on the &rtp; proxy.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem><para>
		<emphasis>flags(string, optional)</emphasis> - flags used to change the behavior
		of the recorder. An importat value to set is the <emphasis>call-id</emphasis>
		value, which can be used to start recording a different call than the requested one.
		</para></listitem>
		<listitem><para>
		<emphasis>sock_var(var, optional)</emphasis> - variable used to store the rtpengine
		socket chosen for this call.
		</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title><function>rtpengine_start_recording</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_start_recording();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_stop_recording" xreflabel="rtpengine_stop_recording()">
		<title>
		<function moreinfo="none">rtpengine_stop_recording([flags [, sock_var]])</function>
		</title>
		<para>
		This function will send a signal to the &rtp; proxy to stop
		recording the RTP stream on the &rtp; proxy.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem><para>
		<emphasis>flags(string, optional)</emphasis> - flags used to change the behavior
		of the recorder. An importat value to set is the <emphasis>call-id</emphasis>
		value, which can be used to start recording a different call than the requested one.
		</para></listitem>
		<listitem><para>
		<emphasis>sock_var(var, optional)</emphasis> - variable used to store the rtpengine
		socket chosen for this call.
		</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title><function>rtpengine_stop_recording</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_stop_recording();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_play_media" xreflabel="rtpengine_play_media()">
		<title>
		<function moreinfo="none">rtpengine_play_media(flags, [duration_spec[, sock_var[, sockvar]]])</function>
		</title>
		<para>
		This function will start playing a media file to one of the endpoints.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem><para>
		<emphasis>flags(string)</emphasis> - a list of flags simialar to
			the other functions. One of the <emphasis>file</emphasis>,
			<emphasis>blob</emphasis> or <emphasis>db-id</emphasis> parameters
			is mandatory to indicate the content of the media file to be played.
			<emphasis>file</emphasis> is a common choice for specifying rtpengine
			to get media from a file path, <emphasis>blob</emphasis> to take
			the content from an inline string and <emphasis>db-id</emphasis> to
			get the content from the database.
			<para>
			The direction of the media stream is controlled by the
			<emphasis>from-tag</emphasis> parameter, <emphasis>address</emphasis>
			(media address from the SDP), or <emphasis>label</emphasis>, if the
			media stream contains a label. If all of them are missing, the media
			file is played to the initiator of the SIP request, and will work similar
			to a ringback tone.
			</para>
		</para></listitem>
		<listitem><para>
		<emphasis>duration_spec(var, optional)</emphasis> - a pseudo variable that
			will contain the duration of the played file. It will be set to
			<emphasis>-1</emphasis> if the duration could not be determined.
		</para></listitem>
		<listitem><para>
		<emphasis>sock_var(var, optional)</emphasis> - variable used to store the rtpengine
		socket chosen for this call.
		</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Ringback tone using <function>rtpengine_play_media</function></title>
		<programlisting format="linespecific">
...
if (is_method("INVITE") &amp;&amp; !has_totag())
	rtpengine_play_media("file=/path/to/ringback_tone_file.wav");
...
		</programlisting>
		</example>
		<example>
		<title>Manage music on hold using <function>rtpengine_play_media</function></title>
		<programlisting format="linespecific">
...
if (is_method("INVITE") &amp;&amp; has_totag()) {
	if (is_audio_on_hold()) {
		$dlg_val(on_hold) = "1";
		rtpengine_play_media("from-tag=$tt file=/path/to/moh_file.wav");
	} else if ($dlg_val(on_hold) == "1") {
		$dlg_val(on_hold) = "0";
		rtpengine_stop_media("from-tag=$tt");
	}
}
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_stop_media" xreflabel="rtpengine_stop_media()">
		<title>
		<function moreinfo="none">rtpengine_stop_media([flags[, sockvar]])</function>
		</title>
		<para>
			This function will stop playing a media file previously started
			by a <function>rtpengine_play_media()</function> call. The meaning
			of its parameters is similar to the previous functions. Note that this
			function should be called with similar parameters as its matching
			<function>rtpengine_play_media()</function> call, otherwise
			RTPEngine will not be able to stop media playing.
		</para>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Ringback tone stop using <function>rtpengine_stop_media</function></title>
		<programlisting format="linespecific">
...
if (is_method("INVITE") &amp;&amp; $rs == 200)
	rtpengine_stop_media();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_block_media" xreflabel="rtpengine_block_media()">
		<title>
		<function moreinfo="none">rtpengine_stop_media([flags[, sockvar]])</function>
		</title>
		<para>
			This function will block the media sent from one of the endpoints.
			The direction to be blocked is controled by the <emphasis>flags</emphasis>
			parameter, the <emphasis>from-tag</emphasis> value.
		</para>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Example of <function>rtpengine_block_media</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_block_media();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_unblock_media" xreflabel="rtpengine_unblock_media()">
		<title>
		<function moreinfo="none">rtpengine_unstop_media([flags[, sockvar]])</function>
		</title>
		<para>
			This function will resume/unblock the media sent from one of the endpoints.
			The direction to be blocked is controled by the <emphasis>flags</emphasis>
			parameter, the <emphasis>from-tag</emphasis> value.
		</para>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Example of <function>rtpengine_unblock_media</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_unblock_media();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_block_dtmf" xreflabel="rtpengine_block_dtmf()">
		<title>
		<function moreinfo="none">rtpengine_stop_dtmf([flags[, sockvar]])</function>
		</title>
		<para>
			This function will block the DTMF media sent from one of the endpoints.
			The direction to be blocked is controled by the <emphasis>flags</emphasis>
			parameter, the <emphasis>from-tag</emphasis> value.
		</para>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Example of <function>rtpengine_block_dtmf</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_block_dtmf();
...
		</programlisting>
		</example>
	</section>

	<section id="func_rtpengine_unblock_dtmf" xreflabel="rtpengine_unblock_dtmf()">
		<title>
		<function moreinfo="none">rtpengine_unstop_dtmf([flags[, sockvar]])</function>
		</title>
		<para>
			This function will resume/unblock the DTMF media sent from one of the endpoints.
			The direction to be blocked is controled by the <emphasis>flags</emphasis>
			parameter, the <emphasis>from-tag</emphasis> value.
		</para>
		<para>
		This function can be used from any route.
		</para>
		<example>
		<title>Example of <function>rtpengine_unblock_dtmf</function> usage</title>
		<programlisting format="linespecific">
...
rtpengine_unblock_dtmf();
...
		</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_pseudo_variables">
		<title>Exported Pseudo-Variables</title>
		<section id="pv_rtpstat_0" xreflabel="$rtpstat">
			<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.
			</para>

		<example>
		<title>$rtpstat Usage</title>
		<programlisting format="linespecific">
...
    append_hf("X-RTP-Statistics: $rtpstat\r\n");
...
		</programlisting>
		</example>
		</section>
		<section id="pv_rtpstat" xreflabel="$rtpstat">
			<title><function moreinfo="none">$rtpstat(STAT)[index]</function></title>
			<para>
			Returnes one of the pre-fined statistics listed below:
			</para>
			<itemizedlist>
			<listitem><para>
					<emphasis>MOS-average</emphasis> - without an index, it returns the average
					MOS value, expressed in an integer between 0 and 50, of all the RTP streams
					involved in the call, both caller and callee. If index is specified, it has
					to be one of the <emphasis>from-tag</emphasis>
					or <emphasis>to-tag</emphasis> involved in the call. In this case, the variable
					will return the average MOS of all the streams generated by that endpoint
					with the associated tag value. If you need more granular statistics, check
					the <emphasis>$rtpquery</emphasis> variable.
			</para></listitem>
			<listitem><para>
					<emphasis>jitter-average</emphasis> - similar behavior with
					<emphasis>MOS-average</emphasis>, but returnes the average jitter.
			</para></listitem>
			<listitem><para>
					<emphasis>roundtrip-average</emphasis> - similar behavior with
					<emphasis>MOS-average</emphasis>, but returnes the average roundtrip.
			</para></listitem>
			<listitem><para>
					<emphasis>packetloss-average</emphasis> - similar behavior with
					<emphasis>MOS-average</emphasis>, but returnes the average packet loss.
			</para></listitem>
			<listitem><para>
					<emphasis>MOS-min</emphasis> - without an index, it returns the minimum
					MOS value (integer value between 0 and 50) of all RTP streams involved in the
					call, both caller and callee.
					If the index is specified, it has the same effect as for
					<emphasis>MOS-average</emphasis>.
			</para></listitem>
			<listitem><para>
					<emphasis>jitter-min</emphasis> - similar behavior with
					<emphasis>MOS-min</emphasis>, but returnes the minimum jitter of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>roundtrip-min</emphasis> - similar behavior with
					<emphasis>MOS-min</emphasis>, but returnes the minimum roundtrip of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>packetloss-min</emphasis> - similar behavior with
					<emphasis>MOS-min</emphasis>, but returnes the minimum packet loss of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>MOS-max</emphasis> - without an index, it returns the maximum
					MOS value (integer value between 0 and 50) of all RTP streams involved in the
					call, both caller and callee.
					If the index is specified, it has the same effect as for
					<emphasis>MOS-average</emphasis>.
			</para></listitem>
			<listitem><para>
					<emphasis>jitter-max</emphasis> - similar behavior with
					<emphasis>MOS-max</emphasis>, but returnes the maximum jitter of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>roundtrip-max</emphasis> - similar behavior with
					<emphasis>MOS-max</emphasis>, but returnes the maximum roundtrip of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>packetloss-max</emphasis> - similar behavior with
					<emphasis>MOS-max</emphasis>, but returnes the maximum packet loss of a leg/call.
			</para></listitem>
			<listitem><para>
					<emphasis>MOS-min-at</emphasis> - without an index, it returns the time in
					seconds elapsed from the start of the call when the MOS value is minimum.
					If the index is specified, it has the same effect as for
					<emphasis>MOS-average</emphasis>.
			</para></listitem>
			<listitem><para>
					<emphasis>jitter-min-at</emphasis> - similar behavior with
					<emphasis>MOS-min-at</emphasis>, but returnes the time when the minimum
					jitter was detected.
			</para></listitem>
			<listitem><para>
					<emphasis>roundtrip-min-at</emphasis> - similar behavior with
					<emphasis>MOS-min-at</emphasis>, but returnes the time when the minimum
					roundtrip was detected.
			</para></listitem>
			<listitem><para>
					<emphasis>packetloss-min-at</emphasis> - similar behavior with
					<emphasis>MOS-min-at</emphasis>, but returnes the time when the minimum
					packet loss of a leg/call was detected.
			</para></listitem>
			<listitem><para>
					<emphasis>MOS-max-at</emphasis> - without an index, it returns the time in
					seconds elapsed from the start of the call when the MOS value is maximum.
					If the index is specified, it has the same effect as for
					<emphasis>MOS-average</emphasis>.
			</para></listitem>
			<listitem><para>
					<emphasis>jitter-max-at</emphasis> - similar behavior with
					<emphasis>MOS-max-at</emphasis>, but returnes the time when the maximum
					value of jitter was detected.
			</para></listitem>
			<listitem><para>
					<emphasis>roundtrip-max-at</emphasis> - similar behavior with
					<emphasis>MOS-max-at</emphasis>, but returnes the time when the maximum
					value of roundtrip was detected.
			</para></listitem>
			<listitem><para>
					<emphasis>packetloss-min-at</emphasis> - similar behavior with
					<emphasis>MOS-max-at</emphasis>, but returnes the time when the maximum
					packet loss of a leg/call was detected.
			</para></listitem>
			</itemizedlist>

			<para>
				<emphasis>NOTE:</emphasis> all these statistics are computed based on the
				statistics generated by RTPEngine. Some of them might not be available for
				all the calls (i.e. MOS cannot be computed if the call is too short, or if
				the phones do not properly report RTP statistics over RTCP). In these cases
				the variable returns the <emphasis>NULL</emphasis> value.
			</para>
		<example>
		<title>$rtpstat(STAT)</title>
		<programlisting format="linespecific">
...
    xlog("Average MOS of the entire call is $rtpstat(MOS-average)\r\n");
    xlog("Average MOS of caller is $(rtpstat(MOS-average)[$ft])\r\n");
    xlog("Average MOS of callee is $(rtpstat(MOS-average)[$tt])\r\n");
    xlog("Min MOS of caller is $(rtpstat(MOS-min)[$ft]) reported at $(rtpstat(MOS-min-at)[$ft])\r\n");
...
		</programlisting>
		</example>
		</section>
		<section id="pv_rtpquery" xreflabel="$rtpquery">
			<title><function moreinfo="none">$rtpquery</function></title>
			<para>
			Does a Query command to the &rtp; proxy and returns the answer in a JSON format.
			You can use this variable to fetch arbitrary data from the &rtp; proxy such as
			raw statistics about the call, or other indicators.
			</para>
			<para>
			You can use a <emphasis>$json()</emphasis> variable to parse
			its output and extract any information from the query, such as
			RTP statistics, or MOS values.
			</para>

		<example>
		<title>$rtpquery Usage</title>
		<programlisting format="linespecific">
...
	$json(reply) := $rtpquery;
	xlog("Total RTP Stats: $json(reply/totals)\n");
...
		</programlisting>
		</example>
		</section>

	</section>

	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
		<section id="mi_rtpengine_enable" xreflabel="rtpengine_enable">
			<title><function moreinfo="none">rtpengine_enable</function></title>
			<para>
			Enables/disables a &rtp; proxy.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>url</emphasis> - the &rtp; proxy url (exactly as
					defined in the config file).
				</para></listitem>
				<listitem><para>
					<emphasis>enable</emphasis> - 1 - enable, 0 - disable the &rtp; proxy.
				</para></listitem>
			</itemizedlist>
			<para>
			NOTE: if a &rtp; proxy is defined multiple times (in the same or
			different set), all of its instances will be enables/disabled.
			</para>
			<example>
			<title>
			<function moreinfo="none">rtpengine_enable</function> usage</title>
			<programlisting format="linespecific">
...
$ opensips-cli -x mi rtpengine_enable udp:192.168.2.133:8081 0
...
			</programlisting>
			</example>
		</section>

		<section id="mi_rtpengine_show" xreflabel="rtpengine_show">
			<title><function moreinfo="none">rtpengine_show</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">rtpengine_show</function> usage</title>
			<programlisting format="linespecific">
...
$ opensips-cli -x mi rtpengine_show
...
			</programlisting>
			</example>
		</section>

		<section id="mi_rtpengine_reload" xreflabel="rtpengine_reload">
			<title><function moreinfo="none">rtpengine_reload</function></title>
			<para>
			Reloads all rtpengine sets from the database. Used only when the
			<quote><xref linkend="param_db_url"/></quote> parameter is set.
			</para>
			<para>
			No parameter.
			</para>
			<example>
			<title>
				<function moreinfo="none">rtpengine_reload</function> usage</title>
			<programlisting format="linespecific">
...
$ opensips-cli -x mi rtpengine_reload
...
			</programlisting>
			</example>
		</section>

		<section id="mi_teardown" xreflabel="teardown">
			<title><function moreinfo="none">teardown</function></title>
			<para>
			Terminates the SIP dialog by the SIP Call-ID given as parameter.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>callid</emphasis> - SIP Call-ID.
				</para></listitem>
			</itemizedlist>
			<para>
			Note this is a just a wrapper function over the 
			<quote>dlg_end_dlg</quote> MI function provided by the
			<quote>dialog</quote> module. This wrapping is done just to
			make rtpengine happy when trying to terminate SIP calls based on
			RTP timeouts.
			</para>
			<example>
			<title>
				<function moreinfo="none">teardown</function> usage</title>
			<programlisting format="linespecific">
...
$ opensips-cli -x mi teardown Y2IwYjQ2YmE2ZDg5MWVkNDNkZGIwZjAzNGM1ZDY0ZDQ
...
			</programlisting>
			</example>
		</section>



	</section>

</chapter>