sl_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.4 $</revnumber>
		<date>$Date: 2006/02/06 17:01:26 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		The <acronym>SL</acronym> module allows &ser; to act as a stateless 
		&ua; server and generate replies to &sip; requests without keeping 
		state. That is beneficial in many scenarios, in which you wish not to 
		burden server's memory and scale well.
	</para>
	<para>
		The <acronym>SL</acronym> module needs to filter ACKs sent after a 
		local stateless reply to an INVITE was generated. To recognize such 
		ACKs, &ser; adds a special "signature" in to-tags. This signature is 
		sought for in incoming ACKs, and if included, the ACKs are absorbed.
	</para>
	<para>
		To speed up the filtering process, the module uses a timeout 
		mechanism. When a reply is sent, a timer is set. As time as the timeout 
		didn't hit, the incoming ACK requests will be checked using TO tag 
		value. Once the timer expires, all the ACK are let through - a long
		time passed till it sent a reply, so it does not expect any ACK that 
		have to be blocked.
	</para>
	<para>
		The ACK filtering may fail in some rare cases. If you think these 
		matter to you, better use stateful processing (tm module) for INVITE 
		processing. Particularly, the problem happens when a UA sends an 
		INVITE which already has a to-tag in it (e.g., a re-INVITE)
		and &ser; want to reply to it. Than, it will keep the current to-tag, 
		which will be mirrored in ACK. &ser; will not see its signature and 
		forward the ACK downstream. Caused harm is not bad--just a useless 
		ACK is forwarded.
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>enable_stats</varname> (integer)</title>
		<para>
		If the module should generate and export statistics to the core
		manager. A zero value means disabled.
		</para>
		<para>
		SL module provides statistics about how many replies were sent (
		splitted per code classes) and how many local ACKs were filtered out.
		</para>
		<para>
		Default value is 1 (enabled).
		</para>
		<example>
		<title>enable_stats example</title>
		<programlisting format="linespecific">
modparam("sl", "enable_stats", 0)
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">sl_send_reply(code, reason)</function>
		</title>
		<para>
		For the current request, a reply is sent back having the given code 
		and text reason. The reply is sent stateless, totally independent of 
		the Transaction module and with no retransmission for the INVITE's 
		replies.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>code</emphasis> - Return code.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>reason</emphasis> - Reason phrase.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>sl_send_reply</function> usage</title>
		<programlisting format="linespecific">
...
sl_send_reply("404", "Not found");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">sl_reply_error()</function>
		</title>
		<para>
		Sends back an error reply describing the nature of the last internal 
		error.  Usually this function should be used after a script function 
		that returned an error code.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>sl_reply_error</function> usage</title>
		<programlisting format="linespecific">
...
sl_reply_error();
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("sl.sgml" "Book" "chapter")
End:
-->