tm_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 1,224 行 · 第 1/3 页

		<para>
		Remove transaction from memory (it will be first put on a wait timer 
		to absorb delayed messages).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>t_release</function> usage</title>
		<programlisting format="linespecific">
...
t_release();
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_check_status(re)</function>
		</title>
		<para>
		Returns true if the regualr expresion <quote>re</quote> match the 
		reply code of the response message as follows:
		<itemizedlist>
		<listitem>
			<para><emphasis>in routing block</emphasis> - the code of the
			last sent reply.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>in on_reply block</emphasis> - the code of the
			current received reply.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>in on_failure block</emphasis> - the code of the
			selected negative final reply.
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE .
		</para>
		<example>
		<title><function>t_check_status</function> usage</title>
		<programlisting format="linespecific">
...
if (t_check_status("(487)|(408)")) {
    log("487 or 408 negative reply\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_flush_flags()</function>
		</title>
		<para>
		Flush the flags from current request into the already created 
		transaction. It make sens only in routing block if the trnasaction was
		created via t_newtran() and the flags have been altered since.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and BRANCH_ROUTE .
		</para>
		<example>
		<title><function>t_flush_flags</function> usage</title>
		<programlisting format="linespecific">
...
t_flush_flags();
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_local_replied(reply)</function>
		</title>
		<para>
		Returns true if all or last (depending of the parameter) reply(es) were
		local generated (and not received).
		</para>
		<para>
		Parameter may be <quote>all</quote> or <quote>last</quote>.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
		FAILURE_ROUTE and ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>t_local_replied</function> usage</title>
		<programlisting format="linespecific">
...
if (t_local_replied("all")) {
	log ("no reply received\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_write_fifo(info,fifo)</function>
		<function moreinfo="none">t_write_unix(info,sock)</function>
		</title>
		<para>
		Write via FIFO file or UNIX socket a lot of information regarding the
		request. Which information should be written may be control via the
		<quote>tw_append</quote> parameter.
		</para>
		<para>
		This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE and 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>t_write_fifo/unix</function> usage</title>
		<programlisting format="linespecific">
...
modparam("tm","tw_append","append1:Email=avp[i:12];UA=hdr[User-Agent]")
modparam("tm","tw_append","append2:body=msg[body]")
...
t_write_fifo("voicemail/append1","/tmp/appx_fifo");
...
t_write_unix("logger/append2","/var/run/logger.sock");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_check_trans()</function>
		</title>
		<para>
		Returns true if the current request is associated to a transaction. 
		The relationship between the request ans transaction is defined as 
		follow:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>non-CANCEL/non-ACK requests</emphasis> - is true 
			if the request belongs to a transaction; if so, it means that the 
			request is a retransmision.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>CANCEL request</emphasis> - true if the cancelled
			INVITE transaction exists.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>ACK request</emphasis> - true if the ACK is a
			local end-to-end ACK for an existent INVITE transaction.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>t_check_trans</function> usage</title>
		<programlisting format="linespecific">
...
if ( is_method("CANCEL") ) {
	if ( t_check_trans() )
		t_relay();
	exit;
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_was_cancelled()</function>
		</title>
		<para>
		Retuns true if called for an INVITE transaction that was explicitly
		cancelled by UAC side via a CANCEL request.
		</para>
		<para>
		This function can be used from ONREPLY_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_was_cancelled</function> usage</title>
		<programlisting format="linespecific">
...
if (t_was_cancelled()) {
    log("transaction was cancelled by UAC\n");
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_on_failure(failure_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>).
		</para>
		<para>
		As not all functions are available from failure route, please check 
		the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one failure_route can be armed for a request. If you use many
		times t_on_failure(), only the last one has effect.
		</para>
		<para>
		Note that whenever failure_route is entered, RURI is set to value 
		of the winning branch.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>failure_route</emphasis> - Reply route block to be 
			called.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_failure</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_failure("1"); 
	t_relay();
} 

failure_route[1] {
	seturi("sip:user@voicemail");
	append_branch();
	t_relay();
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">t_on_reply(reply_route)</function>
		</title>
		<para>
		Sets reply routing block, to which control is passed each time a reply
		(provisional or final) for the transaction is received. 
		The route is not called for local generated replies! In the referred 
		block, you can inspect the reply and perform text operations on it.
		</para>
		<para>
		As not all functions are available from this type of route, please 
		check  the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one onreply_route can be armed for a request. If you use many
		times t_on_reply(), only the last one has effect.
		</para>
		<para>
		If the processed reply is provisionla reply (1xx code), by calling
		the drop() function (exported by core), the execution of the route
		will end and the reply will not be forwarded further.
		</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>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_reply</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_reply("1"); 
	t_relay();
} 

onreply_route[1] {
	if (t_check_status("1[0-9][0-9]")) {
		setflag(1);
		log("provisional reply received\n");
		if (t_check_status("183"))
			drop;
	}
}
...
</programlisting>
		</example>
	</section>

	<section id="branch-route">
		<title>
		<function moreinfo="none">t_on_branch(branch_route)</function>
		</title>
		<para>
		Sets a branch route to be execute separately for each branch of the
		transaction before being sent out - changes in that route should 
		reflect only on that branch.
		</para>
		<para>
		As not all functions are available from this type of route, please 
		check  the documentation for each function to see the permissions.
		Any other commands may result in unpredictable behavior and 
		possible server failure.
		</para>
		<para>
		Only one branch_route can be armed for a request. If you use many
		time t_on_branch(), only the last one has effect.
		</para>
		<para>
		The per-branch flags which are modified in the branch route will be
		visible only in the replies related to that branch.
		See <xref linkend="branch-flag-mask"> also.
		</para>
		<para>
		By calling the drop() function (exported by core), the execution of 
		the branch route will end and the branch will not be forwarded further.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>branch_route</emphasis> - Branch route block to be 
			called.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, 
		ONREPLY_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>t_on_branch</function> usage</title>
		<programlisting format="linespecific">
...
route { 
	t_on_reply("1"); 
	t_relay();
} 

branch_route[1] {
	if (uri=~"bad_uri") {
		xlog("dropping branch $ru \n");
		drop;
	}
	if (uri=~"GW_uri") {
		append_rpid();
	}
}
...
</programlisting>
		</example>
	</section>

	</section>
	<section>
	<title>Pseudo-Variables</title>
	<para>
	This module exports the follong pseudo-variables:
	</para>
	<itemizedlist>
		<listitem>
			<para>
			<emphasis>$T_branch_index</emphasis> - the index (starting with 1
			for the first branch) of the branch for which is executed the
			branch_route[]. If used outside of branch_route[] block, the value
			is '0'.
			</para>
		</listitem>
	</itemizedlist>
	</section>
</chapter>

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