tm_user.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.3.2.1 $</revnumber>
		<date>$Date: 2005/06/22 23:12:08 $</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>
	    <title><varname>ruri_matching</varname> (integer)</title>
	    <para>
		The parameter controls whether the Request-URI should be
		included in pre-RFC3261 transaction maching. When set 1 then
		the Request-URI will be included, when set to 0 then it will be
		not included.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 (include Request-URI).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>via1_matching</varname> (integer)</title>
	    <para>
		The parameter controls whether the topmost Via header field
		should be included in pre-RFC3261 transaction maching. When set
		1 then the topmost Via header field will be included, when set
		to 0 then it will be not included.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 (include topmost Via header field).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>uac_from</varname> (string)</title>
	    <para>
		This parameter allows to configure the URI that will be put in
		the From header field of SIP request generated localy by the
		UAC in tm module. This parameter is currently not used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "sip:[e-mail]".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>unix_tx_timeout</varname> (integer)</title>
	    <para>
		Maximum timeout in seconds for the request sent over the unix
		domain socket interface (using t_write_unix function). The
		function will indicate failure if it does not manage to send
		all the data within the interval configured by this parameter.
	    </para>
	    <para>
		<emphasis>
		    Default value is 2 seconds.
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>restart_fr_on_each_reply</varname> (integer)</title>
	    <para>
		The parameter controls whether the FR timer will be restarted on
		each provisional reply received.
	    </para>
	    <para>
		<emphasis>