Kaynağa Gözat

iptrtpproxy: docbook parts split to functions.xml and params.xml

Daniel-Constantin Mierla 14 yıl önce
ebeveyn
işleme
8fb4f1da10

+ 343 - 0
modules/iptrtpproxy/doc/functions.xml

@@ -0,0 +1,343 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!ENTITY % local.common.attrib
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+	 <!-- Include general documentation entities -->
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+	 %docentities;
+	]
+>
+
+
+	<section id="iptrtpproxy.funcs" xmlns:xi="http://www.w3.org/2001/XInclude">
+		<title>Functions</title>
+
+		<section id="iptrtpproxy_alloc">
+		<title>
+			<function>iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])</function>
+		</title>
+		<para>
+			Parses SDP content and allocates for each RTP media stream one RTP proxy session.
+			SDP is updates to reflect allocated sessions. Switchboard/aggregation is set using
+			<function>iptrtpproxy_set_param(by_sip_ip)</function> or <function>iptrtpproxy_set_param("switchboard/aggregation")</function>.
+		</para>
+		<para>
+			Aggregation supports load balancing among more RTP proxies controlled by RPC.
+			The module try to allocate at machines/switchboards in following order (priorities)
+			not yet asked (or being heartbeated) machines, responsive machines, switchboards
+			having percentualy more free slots, non responsive machines.
+		</para>
+		<para>
+			Proxy may hide caller identity provided at <emphasis>o=</emphasis> line using
+			<function>@iptrtpproxy.o_name/addr</function> and <function>iptrtpproxy_set_param(o_name/addr)</function>
+			functions. But the script is responsible for rewritting to original values in
+			a response or a callee initiated re-INVITE. Therefore original value need to be stored
+			in-dialog.
+		</para>
+		<itemizedlist>
+			<listitem>
+			<para>
+				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
+				then SDP regards to gate-a to gate-b direction.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				<emphasis>protected_session_ids</emphasis> list of existing sessions
+				enables reusing already allocated sessions in re-INVITE without 
+				allocating new sessions for each stream in SDP regardless a IP/port
+				is required. It's mostly undesirable, typically "hold-on" is
+				done via re-INVITE without any change. There is drawback because
+				callee cannot change IP:port in 200OK which is legal case in RFC3264. 
+				But because some non-RFC3264 compliant phones dislike proactively 
+				changed IP:port at RTP proxy it seems it's less evil.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				function returns true is a session was created, identifier is available
+				via select <function>@iptrtpproxy.session_ids</function>.
+			</para>
+			</listitem>
+		</itemizedlist>
+		<example>
+			<title><function>iptrtpproxy_alloc</function> usage</title>
+			<programlisting>
+	...
+	if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip")) {
+		if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@received.ip")) {
+			t_reply("500", "RTP proxy error");
+			drop;
+		}
+	}
+	eval_push("x:%@next_hop.src_ip");
+	if (@eval.get[-1] == @received.ip) {
+		if (@iptrtpproxy.aggregation_a) {
+			iptrtpproxy_set_param("aggregation_b", "@iptrtpproxy.aggregation_a");
+		}
+		else {
+			iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.switchboard_a");
+		}
+	}
+	else {
+		if (!iptrtpproxy_set_param("aggregation_by_sip_ip_b", "@eval.get[-1]")) {
+			if (!iptrtpproxy_set_param("switchboard_by_sip_ip_b", "@eval.get[-1]")) {
+				t_reply("500", "RTP proxy error");
+				drop;
+			}
+		}
+	}
+	eval_remove(-1, 1);
+	
+	if (!iptrtpproxy_alloc("1")) {
+		t_reply("500", "RTP proxy error");
+		drop;
+	}
+	$sess_ids = @iptrtpproxy.session_ids;
+	...
+			</programlisting>
+		</example>
+		</section>
+
+		<section id="iptrtpproxy_update">
+		<title>
+			<function>iptrtpproxy_update(gate_a_to_b, session_ids)</function>
+		</title>
+		<para>
+		Parses SDP content and updates sessions provided by <emphasis>session_ids</emphasis> and
+		updates SDP. If succesfull then session_ids may be changed (in case e.g. media 
+		stream has port zero particular session is released), the
+		result of <function>@iptrtpproxy.session_ids</function> should be stored for future in-dialog usage.
+		</para>
+		<para>
+			The SDP contect is also affected by <function>iptrtpproxy_set_param(o_name/addr)</function>
+			functions. If a stream is deactivated in SDP then Sessions may be deleted unless 
+			mentioned in <emphasis>protected_session_ids</emphasis>.
+		</para>
+		<itemizedlist>
+			<listitem>
+			<para>
+				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
+				then SDP regards to gate-a to gate-b direction.
+			</para>
+			<para>
+				if <emphasis>gate_a_to_b</emphasis> bit 1 is set 
+				then SDP is updated only, no RTP session are affected.
+				Should be used when handling retransmission in onreply route,
+				retransmission replies are not eaten be tm module!
+			</para>
+			</listitem>
+		</itemizedlist>
+		<example>
+			<title><function>iptrtpproxy_update</function> usage</title>
+			<programlisting>
+	...
+	# load $sess_ids from dialog
+	if (iptrtpproxy_update("0", $sess_ids)) {
+	  $sess_ids = @iptrtpproxy.session_ids;
+	  # save sess_ids in dialog
+	}
+	...
+			</programlisting>
+		</example>
+		</section>
+
+		<section id="iptrtpproxy_adjust_timeout">
+		<title>
+			<function>iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)</function>
+		</title>
+		<para>
+		Adjust timeout for particular gate. It's useful in "200 OK"
+		decrease timeout to learning timeout if INVITE has set (long) <emphasis>ringing timeout</emphasis>.
+		</para>
+		<itemizedlist>
+			<listitem>
+			<para>
+				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
+				then it regards to gate-a to gate-b direction.
+			</para>
+			</listitem>
+		</itemizedlist>
+		<example>
+			<title><function>iptrtpproxy_adjust_timeout</function> usage</title>
+			<programlisting>
+	...
+	# load $sess_ids from dialog
+	if (status=~"18[0-9]") {
+		iptrtpproxy_set_param("learning_timeout", "60");
+	}
+	else {
+		iptrtpproxy_set_param("learning_timeout", "5");
+	}
+	if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
+	}
+	...
+			</programlisting>
+		</example>
+		</section>
+		<section id="iptrtpproxy_delete">
+		<title>
+			<function>iptrtpproxy_delete(session_ids)</function>
+		</title>
+		<para>
+		Delete sessions identified by <emphasis>session_ids</emphasis>. May be used when dialog is being
+		destroyed (BYE) or when INVITE failed in failure route. If <emphasis>protected_session_ids</emphasis>
+		list is provided then this set is excluded from sessions to be deleted.
+		</para>
+		<example>
+			<title><function>iptrtpproxy_delete</function> usage</title>
+			<programlisting>
+	...
+	# load $sess_ids from dialog
+	iptrtpproxy_delete($sess_ids);
+	...
+			</programlisting>
+		</example>
+		</section>
+
+		<section id="iptrtpproxy_authorize_media">
+		<title>
+			<function>iptrtpproxy_authorize_media()</function>
+		</title>
+		<para>
+		Authorizes SDP media according currect <emphasis>codec_set</emphasis>. If bit AND operation 
+		between rights in codec set and <function>remove_codec_mask</function> is non zero then
+		such a codec are to be removed. The result may be obtained from
+		<function>@iptrtpproxy.auth_rights</function> which returns max. right which has been applied when
+		processing all codecs of enabled streams.
+		</para>
+		<para>
+		The function MUST NOT be called after <function>iptrtpproxy_alloc/update</function>! 
+		But the function may be called several times to authorize using more codec sets.
+		</para>
+		<example>
+			<title><function>iptrtpproxy_authorize_media</function> usage</title>
+			<programlisting>
+	...
+	if (@iptrtpproxy.active_media_num == "0") break;
+	iptrtpproxy_set_param("codec_set", "cs2");
+	iptrtpproxy_set_param("remove_codec_mask", "1");
+	if (!iptrtpproxy_authorize_media()) {
+		t_reply("415", "Cannot authorize media");
+		drop;
+	}
+	iptrtpproxy_set_param("codec_set", "cs3");
+	if (!iptrtpproxy_authorize_media()) {
+		t_reply("415", "Cannot authorize media");
+		drop;
+	}
+	if (@iptrtpproxy.active_media_num == "0") {
+		t_reply("488", "Not acceptable here");
+		drop;
+	}
+	if (@iptrtpproxy.auth_rights == "2") {
+		append_hf_value("Contact: &lt;sip:1.2.3.4&gt;");
+		t_reply("301", "Redirect to transcoder");
+		drop;
+
+	}
+	...
+			</programlisting>
+		</example>
+		</section>
+
+		<section id="iptrtpproxy_set_param">
+		<title>
+			<function>iptrtpproxy_set_param(param, value)</function>
+		</title>
+		<para>
+			Set particular parameter needed mainly by <function>iptrtpproxy_alloc/update/adjust_timeout</function>.
+			The paramter value is availble via <function>@iptrtpproxy.&lt;param&gt;</function>.
+		</para>
+		<itemizedlist>
+			<listitem>
+			<para>
+				Supported parameters: <emphasis>expiration_timeout</emphasis>, <emphasis>ttl</emphasis>, <emphasis>learning_timeout</emphasis>, 
+				<emphasis>always_learn</emphasis>,
+				<emphasis>aggregation_a</emphasis>, <emphasis>aggregation_b</emphasis>, 
+				<emphasis>switchboard_a</emphasis>, <emphasis>switchboard_b</emphasis>,
+				<emphasis>throttle_mark</emphasis>,
+				<emphasis>throttle_rtp_max_bytes</emphasis>, <emphasis>throttle_rtp_max_packets</emphasis>, 
+				<emphasis>throttle_rtcp_max_bytes</emphasis>, <emphasis>throttle_rtcp_max_packets</emphasis>.
+			</para>
+			</listitem>
+		</itemizedlist>
+		</section>
+
+		<section id="iptrtpproxy_set_param(by_sip_ip)">
+		<title>
+			<function>iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)", sip_ip)</function>
+		</title>
+		<para>
+			Find corresponding aggregation or switchboard and set 
+			<function>@iptrtpproxy.aggregation_a/b</function> or <function>@iptrtpproxy.switchboard_a/b</function>.
+			Switchboards/aggregations are compared against <emphasis>sip-addr</emphasis>, 
+			it allow separate SIP and RTP traffic and RTP aggregation.
+		</para>
+		<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>sip_ip</emphasis> IP to be compared, typically <function>@received.ip</function>
+				or <function>@next_hop.src_ip</function>.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				function returns true if switchboard/aggregation was found
+			</para>
+			</listitem>
+		</itemizedlist>
+		</section>
+
+		<section id="iptrtpproxy_set_param(protected_session_ids)">
+		<title>
+			<function>iptrtpproxy_set_param("protected_session_ids", sess_ids)</function>
+		</title>
+		<para>
+			Used for reusing sessions in <function>iptrtpproxy_alloc</function>,  <function>iptrtpproxy_update</function>
+			and <function>iptrtpproxy_delete</function>.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy_set_param(o_name)">
+		<title>
+			<function>iptrtpproxy_set_param("o_name", value)</function>
+		</title>
+		<para>
+		Username to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
+		to hide caller identity. If value is blank then username is left unchanged.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy_set_param(o_addr)">
+		<title>
+			<function>iptrtpproxy_set_param("o_addr", value)</function>
+		</title>
+		<para>
+		Address to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
+		to hide caller identity. If value is blank then address is left unchanged.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy_set_param(codec_set)">
+		<title>
+			<function>iptrtpproxy_set_param("codec_set", value)</function>
+		</title>
+		<para>
+		Codec set for <function>iptrtpproxy_authorize_media</function>. Current codec set
+		may be obtained by <function>@iptrtpproxy.codec_set</function>.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy_set_param(remove_codec_mask)">
+		<title>
+			<function>iptrtpproxy_set_param("remove_codec_mask", value)</function>
+		</title>
+		<para>
+		Mask used in <function>iptrtpproxy_authorize_media</function>. Current mask 
+		may be obtained by <function>@iptrtpproxy.remove_codec_mask</function>.
+		</para>
+		</section>
+	</section>
+

+ 2 - 460
modules/iptrtpproxy/doc/iptrtpproxy.xml

@@ -111,469 +111,11 @@
 	</para></note>
 	</section>
 
-	<section id="iptrtpproxy.parameters">
 
-		<title>Parameters</title>
+	<xi:include href="params.xml"/>
+    <xi:include href="functions.xml"/>
 
-		<section id="config">
-		<title><varname>config</varname> (string)</title>
-		<para>
-  References <emphasis>iptrtpproxy.cfg</emphasis>, see <emphasis>iptrtpproxy_helper</emphasis>. Default value
-		is <emphasis>/etc/iptrtpproxy.cfg</emphasis>. If only codec authorization is to be used then 
-		<emphasis>/dev/null</emphasis> may be used.
-		</para>
-		</section>
-
-		<section id="switchboard">
-		<title><varname>switchboard</varname> (string)</title>
-		<para>
-  References <emphasis>xt_RTPPROXY</emphasis> switchboard for usage by ser module. 
-		</para>
-		<para>
-		The format is:
-		</para>
-			<programlisting>
-  "name=" value * ( ";" name "=" value )
-
-  name =  "aggregation" | "sip-addr-" 
-			</programlisting>
 
-		<para>
-  The <emphasis>name</emphasis> is the switchboard name as declared in config and will be used by script functions and references switchboard. 
-  It's mandatory parameter. The special name <emphasis>*</emphasis> set values for all switchboards. 
-		</para>
-		<para>
-  The <emphasis>sip-addr</emphasis> is address used by <function>iptrtpproxy_ser_param(by_sip_ip)</function> to find a switchboard for particular
-  connection. If not explicitly configured then RTP switchboard gate address are used for this feature. 
-		</para>
-		<para>
-The <emphasis>aggregation</emphasis> enables to aggregate more switchboards in cluster and to widden bandwidth.
-Aggregation will take <emphasis>sip-addr</emphasis> from the first switchboard of its. 
-		</para>
-		<example>
-			<title>Declare <varname>switchboard</varname></title>
-			<programlisting>
-	...
-	modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
-	modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip-addr-b=5.6.7.8");
-	modparam("iptrtpproxy", "switchboard", "name=my2;sip-addr-a=2.3.4.5;sip-addr-b=3.4.5.6;aggregation=my23");
-	modparam("iptrtpproxy", "switchboard", "name=my3;aggregation=my23");
-	modparam("iptrtpproxy", "switchboard", "name=*;aggregation=my123");
-	...
-			</programlisting>
-		</example>
-		</section>
-
-		<section id="rpc_heartbeat_timeout">
-		<title><varname>rpc_heartbeat_timeout</varname> (int)</title>
-		<para>
-		Timeout in seconds used for rerequest remote RTP proxy via RPC command after preceeding error.
-		In other words if a RPC server is unresponsive at the moment then next attempt will be forced
-		after this timeout. Default value is <emphasis>30</emphasis>.
-		</para>
-		</section>
-
-		<section id="hostname">
-		<title><varname>hostname</varname> (string)</title>
-		<para>
-		The hostname used by RPC to identify machine where Ser is running to communicate which RTP proxy
-		via local interface. Default value is taken from system hostname.
-		</para>
-		</section>
-
-		<section id="declare_codec">
-		<title><varname>declare_codec</varname> (string)</title>
-		<para>
-		There are basic implicit codecs compiled in module, more codecs may be added by this parameter (one codec per modparam).
-		</para>
-		</section>
-
-		<section id="codec_set">
-		<title><varname>codec_set</varname> (string)</title>
-		<para>
-		Declares new codec set. Codecs are declared for each media type independently. 
-		</para>
-		<para>
-		The format is:
-		</para>
-			<programlisting>
-  "name=" value * ( ";" name "=" value )
-
-  name =  "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp" ) "_" ( "bytes" | "packets" )
-
-  media_types = "audio" | "video" | "application" | "text" | "message" | "data" | "control" | "?" | "*"
-			</programlisting>		
-
-		<para>
-  The <emphasis>name</emphasis> is the codec set name to be defined.
-		</para>
-		<para>
-  The <emphasis>media_type</emphasis> belongs to type at <emphasis>m=</emphasis> SDP line. Question mark means
-  "unknown media" type and asterisk "all media types".
-		</para>
-		<para>
-  The <emphasis>max_streams</emphasis> defines how many streams (m= lines) is allowed per media type.
-		</para>
-		<para>
-  The <emphasis>rights</emphasis> defines if particular codec is allowed <emphasis>0</emphasis>, disallowed, i.e. will be removed
-  if bit AND operation with <function>remove_codec_mask</function> is non-zero or its presence will be signallized by <function>@iptrtpproxy.auth_rights</function> (any other value).
-		</para>
-		<para>
-  The <emphasis>codecs</emphasis> comma separated list of codecs. Previous <emphasis>media_type&amp;rights</emphasis> will be applied.
-		</para>
-		<para>
-  The <emphasis>rtp/rtcp_bytes/packets</emphasis> limits bandwidth per <emphasis>media_type</emphasis> (0 is unlimited). It will override
-  bandwidth limited by <function>iptrtpproxy_set_param("throttle_*")</function>.
-		</para>
-		<example>
-			<title>Declare <varname>codec_set</varname></title>
-			<programlisting>
-	...
-	# enable all codecs, default state when codec is declared
-	modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams=9999;rights=0;codecs=*");
-	# allow only 2 audio and 1 video stream
-	modparam("iptrtpproxy", "codec_set", "name=cs2;media_type=*;max_streams=0;media_type=audio;max_streams=2;media_type=video;max_streams=1");
-	# dtto, allow only a few audio and video codecs, GSM codec is allowed but signallized
-	modparam("iptrtpproxy", "codec_set", "name=cs3;media_type=*;max_streams=0;rights=1;codecs=*;media_type=audio;max_streams=2;rights=0;codecs=PCMU,G729,G728,parityfec,telephone-events;rights=2;codecs=GSM;media_type=video;max_streams=1;rights=0;codecs=jpeg,parityfec");
-	# limit max. bandwidth for video¨	
-	modparam("iptrtpproxy", "codec_set", "name=cs4;media_type=video;rtp_bytes=10000;rtcp_bytes=1000");
-	...
-			</programlisting>
-		</example>
-		</section>
-
-	</section>
-
-	<section id="iptrtpproxy.functions">
-		<title>Functions</title>
-
-		<section id="iptrtpproxy_alloc">
-		<title>
-			<function>iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])</function>
-		</title>
-		<para>
-			Parses SDP content and allocates for each RTP media stream one RTP proxy session.
-			SDP is updates to reflect allocated sessions. Switchboard/aggregation is set using
-			<function>iptrtpproxy_set_param(by_sip_ip)</function> or <function>iptrtpproxy_set_param("switchboard/aggregation")</function>.
-		</para>
-		<para>
-			Aggregation supports load balancing among more RTP proxies controlled by RPC.
-			The module try to allocate at machines/switchboards in following order (priorities)
-			not yet asked (or being heartbeated) machines, responsive machines, switchboards
-			having percentualy more free slots, non responsive machines.
-		</para>
-		<para>
-			Proxy may hide caller identity provided at <emphasis>o=</emphasis> line using
-			<function>@iptrtpproxy.o_name/addr</function> and <function>iptrtpproxy_set_param(o_name/addr)</function>
-			functions. But the script is responsible for rewritting to original values in
-			a response or a callee initiated re-INVITE. Therefore original value need to be stored
-			in-dialog.
-		</para>
-		<itemizedlist>
-			<listitem>
-			<para>
-				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
-				then SDP regards to gate-a to gate-b direction.
-			</para>
-			</listitem>
-			<listitem>
-			<para>
-				<emphasis>protected_session_ids</emphasis> list of existing sessions
-				enables reusing already allocated sessions in re-INVITE without 
-				allocating new sessions for each stream in SDP regardless a IP/port
-				is required. It's mostly undesirable, typically "hold-on" is
-				done via re-INVITE without any change. There is drawback because
-				callee cannot change IP:port in 200OK which is legal case in RFC3264. 
-				But because some non-RFC3264 compliant phones dislike proactively 
-				changed IP:port at RTP proxy it seems it's less evil.
-			</para>
-			</listitem>
-			<listitem>
-			<para>
-				function returns true is a session was created, identifier is available
-				via select <function>@iptrtpproxy.session_ids</function>.
-			</para>
-			</listitem>
-		</itemizedlist>
-		<example>
-			<title><function>iptrtpproxy_alloc</function> usage</title>
-			<programlisting>
-	...
-	if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip")) {
-		if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@received.ip")) {
-			t_reply("500", "RTP proxy error");
-			drop;
-		}
-	}
-	eval_push("x:%@next_hop.src_ip");
-	if (@eval.get[-1] == @received.ip) {
-		if (@iptrtpproxy.aggregation_a) {
-			iptrtpproxy_set_param("aggregation_b", "@iptrtpproxy.aggregation_a");
-		}
-		else {
-			iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.switchboard_a");
-		}
-	}
-	else {
-		if (!iptrtpproxy_set_param("aggregation_by_sip_ip_b", "@eval.get[-1]")) {
-			if (!iptrtpproxy_set_param("switchboard_by_sip_ip_b", "@eval.get[-1]")) {
-				t_reply("500", "RTP proxy error");
-				drop;
-			}
-		}
-	}
-	eval_remove(-1, 1);
-	
-	if (!iptrtpproxy_alloc("1")) {
-		t_reply("500", "RTP proxy error");
-		drop;
-	}
-	$sess_ids = @iptrtpproxy.session_ids;
-	...
-			</programlisting>
-		</example>
-		</section>
-
-		<section id="iptrtpproxy_update">
-		<title>
-			<function>iptrtpproxy_update(gate_a_to_b, session_ids)</function>
-		</title>
-		<para>
-		Parses SDP content and updates sessions provided by <emphasis>session_ids</emphasis> and
-		updates SDP. If succesfull then session_ids may be changed (in case e.g. media 
-		stream has port zero particular session is released), the
-		result of <function>@iptrtpproxy.session_ids</function> should be stored for future in-dialog usage.
-		</para>
-		<para>
-			The SDP contect is also affected by <function>iptrtpproxy_set_param(o_name/addr)</function>
-			functions. If a stream is deactivated in SDP then Sessions may be deleted unless 
-			mentioned in <emphasis>protected_session_ids</emphasis>.
-		</para>
-		<itemizedlist>
-			<listitem>
-			<para>
-				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
-				then SDP regards to gate-a to gate-b direction.
-			</para>
-			<para>
-				if <emphasis>gate_a_to_b</emphasis> bit 1 is set 
-				then SDP is updated only, no RTP session are affected.
-				Should be used when handling retransmission in onreply route,
-				retransmission replies are not eaten be tm module!
-			</para>
-			</listitem>
-		</itemizedlist>
-		<example>
-			<title><function>iptrtpproxy_update</function> usage</title>
-			<programlisting>
-	...
-	# load $sess_ids from dialog
-	if (iptrtpproxy_update("0", $sess_ids)) {
-	  $sess_ids = @iptrtpproxy.session_ids;
-	  # save sess_ids in dialog
-	}
-	...
-			</programlisting>
-		</example>
-		</section>
-
-		<section id="iptrtpproxy_adjust_timeout">
-		<title>
-			<function>iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)</function>
-		</title>
-		<para>
-		Adjust timeout for particular gate. It's useful in "200 OK"
-		decrease timeout to learning timeout if INVITE has set (long) <emphasis>ringing timeout</emphasis>.
-		</para>
-		<itemizedlist>
-			<listitem>
-			<para>
-				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
-				then it regards to gate-a to gate-b direction.
-			</para>
-			</listitem>
-		</itemizedlist>
-		<example>
-			<title><function>iptrtpproxy_adjust_timeout</function> usage</title>
-			<programlisting>
-	...
-	# load $sess_ids from dialog
-	if (status=~"18[0-9]") {
-		iptrtpproxy_set_param("learning_timeout", "60");
-	}
-	else {
-		iptrtpproxy_set_param("learning_timeout", "5");
-	}
-	if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
-	}
-	...
-			</programlisting>
-		</example>
-		</section>
-		<section id="iptrtpproxy_delete">
-		<title>
-			<function>iptrtpproxy_delete(session_ids)</function>
-		</title>
-		<para>
-		Delete sessions identified by <emphasis>session_ids</emphasis>. May be used when dialog is being
-		destroyed (BYE) or when INVITE failed in failure route. If <emphasis>protected_session_ids</emphasis>
-		list is provided then this set is excluded from sessions to be deleted.
-		</para>
-		<example>
-			<title><function>iptrtpproxy_delete</function> usage</title>
-			<programlisting>
-	...
-	# load $sess_ids from dialog
-	iptrtpproxy_delete($sess_ids);
-	...
-			</programlisting>
-		</example>
-		</section>
-
-		<section id="iptrtpproxy_authorize_media">
-		<title>
-			<function>iptrtpproxy_authorize_media()</function>
-		</title>
-		<para>
-		Authorizes SDP media according currect <emphasis>codec_set</emphasis>. If bit AND operation 
-		between rights in codec set and <function>remove_codec_mask</function> is non zero then
-		such a codec are to be removed. The result may be obtained from
-		<function>@iptrtpproxy.auth_rights</function> which returns max. right which has been applied when
-		processing all codecs of enabled streams.
-		</para>
-		<para>
-		The function MUST NOT be called after <function>iptrtpproxy_alloc/update</function>! 
-		But the function may be called several times to authorize using more codec sets.
-		</para>
-		<example>
-			<title><function>iptrtpproxy_authorize_media</function> usage</title>
-			<programlisting>
-	...
-	if (@iptrtpproxy.active_media_num == "0") break;
-	iptrtpproxy_set_param("codec_set", "cs2");
-	iptrtpproxy_set_param("remove_codec_mask", "1");
-	if (!iptrtpproxy_authorize_media()) {
-		t_reply("415", "Cannot authorize media");
-		drop;
-	}
-	iptrtpproxy_set_param("codec_set", "cs3");
-	if (!iptrtpproxy_authorize_media()) {
-		t_reply("415", "Cannot authorize media");
-		drop;
-	}
-	if (@iptrtpproxy.active_media_num == "0") {
-		t_reply("488", "Not acceptable here");
-		drop;
-	}
-	if (@iptrtpproxy.auth_rights == "2") {
-		append_hf_value("Contact: &lt;sip:1.2.3.4&gt;");
-		t_reply("301", "Redirect to transcoder");
-		drop;
-
-	}
-	...
-			</programlisting>
-		</example>
-		</section>
-
-		<section id="iptrtpproxy_set_param">
-		<title>
-			<function>iptrtpproxy_set_param(param, value)</function>
-		</title>
-		<para>
-			Set particular parameter needed mainly by <function>iptrtpproxy_alloc/update/adjust_timeout</function>.
-			The paramter value is availble via <function>@iptrtpproxy.&lt;param&gt;</function>.
-		</para>
-		<itemizedlist>
-			<listitem>
-			<para>
-				Supported parameters: <emphasis>expiration_timeout</emphasis>, <emphasis>ttl</emphasis>, <emphasis>learning_timeout</emphasis>, 
-				<emphasis>always_learn</emphasis>,
-				<emphasis>aggregation_a</emphasis>, <emphasis>aggregation_b</emphasis>, 
-				<emphasis>switchboard_a</emphasis>, <emphasis>switchboard_b</emphasis>,
-				<emphasis>throttle_mark</emphasis>,
-				<emphasis>throttle_rtp_max_bytes</emphasis>, <emphasis>throttle_rtp_max_packets</emphasis>, 
-				<emphasis>throttle_rtcp_max_bytes</emphasis>, <emphasis>throttle_rtcp_max_packets</emphasis>.
-			</para>
-			</listitem>
-		</itemizedlist>
-		</section>
-
-		<section id="iptrtpproxy_set_param(by_sip_ip)">
-		<title>
-			<function>iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)", sip_ip)</function>
-		</title>
-		<para>
-			Find corresponding aggregation or switchboard and set 
-			<function>@iptrtpproxy.aggregation_a/b</function> or <function>@iptrtpproxy.switchboard_a/b</function>.
-			Switchboards/aggregations are compared against <emphasis>sip-addr</emphasis>, 
-			it allow separate SIP and RTP traffic and RTP aggregation.
-		</para>
-		<itemizedlist>
-			<listitem>
-			<para>
-				<emphasis>sip_ip</emphasis> IP to be compared, typically <function>@received.ip</function>
-				or <function>@next_hop.src_ip</function>.
-			</para>
-			</listitem>
-			<listitem>
-			<para>
-				function returns true if switchboard/aggregation was found
-			</para>
-			</listitem>
-		</itemizedlist>
-		</section>
-
-		<section id="iptrtpproxy_set_param(protected_session_ids)">
-		<title>
-			<function>iptrtpproxy_set_param("protected_session_ids", sess_ids)</function>
-		</title>
-		<para>
-			Used for reusing sessions in <function>iptrtpproxy_alloc</function>,  <function>iptrtpproxy_update</function>
-			and <function>iptrtpproxy_delete</function>.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy_set_param(o_name)">
-		<title>
-			<function>iptrtpproxy_set_param("o_name", value)</function>
-		</title>
-		<para>
-		Username to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
-		to hide caller identity. If value is blank then username is left unchanged.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy_set_param(o_addr)">
-		<title>
-			<function>iptrtpproxy_set_param("o_addr", value)</function>
-		</title>
-		<para>
-		Address to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
-		to hide caller identity. If value is blank then address is left unchanged.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy_set_param(codec_set)">
-		<title>
-			<function>iptrtpproxy_set_param("codec_set", value)</function>
-		</title>
-		<para>
-		Codec set for <function>iptrtpproxy_authorize_media</function>. Current codec set
-		may be obtained by <function>@iptrtpproxy.codec_set</function>.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy_set_param(remove_codec_mask)">
-		<title>
-			<function>iptrtpproxy_set_param("remove_codec_mask", value)</function>
-		</title>
-		<para>
-		Mask used in <function>iptrtpproxy_authorize_media</function>. Current mask 
-		may be obtained by <function>@iptrtpproxy.remove_codec_mask</function>.
-		</para>
-		</section>
-	</section>
 	<section>
 		<title>Selects</title>
 

+ 145 - 0
modules/iptrtpproxy/doc/params.xml

@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!ENTITY % local.common.attrib
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+	 <!-- Include general documentation entities -->
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+	 %docentities;
+	]
+>
+
+
+	<section id="iptrtpproxy.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+		<title>Parameters</title>
+
+		<section id="config">
+		<title><varname>config</varname> (string)</title>
+		<para>
+  References <emphasis>iptrtpproxy.cfg</emphasis>, see <emphasis>iptrtpproxy_helper</emphasis>. Default value
+		is <emphasis>/etc/iptrtpproxy.cfg</emphasis>. If only codec authorization is to be used then 
+		<emphasis>/dev/null</emphasis> may be used.
+		</para>
+		</section>
+
+		<section id="switchboard">
+		<title><varname>switchboard</varname> (string)</title>
+		<para>
+  References <emphasis>xt_RTPPROXY</emphasis> switchboard for usage by ser module. 
+		</para>
+		<para>
+		The format is:
+		</para>
+			<programlisting>
+  "name=" value * ( ";" name "=" value )
+
+  name =  "aggregation" | "sip-addr-" 
+			</programlisting>
+
+		<para>
+  The <emphasis>name</emphasis> is the switchboard name as declared in config and will be used by script functions and references switchboard. 
+  It's mandatory parameter. The special name <emphasis>*</emphasis> set values for all switchboards. 
+		</para>
+		<para>
+  The <emphasis>sip-addr</emphasis> is address used by <function>iptrtpproxy_ser_param(by_sip_ip)</function> to find a switchboard for particular
+  connection. If not explicitly configured then RTP switchboard gate address are used for this feature. 
+		</para>
+		<para>
+The <emphasis>aggregation</emphasis> enables to aggregate more switchboards in cluster and to widden bandwidth.
+Aggregation will take <emphasis>sip-addr</emphasis> from the first switchboard of its. 
+		</para>
+		<example>
+			<title>Declare <varname>switchboard</varname></title>
+			<programlisting>
+	...
+	modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
+	modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip-addr-b=5.6.7.8");
+	modparam("iptrtpproxy", "switchboard", "name=my2;sip-addr-a=2.3.4.5;sip-addr-b=3.4.5.6;aggregation=my23");
+	modparam("iptrtpproxy", "switchboard", "name=my3;aggregation=my23");
+	modparam("iptrtpproxy", "switchboard", "name=*;aggregation=my123");
+	...
+			</programlisting>
+		</example>
+		</section>
+
+		<section id="rpc_heartbeat_timeout">
+		<title><varname>rpc_heartbeat_timeout</varname> (int)</title>
+		<para>
+		Timeout in seconds used for rerequest remote RTP proxy via RPC command after preceeding error.
+		In other words if a RPC server is unresponsive at the moment then next attempt will be forced
+		after this timeout. Default value is <emphasis>30</emphasis>.
+		</para>
+		</section>
+
+		<section id="hostname">
+		<title><varname>hostname</varname> (string)</title>
+		<para>
+		The hostname used by RPC to identify machine where Ser is running to communicate which RTP proxy
+		via local interface. Default value is taken from system hostname.
+		</para>
+		</section>
+
+		<section id="declare_codec">
+		<title><varname>declare_codec</varname> (string)</title>
+		<para>
+		There are basic implicit codecs compiled in module, more codecs may be added by this parameter (one codec per modparam).
+		</para>
+		</section>
+
+		<section id="codec_set">
+		<title><varname>codec_set</varname> (string)</title>
+		<para>
+		Declares new codec set. Codecs are declared for each media type independently. 
+		</para>
+		<para>
+		The format is:
+		</para>
+			<programlisting>
+  "name=" value * ( ";" name "=" value )
+
+  name =  "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp" ) "_" ( "bytes" | "packets" )
+
+  media_types = "audio" | "video" | "application" | "text" | "message" | "data" | "control" | "?" | "*"
+			</programlisting>		
+
+		<para>
+  The <emphasis>name</emphasis> is the codec set name to be defined.
+		</para>
+		<para>
+  The <emphasis>media_type</emphasis> belongs to type at <emphasis>m=</emphasis> SDP line. Question mark means
+  "unknown media" type and asterisk "all media types".
+		</para>
+		<para>
+  The <emphasis>max_streams</emphasis> defines how many streams (m= lines) is allowed per media type.
+		</para>
+		<para>
+  The <emphasis>rights</emphasis> defines if particular codec is allowed <emphasis>0</emphasis>, disallowed, i.e. will be removed
+  if bit AND operation with <function>remove_codec_mask</function> is non-zero or its presence will be signallized by <function>@iptrtpproxy.auth_rights</function> (any other value).
+		</para>
+		<para>
+  The <emphasis>codecs</emphasis> comma separated list of codecs. Previous <emphasis>media_type&amp;rights</emphasis> will be applied.
+		</para>
+		<para>
+  The <emphasis>rtp/rtcp_bytes/packets</emphasis> limits bandwidth per <emphasis>media_type</emphasis> (0 is unlimited). It will override
+  bandwidth limited by <function>iptrtpproxy_set_param("throttle_*")</function>.
+		</para>
+		<example>
+			<title>Declare <varname>codec_set</varname></title>
+			<programlisting>
+	...
+	# enable all codecs, default state when codec is declared
+	modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams=9999;rights=0;codecs=*");
+	# allow only 2 audio and 1 video stream
+	modparam("iptrtpproxy", "codec_set", "name=cs2;media_type=*;max_streams=0;media_type=audio;max_streams=2;media_type=video;max_streams=1");
+	# dtto, allow only a few audio and video codecs, GSM codec is allowed but signallized
+	modparam("iptrtpproxy", "codec_set", "name=cs3;media_type=*;max_streams=0;rights=1;codecs=*;media_type=audio;max_streams=2;rights=0;codecs=PCMU,G729,G728,parityfec,telephone-events;rights=2;codecs=GSM;media_type=video;max_streams=1;rights=0;codecs=jpeg,parityfec");
+	# limit max. bandwidth for video¨	
+	modparam("iptrtpproxy", "codec_set", "name=cs4;media_type=video;rtp_bytes=10000;rtcp_bytes=1000");
+	...
+			</programlisting>
+		</example>
+		</section>
+
+	</section>
+