tm_user.sgml

sip server服务器

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.3 $</revnumber>
		<date>$Date: 2004/08/24 09:00:45 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    <acronym>TM</acronym> module enables stateful processing of &sip; transactions. The main
	    use of stateful logic, which is costly in terms of memory and <acronym>CPU</acronym>, is
	    some services inherently need state. For example, transaction-based accounting (module
	    acc) needs to process transaction state as opposed to individual messages, and any kinds
	    of forking must be implemented statefully. Other use of stateful processing is it trading
	    <acronym>CPU</acronym> caused by retransmission processing for memory. That makes
	    however only sense if <acronym>CPU</acronym> consumption per request is huge. For
	    example, if you want to avoid costly <acronym>DNS</acronym> resolution for every
	    retransmission of a request to an unresolvable destination, use stateful mode. Then,
	    only the initial message burdens server by <acronym>DNS</acronym> queries, subsequent
	    retransmissions will be dropped and will not result in more processes blocked by
	    <acronym>DNS</acronym> resolution. The price is more memory consumption and higher
	    processing latency.
	</para>
	<para>
	    From user's perspective, there are these major functions : t_relay, t_relay_to_udp
		and t_relay_to_tcp. All of them
	    setup transaction state, absorb retransmissions from upstream, generate downstream
	    retransmissions and correlate replies to requests. t_relay forwards to current &uri; (be
	    it original request's &uri; or a &uri; changed by some of &uri;-modifying functions,
	    such as sethost). t_relay_to_udp and t_relay_to_tcp forward to a specific address
		over UDP or TCP respectively.
	</para>
	<para>
	    In general, if <acronym>TM</acronym> is used, it copies clones of received &sip;
	    messages in shared memory. That costs the memory and also <acronym>CPU</acronym> time
	    (memcpys, lookups, shmem locks, etc.)  Note that non-<acronym>TM</acronym> functions
	    operate over the received message in private memory, that means that any core operations
	    will have no effect on statefully processed messages after creating the transactional
	    state. For example, calling record_route <emphasis>after</emphasis> t_relay is pretty
	    useless, as the <acronym>RR</acronym> is added to privately held message whereas its
	    <acronym>TM</acronym> clone is being forwarded.
	</para>
	<para>
	    <acronym>TM</acronym> is quite big and uneasy to program--lot of mutexes, shared memory
	    access, malloc & free, timers--you really need to be careful when you do anything. To
	    simplify <acronym>TM</acronym> programming, there is the instrument of callbacks. The
	    callback mechanisms allow programmers to register their functions to specific event. See
	    t_hooks.h for a list of possible events.
	</para>
	<para>
	    Other things programmers may want to know is &uac;--it is a very simplistic code which
	    allows you to generate your own transactions. Particularly useful for things like
	    NOTIFYs or <acronym>IM</acronym> gateways. The &uac; takes care of all the transaction
	    machinery: retransmissions , FR timeouts, forking, etc.  See t_uac prototype in uac.h
	    for more details. Who wants to see the transaction result may register for a callback.
	</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>fr_timer</varname> (integer)</title>
	    <para>
		Timer which hits if no final reply for a request or ACK for a negative INVITE reply
		arrives (in seconds).
	    </para>
	    <para>
		<emphasis>
		    Default value is 30 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fr_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timer", 10)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>fr_inv_timer</varname> (integer)</title>
	    <para>
		Timer which hits if no final reply for an INVITE arrives after a provisional message
		was received (in seconds).
	    </para>
	    <para>
		<emphasis>
		    Default value is 120 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fr_inv_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timer", 200)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>wt_timer</varname> (integer)</title>
	    <para>
		Time for which a transaction stays in memory to absorb delayed messages after it
		completed; also, when this timer hits, retransmission of local cancels is stopped (a
		puristic but complex behavior would be not to enter wait state until local branches
		are finished by a final reply or FR timer--we simplified).
	    </para>
	    <para>
		<emphasis>
		    Default value is 5 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>wt_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "wt_timer", 10)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>delete_timer</varname> (integer)</title>
	    <para>
		Time after which a to-be-deleted transaction currently ref-ed by a process will be
		tried to be deleted again.
	    </para>
	    <para>
		<emphasis>
		    Default value is 2 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>delete_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "delete_timer", 5)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer1p1</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p1</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p1", 2)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer1p2</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 2 * <varname>retr_timer1p1</varname> second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p2", 4)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer1p3</varname> (integer)</title>
	    <para>
		Retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4 * <varname>retr_timer1p1</varname> second.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer1p4</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p3", 8)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>retr_timer2</varname> (integer)</title>
	    <para>
		Maximum retransmission period.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4 seconds.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>retr_timer2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer2", 8)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>noisy_ctimer</varname> (integer)</title>
	    <para>
		If set, on FR timer INVITE transactions will be explicitly canceled if possible,
		silently dropped otherwise. Preferably, it is turned off to allow very long ringing.
		This behavior is overridden if a request is forked, or some functionality
		explicitly turned it off for a transaction (like acc does to avoid unaccounted
		transactions due to expired timer).
	    </para>
	    <para>
		<emphasis>
		    Default value is 0 (false).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>noisy_ctimer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "noisy_ctimer", 1)
...
</programlisting>
	    </example>
	</section>



    </section>
    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">t_relay_to_udp(ip, port)</function>,
		<function moreinfo="none">t_relay_to_tcp(ip, port)</function>
	    </title>
	    <para>
		Relay a message statefully to a fixed destination. This along with <function
		    moreinfo="none">t_relay</function> is the function most users want to use--all
		other are mostly for programming. Programmers interested in writing
		<acronym>TM</acronym> logic should review how t_relay is implemented in tm.c and
		how <acronym>TM</acronym> callbacks work.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>ip</emphasis> - &ip address where the message should be sent.
		    </para>
		</listitem>
		<listitem>
		    <para><emphasis>port</emphasis> - Port number.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_relay_to_udp</function> usage</title>
		<programlisting format="linespecific">
...
t_relay_to_udp("1.2.3.4", "5060");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_relay()</function>
	    </title>
	    <para>
		Relay a message statefully to destination indicated in current &uri;. (If the
		original &uri; was rewritten by UsrLoc, RR, strip/prefix, etc., the new &uri; will
		be taken). Returns a negative value on failure--you may still want to send a
		negative reply upstream statelessly not to leave upstream &uac; in lurch.
	    </para>
	    <example>