tm_user.sgml

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

		    Default value is 1 (yes).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>fr_timer_avp</varname> (string)</title>
	    <para>
		This parameter makes it possible to override the value of FR
		(final reply) timer on per-transaction basis. TM module can
		pick the value of the timer from an AVP. The name or ID of the
		AVP can be configured by this parameter. If there is no such
		AVP then the default value configured through fr_timer
		parameter will be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "callee_fr_timer".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>fr_inv_timer_avp</varname> (string)</title>
	    <para>
		This parameter makes it possible to override the value of FR
		Invite (final response for INVITE transactions) timer on
		per-transaction basis. TM module can pick the value of the
		timer from an AVP. The name or ID of the AVP can be configured
		by this parameter. If there is no such AVP then the default
		value configured through fr_inv_timer parameter will be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is "callee_fr_inv_timer".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>tw_append</varname> (string)</title>
	    <para>
		This parameter configures additional information that can be
		passed over the FIFO or unix domain socket interfaces by TM
		module to another application. TM module can pass values of
		AVPs, SIP message header fields, or the message body. Syntax of
		the parameter is as follows:
	    </para>
	    <programlisting>
tw_append = name ':' element ( ';' element ) *
element   = [ title '=' ] ( avp_val | hdr_val )
element   = title '=' body_val
avp_val   = "avp" '[' avp_spec ']'
hdr_val   = "hdr" '[' hdr_name ']'
body_val  = "msg[body]"
</programlisting>
	    <para>
		<emphasis>
		    Default value is "".
		</emphasis>
	    </para>

	    <example>
		<title>Set <varname>tw_append</varname> parameter</title>
		<para>
		    Pass the value of callee_fr_timer AVP, the contents of
		    Subject header field, and the whole SIP message body to the
		    application over FIFO or unix domain socket interface.
		</para>
		<programlisting format="linespecific">
...
modparam("tm", "tw_append", "params:avp[callee_fr_timer];hdr[Subject];body=msg[body]")
...
</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>,
		<function moreinfo="none">t_relay_to_tls(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>
		<title><function>t_relay</function> usage</title>
		<programlisting format="linespecific">
...
if (!t_relay()) { sl_reply_error(); break; };
...
</programlisting>
	    </example>
	</section>




	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed after a transaction completed
		with a negative result but before sending a final reply. In the referred block, you
		can either start a new branch (good for services such as forward_on_no_reply) or
		send a final reply on your own (good for example for message silo, which received a
		negative reply from upstream and wants to tell upstream <quote>202 I will take care
		of it</quote>). Note that the set of command which are usable within reply_routes
		is strictly limited to rewriting &uri;, initiating new branches, logging, and
		sending stateful replies (<function>t_reply</function>). Any other commands may
		result in unpredictable behavior and possible server failure. Note that whenever
		reply_route is entered, uri is reset to value which it had on relaying. If it
		temporarily changed during a reply_route processing, subsequent reply_route will
		ignore the changed value and use again the original one.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed after a transaction completed
		with a negative result but before sending a final reply. In the referred block, you
		can either start a new branch (good for services such as forward_on_no_reply) or
		send a final reply on your own (good for example for message silo, which received a
		negative reply from upstream and wants to tell upstream <quote>202 I will take care
		of it</quote>). Note that the set of command which are usable within reply_routes
		is strictly limited to rewriting &uri;, initiating new branches, logging, and
		sending stateful replies (<function>t_reply</function>). Any other commands may
		result in unpredictable behavior and possible server failure. Note that whenever
		reply_route is entered, uri is reset to value which it had on relaying. If it
		temporarily changed during a reply_route processing, subsequent reply_route will
		ignore the changed value and use again the original one.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_failure(reply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed after a transaction completed
		with a negative result but before sending a final reply. In the referred block, you
		can either start a new branch (good for services such as forward_on_no_reply) or
		send a final reply on your own (good for example for message silo, which received a
		negative reply from upstream and wants to tell upstream <quote>202 I will take care
		of it</quote>). Note that the set of command which are usable within reply_routes
		is strictly limited to rewriting &uri;, initiating new branches, logging, and
		sending stateful replies (<function>t_reply</function>). Any other commands may
		result in unpredictable behavior and possible server failure. Note that whenever
		reply_route is entered, uri is reset to value which it had on relaying. If it
		temporarily changed during a reply_route processing, subsequent reply_route will
		ignore the changed value and use again the original one.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_failure("1"); 
    t_relay(); 
} 

failure_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_reply(onreply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed when a
		reply is received from one of downstream branches. Only a
		limited set of functions is available in onreply_route
		blocks. The routing block will be called for every reply
		received from downstream. A typical use for onreply_route
		blocks would be rewriting contacts with private IP addresses in
		200 OK replies by nathelper module.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>onreply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_reply</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_reply("1"); 
    t_relay(); 
} 

onreply_route[1] {
    fix_nated_contact();
    force_rtp_proxy();
}
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_check_status(regex)</function>
	    </title>
	    <para>
		This function can be used to check the status code in replies
		from failure_route and onreply_route blocks. It allows to
		differentiate processing based on the status code received.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>regex</emphasis> - Regular expression to be
		    matched agains the status code.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_check_status</function> usage</title>
		<programlisting format="linespecific">
...
failure_route[1] {
    if (t_check_status("486")) {
        # Busy
        t_relay_to_udp("1.2.3.4", "5060");
    };
 }
...
</programlisting>
	    </example>
	</section>

	<section>