<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

<chapter>
	<title>&adminguide;</title>

<section>
	<title>Overview</title>
	<para>
		rtp_media_server module adds RTP and media processing functionalities to Kamailio.
		Kamailio is providing SIP signaling including an endpoint with Dialog state,
		SDP parsing and scripting language.
	</para><para>
		oRTP: is providing Real-time Transport Protocol (RFC 3550)
	</para><para>
		mediastreamer2: is providing mediaprocessing functionnalities using graphs and filters, many modules are available
		to support various features, it should be relatively simple to integrated them.
	</para><para>
		mediastreamer2 is also providing a framework to create custom mediaprocessing modules.
	</para>
</section>

<section>
	<title>Quick start, how-to build on debian</title>
	<section>
		<title>Building on Debian, Dockerfile and docker image</title>
		<para>
		The module includes Dockerfile that can also be used as a reference on how to build everything
		from source on Debian, the package of libmediastreamer on Linux is usually outdated.

		A Docker image is also available from dockerhub
		<ulink url="https://hub.docker.com/r/jchavanton/rtp_media_server">https://hub.docker.com/r/jchavanton/rtp_media_server</ulink>
		</para>
	</section>
</section>

<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The module depends on the following modules (in other words
		the listed modules must be loaded before this module):
		<itemizedlist>
			<listitem>
			<para><emphasis>tm</emphasis> - transaction module</para>
			</listitem>
		</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed
		before running &kamailio; with this module loaded:
		</para><para>
		If you want to build oRTP and mediastreamer from source, you can use the provided script for Debian "install_bc.sh".
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>oRTP</emphasis> git clone <ulink url="git://git.linphone.org/ortp.git">git://git.linphone.org/ortp.git</ulink>
			</para>
			<para>
				oRTP is a library implementing Real-time Transport Protocol (RFC 3550), distributed under GNU GPLv2 or proprietary license.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>mediastreamer2</emphasis> git clone
				<ulink url="git://git.linphone.org/mediastreamer2.git">git://git.linphone.org/mediastreamer2.git</ulink>
			</para>
			<para>
				Mediastreamer2 is a powerful and lightweight streaming engine specialized for voice/video telephony applications.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>bcunit</emphasis> git clone
				<ulink url="https://github.com/BelledonneCommunications/bcunit.git">https://github.com/BelledonneCommunications/bcunit.git</ulink>
			</para>
			<para>
				fork of the defunct project CUnit, with several fixes and patches applied.
				CUnit is a Unit testing framework for C.
			</para>
			</listitem>
		</itemizedlist>
	</section>
</section>

<section>
	<title>Parameters</title>
	<section>
	<title><varname>log_file_name</varname> (string)</title>
		<para>
		oRTP and MediaStreamer2 log file settings
		the log mask is not configurable :
		MESSAGE | WARNING | ERROR | FATAL
		levels are activated.
		</para>
		<para>
		Default value is not-set (no logging to file).
		</para>
		<example>
		<title>log_file_name example</title>
		<programlisting format="linespecific">
...
modparam("rtp_media_server", "log_file_name", "/var/log/rms/rms_ortp.log")
...
		</programlisting></example>
	</section>
</section>

<section>
	<title>Functions</title>

	<section id="rtp_media_server.f.rms_answer">
		<title><varname>rms_answer</varname> (event_route)</title>
		<para>
		Create a call leg with a SIP dialog and an RTP session call the event_route
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, REPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title>rms_answer usage example</title>
		<programlisting format="linespecific">
...
event_route[rms:start] {
	xnotice("[rms:start] play ...\n");
	rms_play("/tmp/reference_8000.wav", "rms:after_play");
};

event_route[rms:after_play] {
	xnotice("[rms:after_play] play done...\n");
	rms_hangup();
};

route {
	if (t_precheck_trans()) {
		t_check_trans();
		exit;
	}
	t_check_trans();
	if (is_method("INVITE") &amp;&amp; !has_totag()) {
		if (!rms_answer("rms:start")) {
			t_reply("503", "server error");
		}
	}
	rms_sip_request();
...
		</programlisting></example>
	</section>

	<section id="rtp_media_server.f.rms_hangup">
		<title><varname>rms_hangup</varname> ()</title>
		<para>
		Send a BYE, delete the RTP session and the media resources.
		</para>
		<para>
		This function can be used from EVENT_ROUTE.
		</para>
		<example>
		<title>rms_hangup usage example</title>
		<programlisting format="linespecific">
...
	rms_hangup();
...
		</programlisting></example>
	</section>

	<section id="rtp_media_server.f.rms_bridge">
		<title><varname>rms_bridge</varname> (target URI, event_route)</title>
		<para>
		Bridge the incoming call, create a second call leg using a UAC
		in a B2BUA manner, this is needed in case we want to un-bridge later, a feature not currently implemented
		Call the specified event_route, defaulting to [rms:bridge].
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>rms_bridge usage example</title>
		<programlisting format="linespecific">
...
event_route[rms:bridged] {
	xnotice("[rms:bridged] !\n");
};

route {
	if (t_precheck_trans()) {
		t_check_trans();
		exit;
	}
	t_check_trans();
	if (is_method("INVITE") &amp;&amp; !has_totag()) {
		$var(target) = "sip:" + $rU + "@mydomain.com:5060;";
		if (!rms_bridge("$var(target)", "rms:bridged")) {
			t_reply("503", "server error");
		}
	}
	if(rms_dialog_check()) // If the dialog is managed by the RMS module, the in-dialog request needs to be handled by it.
		rms_sip_request();
...
		</programlisting></example>
	</section>


	<section id="rtp_media_server.f.rms_dialog_check">
		<title><varname>rms_dialog_check</varname> ()</title>
		<para>
		Returns true if the current SIP message it handled/known by
		the RMS module, else it may be handled in any other way by
		Kamailio.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, REPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title>rms_dialog_check usage example</title>
		<programlisting format="linespecific">
...
	if (rms_dialog_check()) {
		xnotice("This dialog is handled by the RMS module\n");
		rms_sip_request();
	}
...
		</programlisting></example>
	</section>

	<section id="rtp_media_server.f.rms_sip_request">
		<title><varname>rms_sip_request</varname> ()</title>
		<para>
		This should be called for every in-dialog SIP request,
		it will be forwarded behaving as a B2BUA, the transaction
		will be suspended until the second leg replies.
		</para>
		<para>
		If the SIP dialog is not found "481 Call/Transaction Does Not Exist"
		is returned.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, REPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title>rms_sip_request usage example</title>
		<programlisting format="linespecific">
...
	if (rms_dialog_check()) {
		rms_sip_request();
	}
...
		</programlisting></example>
	</section>

	<section id="rtp_media_server.f.rms_play">
		<title><varname>rms_play</varname> (file, event_route)</title>
		<para>
		Play a wav file, a resampler is automatically configured to resample
		and convert stereo to mono if needed.
		</para><para>
		The second parameter is the event route that will be called when the file was played.
		</para>
		<para>
		This function can be used from EVENT_ROUTE.
		</para>
		<example>
		<title>rms_play usage example</title>
		<programlisting format="linespecific">
...
	rms_play("file.wav", "event_route_name");
...
		</programlisting></example>
	</section>
</section>
</chapter>
