mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1769 lines
50 KiB
1769 lines
50 KiB
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<section id="tm.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<sectioninfo>
|
|
</sectioninfo>
|
|
|
|
<title>Functions</title>
|
|
|
|
<section id="tm.f.t_relay">
|
|
<title>
|
|
<function>t_relay([host, port])</function>
|
|
</title>
|
|
<para>
|
|
Relay a message statefully either to the destination indicated in the
|
|
current URI (if called without any parameters) or to the specified
|
|
host and port. In the later case (host and port specified) the protocol
|
|
used is the same protocol on which the message was received.
|
|
</para>
|
|
<para>
|
|
<function>t_relay()</function> is the statefull version for
|
|
<function>forward()</function>
|
|
while <function>t_relay(host, port)</function> is similar to
|
|
<function>forward(host, port)</function>.
|
|
</para>
|
|
<para>
|
|
In the forward to uri case (<function>t_relay()</function>), if the
|
|
original URI was rewritten (by UsrLoc, RR, strip/prefix, etc.) the new
|
|
URI will be taken). The destination (including the protocol) is
|
|
determined from the uri, using SIP specific DNS resolving if needed
|
|
(NAPTR, SRV a.s.o depending also on the dns options).
|
|
</para>
|
|
<para>
|
|
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>
|
|
...
|
|
if (!t_relay())
|
|
{
|
|
sl_reply_error();
|
|
break;
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_relay_to_udp">
|
|
<title>
|
|
<function>t_relay_to_udp([ip, port])</function>
|
|
</title>
|
|
<para>
|
|
Relay a message statefully using a fixed protocol either to the
|
|
specified fixed destination or to a destination derived from the
|
|
message uri (if the host address and port are not specified).
|
|
These along with
|
|
<function>t_relay</function> are the functions 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>
|
|
<para>If no parameters are specified the message is sent to a destination
|
|
derived from the message uri (using sip sepcific DNS lookups), but with
|
|
the protocol corresponding to the function name.</para>
|
|
<example>
|
|
<title><function>t_relay_to_udp</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (src_ip==10.0.0.0/8)
|
|
t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
|
|
else
|
|
t_relay_to_tcp(); # relay to msg. uri, but over tcp
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_relay_to_tcp">
|
|
<title>
|
|
<function>t_relay_to_tcp([ip, port])</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_relay_to_udp([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_relay_to_tls">
|
|
<title>
|
|
<function>t_relay_to_tls([ip, port])</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_relay_to_udp([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_relay_to_sctp">
|
|
<title>
|
|
<function>t_relay_to_sctp([ip, port])</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_relay_to_udp([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_on_failure">
|
|
<title>
|
|
<function>t_on_failure(failure_route)</function>
|
|
</title>
|
|
<para>
|
|
Sets failure 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
|
|
"202 I will take care of it"). Note that the set of
|
|
commands which are usable within failure_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 failure_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>failure_route</emphasis> - Failure route block to be called.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_on_failure</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
t_on_failure("1");
|
|
t_relay();
|
|
}
|
|
|
|
failure_route[1] {
|
|
revert_uri();
|
|
setuser("voicemail");
|
|
append_branch();
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See <filename>test/onr.cfg</filename> for a more complex example of
|
|
combination of serial with parallel forking.
|
|
</para>
|
|
</section>
|
|
<section id="tm.f.t_on_branch_failure">
|
|
<title>
|
|
<function>t_on_branch_failure(branch_failure_route)</function>
|
|
</title>
|
|
<para>
|
|
Sets the branch_failure routing block, to which control is passed on each
|
|
negative response to a transaction. This route is run before deciding if
|
|
the transaction is complete. In the referred block, you can start a new
|
|
branch which is required for failover of multiple outbound flows (RFC 5626).
|
|
Note that the set of commands which are usable within a branch_failure route
|
|
is limited to a subset of the failure_route commands including logging,
|
|
rewriting URI and initiating new branches. Any other commands may generate
|
|
errors or result in unpredictable behavior.
|
|
Note that whenever failure_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>Function Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>branch_failure_route</emphasis> - Name of the branch_failure route
|
|
block to be called (it is prefixed internally with 'tm:branch-failure:').
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_on_branch_failure</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
t_on_branch_failure("myroute");
|
|
t_relay();
|
|
}
|
|
|
|
event_route[tm:branch-failure:myroute] {
|
|
if (t_check_status("430|403") {
|
|
unregister("location", "$tu", "$T_reply_ruid");
|
|
}
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_on_reply">
|
|
<title>
|
|
<function>t_on_reply(onreply_route)</function>
|
|
</title>
|
|
<para>
|
|
Sets the reply routing block, to which control is passed when a
|
|
reply for the current transaction is received.
|
|
Note that the set of commands which are usable within onreply_routes is
|
|
limited.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>onreply_route</emphasis> - Onreply route block to be
|
|
called.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_on_reply</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
loadmodule "/usr/local/lib/ser/modules/nathelper.so"
|
|
...
|
|
route {
|
|
/* if natted */
|
|
t_on_reply("1");
|
|
t_relay();
|
|
}
|
|
|
|
onreply_route[1] {
|
|
if (status=~ "(183)|2[0-9][0-9]"){
|
|
force_rtp_proxy();
|
|
search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=yes');
|
|
}
|
|
if (nat_uac_test("1")){
|
|
fix_nated_contact();
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_on_branch">
|
|
<title>
|
|
<function>t_on_branch(branch_route)</function>
|
|
</title>
|
|
<para>
|
|
Sets the branch routing block, to which control is passed after
|
|
forking (when a new branch is created). For now branch routes
|
|
are intended only for last minute changes of the SIP messages
|
|
(like adding new headers).
|
|
Note that the set of commands which are usable within branch_routes is
|
|
very limited. It is not possible to generate a reply.
|
|
</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>
|
|
<example>
|
|
<title><function>t_on_branch</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
t_on_branch("1");
|
|
t_relay();
|
|
}
|
|
|
|
branch_route[1] {
|
|
if (uri=~"sip:[0-9]+"){
|
|
append_hf("P-Warn: numeric uri\r\n");
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_newtran">
|
|
<title>
|
|
<function>t_newtran()</function>
|
|
</title>
|
|
<para>
|
|
Creates a new transaction, returns a negative value on error. This
|
|
is the only way a script can add a new transaction in an atomic
|
|
way. Typically, it is used to deploy a UAS.
|
|
</para>
|
|
<example>
|
|
<title><function>t_newtran</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (t_newtran()) {
|
|
log("UAS logic");
|
|
t_reply("999","hello");
|
|
} else sl_reply_error();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See test/uas.cfg for more examples.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_reply">
|
|
<title>
|
|
<function>t_reply(code, reason_phrase)</function>
|
|
</title>
|
|
<para>
|
|
Sends a stateful reply after a transaction has been
|
|
established. See <function>t_newtran</function> for usage.
|
|
</para>
|
|
<para>
|
|
If the code is in the range 300-399 (redirect reply), the current
|
|
destination set is appended to the reply as Contact headers.
|
|
The destination set contains the request URI (R-URI), if it is
|
|
modified compared to the received one, plus the branches added to the
|
|
request (e.g., after an append_branch() or lookup("location")).
|
|
If the R-URI was changed but it is not desired to be part of the
|
|
destination set, it can be reverted using the function revert_uri().
|
|
</para>
|
|
<para>
|
|
Custom headers to the reply can be added using append_to_reply()
|
|
function from textops module.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>code</emphasis> - Reply code number.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>reason_phrase</emphasis> - Reason string.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_reply</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_reply("404", "Not found");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_lookup_request">
|
|
<title>
|
|
<function>t_lookup_request()</function>
|
|
</title>
|
|
<para>
|
|
Checks if a transaction exists. Returns a positive value if so,
|
|
negative otherwise. Most likely you will not want to use it, as a
|
|
typical application of a look-up is to introduce a new transaction
|
|
if none was found. However this is safely (atomically) done using
|
|
<function>t_newtran</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_lookup_request</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (t_lookup_request()) {
|
|
...
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_retransmit_reply">
|
|
<title>
|
|
<function>t_retransmit_reply()</function>
|
|
</title>
|
|
<para>
|
|
Retransmits a reply sent previously by UAS transaction.
|
|
</para>
|
|
<example>
|
|
<title><function>t_retransmit_reply</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_retransmit_reply();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_release">
|
|
<title>
|
|
<function>t_release()</function>
|
|
</title>
|
|
<para>
|
|
Remove transaction from memory (it will be first put on a wait
|
|
timer to absorb delayed messages).
|
|
</para>
|
|
<example>
|
|
<title><function>t_release</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_release();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_forward_nonack">
|
|
<title>
|
|
<function>t_forward_nonack([ip, port])</function>
|
|
</title>
|
|
<para>
|
|
Mainly for internal usage -- forward a non-ACK request statefully.
|
|
Variants of this functions can enforce a specific transport protocol.
|
|
</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_forward_nonack</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_forward_nonack("1.2.3.4", "5060");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_forward_nonack_udp">
|
|
<title>
|
|
<function>t_forward_nonack_udp(ip, port)</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_forward_nonack([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_forward_nonack_tcp">
|
|
<title>
|
|
<function>t_forward_nonack_tcp(ip, port)</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_forward_nonack([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_forward_nonack_tls">
|
|
<title>
|
|
<function>t_forward_nonack_tls(ip, port)</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_forward_nonack([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_forward_nonack_sctp">
|
|
<title>
|
|
<function>t_forward_nonack_sctp(ip, port)</function>
|
|
</title>
|
|
<para>
|
|
See function <function>t_forward_nonack([ip, port])</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_fr">
|
|
<title>
|
|
<function>t_set_fr(fr_inv_timeout [, fr_timeout])</function>
|
|
</title>
|
|
<para>
|
|
Sets the fr_inv_timeout and optionally fr_timeout for the current
|
|
transaction or for transactions created during the same script
|
|
invocation, after calling this function.
|
|
If the transaction is already created (e.g called after
|
|
<function>t_relay()</function> or in an onreply_route) all the
|
|
branches will have their final response timeout updated on-the-fly.
|
|
If one of the parameters is 0, its value won't be changed.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>fr_inv_timeout</emphasis> - new final response timeout
|
|
(in milliseconds) for INVITEs. See also
|
|
<varname>fr_inv_timer</varname>.
|
|
</para>
|
|
<para><emphasis>fr_timeout</emphasis> - new final response timeout
|
|
(in milliseconds) for non-INVITE transaction, or INVITEs which
|
|
haven't received yet a provisional response. See also
|
|
<varname>fr_timer</varname>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
See also:
|
|
<varname>fr_timer</varname>,
|
|
<varname>fr_inv_timer</varname>,
|
|
<function>t_reset_fr()</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_fr</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
t_set_fr(10000); # set only fr invite timeout to 10s
|
|
t_on_branch("1");
|
|
t_relay();
|
|
}
|
|
|
|
branch_route[1] {
|
|
# if we are calling the pstn, extend the invite timeout to 50s
|
|
# for all the branches, and set the no-reply-received timeout to 2s
|
|
if (uri=~"sip:[0-9]+"){
|
|
t_set_fr(50000, 2000);
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_reset_fr">
|
|
<title>
|
|
<function>t_reset_fr()</function>
|
|
</title>
|
|
<para>
|
|
Resets the <varname>fr_inv_timer</varname> and
|
|
<varname>fr_timer</varname> for the current transaction to the default
|
|
values (set using the tm module parameters
|
|
<varname>fr_inv_timer</varname> and <varname>fr_timer</varname>).
|
|
</para>
|
|
<para>
|
|
It will effectively cancel any previous calls to
|
|
<function>t_set_fr</function> for the same transaction.
|
|
</para>
|
|
<para>
|
|
See also: <varname>fr_timer</varname>,
|
|
<varname>fr_inv_timer</varname>,
|
|
<function>t_set_fr</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_reset_fr</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
t_reset_fr();
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="tm.f.t_set_max_lifetime">
|
|
<title>
|
|
<function>t_set_max_lifetime(inv_lifetime, noninv_lifetime)</function>
|
|
</title>
|
|
<para>
|
|
Sets the maximum lifetime for the current INVITE or non-INVITE
|
|
transaction, or for transactions created during the same script
|
|
invocation, after calling this function (that's why it takes values
|
|
for both INVITE and non-INVITE).
|
|
If one of the parameters is 0, its value won't be changed.
|
|
</para>
|
|
<para>
|
|
It works as a per transaction <varname>max_inv_lifetime</varname> or
|
|
<varname>max_noninv_lifetime</varname>.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>inv_lifetime</emphasis> - maximum INVITE transaction
|
|
lifetime (in milliseconds). See also
|
|
<varname>max_inv_lifetime</varname>.
|
|
</para>
|
|
<para><emphasis>noninv_lifetime</emphasis> - maximum non-INVITE
|
|
transaction lifetime (in milliseconds).
|
|
See also <varname>max_noninv_lifetime</varname>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
See also: <varname>max_inv_lifetime</varname>,
|
|
<varname>max_noninv_lifetime</varname>,
|
|
<function>t_reset_max_lifetime</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_max_lifetime</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
if (src_ip=1.2.3.4)
|
|
t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
|
|
else
|
|
t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
|
|
# the current transaction is an
|
|
# INVITE and to 15s if not
|
|
}
|
|
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_reset_max_lifetime">
|
|
<title>
|
|
<function>t_reset_max_lifetime()</function>
|
|
</title>
|
|
<para>
|
|
Resets the the maximum lifetime for the current INVITE or non-INVITE
|
|
transaction to the default value (set using the tm module parameter
|
|
<varname>max_inv_lifetime</varname> or
|
|
<varname>max_noninv_lifetime</varname>).
|
|
</para>
|
|
<para>
|
|
It will effectively cancel any previous calls to
|
|
<function>t_set_max_lifetime</function> for the same transaction.
|
|
</para>
|
|
<para>
|
|
See also: <varname>max_inv_lifetime</varname>,
|
|
<varname>max_noninv_lifetime</varname>,
|
|
<function>t_set_max_lifetime</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_reset_max_lifetime</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
t_reset_max_lifetime();
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_retr">
|
|
<title>
|
|
<function>t_set_retr(retr_t1_interval, retr_t2_interval)</function>
|
|
</title>
|
|
<para>
|
|
Sets the retr_t1_interval and retr_t2_interval for the current
|
|
transaction or for transactions created during the same script
|
|
invocation, after calling this function.
|
|
If one of the parameters is 0, it's value won't be changed.
|
|
If the transaction is already created (e.g called after
|
|
<function>t_relay()</function> or in an onreply_route) all the
|
|
existing branches will have their retransmissions intervals updated
|
|
on-the-fly:
|
|
if the retransmission interval for the branch has not yet reached T2
|
|
the interval will be reset to retr_t1_interval, else to
|
|
retr_t2_interval. Note that the change will happen after the current
|
|
interval expires (after the next retransmission, the next-next
|
|
retransmission will take place at retr_t1_interval or
|
|
retr_t2_interval).
|
|
All new branches of the same transaction will start with the new
|
|
values.
|
|
This function will work even if it's called in the script before
|
|
a transaction creating function (e.g.: t_set_retr(500, 4000);
|
|
t_relay()). All new transaction created after this function call,
|
|
during the same script invocation will use the new values.
|
|
Note that this function will work only if tm is compile with
|
|
-DTM_DIFF_RT_TIMEOUT (which increases every transaction size with
|
|
4 bytes).
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>retr_t1_interval</emphasis> - new T1 retransmission
|
|
interval (in milliseconds). See also
|
|
<varname>retr_t1_timeout</varname>.
|
|
</para>
|
|
<para><emphasis>retr_t2_interval</emphasis> - new T2 (or maximum)
|
|
retransmission interval (in milliseconds). See also
|
|
<varname>retr_t2_timeout</varname>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
See also:
|
|
<varname>retr_timer1</varname>,
|
|
<varname>retr_timer2</varname>,
|
|
<function>t_reset_retr()</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_retr</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
t_set_retr(250, 0); # set only T1 to 250 ms
|
|
t_on_branch("1");
|
|
t_relay();
|
|
}
|
|
|
|
branch_route[1] {
|
|
# if we are calling the a remote pstn, extend T1 and decrease T2
|
|
# for all the branches
|
|
if (uri=~"sip:[0-9]+"){
|
|
t_set_retr(500, 2000);
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="tm.f.t_reset_retr">
|
|
<title>
|
|
<function>t_reset_retr()</function>
|
|
</title>
|
|
<para>
|
|
Resets the <varname>retr_timer1</varname> and
|
|
<varname>retr_timer2</varname> for the current transaction to the
|
|
default values (set using the tm module parameters
|
|
<varname>retr_timer1</varname> and <varname>retr_timer2</varname>).
|
|
</para>
|
|
<para>
|
|
It will effectively cancel any previous calls to
|
|
<function>t_set_retr</function> for the same transaction.
|
|
</para>
|
|
<para>
|
|
See also: <varname>retr_timer1</varname>,
|
|
<varname>retr_timer2</varname>,
|
|
<function>t_set_retr</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_reset_retr</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
t_reset_retr();
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_auto_inv_100">
|
|
<title>
|
|
<function>t_set_auto_inv_100(0|1)</function>
|
|
</title>
|
|
<para>
|
|
Switch automatically sending 100 replies to INVITEs on/off on a
|
|
per transaction basis. It overrides the
|
|
<varname>auto_inv_100</varname> value for the current transaction.
|
|
</para>
|
|
<para>
|
|
See also: <varname>auto_inv_100</varname>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_auto_inv_100</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
if (src_ip==1.2.3.0/24)
|
|
t_set_auto_inv_100(0); # turn off automatic 100 replies
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_branch_timeout">
|
|
<title>
|
|
<function>t_branch_timeout()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the failure route is executed for a branch that did
|
|
timeout. It can be used from
|
|
<emphasis>failure_route</emphasis> and
|
|
<emphasis>branch-failure</emphasis> event route.
|
|
</para>
|
|
<example>
|
|
<title><function>t_branch_timeout</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (t_branch_timeout()){
|
|
log("timeout\n");
|
|
# ...
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_branch_replied">
|
|
<title>
|
|
<function>t_branch_replied()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the failure route is executed for a branch that did
|
|
receive at least one reply in the past (the "current" reply is not
|
|
taken into account). It can be used from
|
|
<emphasis>failure_route</emphasis> and
|
|
<emphasis>branch-failure</emphasis> event route.
|
|
</para>
|
|
<example>
|
|
<title><function>t_branch_replied</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (t_branch_timeout()){
|
|
if (t_branch_replied())
|
|
log("timeout after receiving a reply (no answer?)\n");
|
|
else
|
|
log("timeout, remote side seems to be down\n");
|
|
# ...
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_any_timeout">
|
|
<title>
|
|
<function>t_any_timeout()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if at least one of the current transactions branches
|
|
did timeout.
|
|
</para>
|
|
<example>
|
|
<title><function>t_any_timeout</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (!t_branch_timeout()){
|
|
if (t_any_timeout()){
|
|
log("one branch did timeout\n");
|
|
sl_send_reply("408", "Timeout");
|
|
}
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_any_replied">
|
|
<title>
|
|
<function>t_any_replied()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if at least one of the current transactions branches
|
|
did receive some reply in the past. If called from a failure or
|
|
onreply route, the "current" reply is not taken into account.
|
|
</para>
|
|
<example>
|
|
<title><function>t_any_replied</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
onreply_route[0]{
|
|
if (!t_any_replied()){
|
|
log("first reply received\n");
|
|
# ...
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_grep_status">
|
|
<title>
|
|
<function>t_grep_status("code")</function>
|
|
</title>
|
|
<para>
|
|
Returns true if "code" is the final reply received (or locally
|
|
generated) in at least one of the current transactions branches.
|
|
</para>
|
|
<example>
|
|
<title><function>t_grep_status</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
onreply_route[0]{
|
|
if (t_grep_status("486")){
|
|
/* force a 486 reply, even if this is not the winning branch */
|
|
t_reply("486", "Busy");
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_is_canceled">
|
|
<title>
|
|
<function>t_is_canceled()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the current transaction was canceled.
|
|
</para>
|
|
<example>
|
|
<title><function>t_is_canceled</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (t_is_canceled()){
|
|
log("transaction canceled\n");
|
|
# ...
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_is_expired">
|
|
<title>
|
|
<function>t_is_expired()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the current transaction has already been expired,
|
|
i.e. the max_inv_lifetime/max_noninv_lifetime interval has already
|
|
elapsed.
|
|
</para>
|
|
<example>
|
|
<title><function>t_is_expired</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (t_is_expired()){
|
|
log("transaction expired\n");
|
|
# There is no point in adding a new branch.
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_relay_cancel">
|
|
<title>
|
|
<function>t_relay_cancel()</function>
|
|
</title>
|
|
<para>
|
|
Forwards the CANCEL if the corresponding INVITE transaction
|
|
exists. The function is supposed to be used at the very
|
|
beginning of the script, because the CANCELs can be caught
|
|
and the rest of the script can be bypassed this way. Do not disable
|
|
<varname>reparse_invite</varname> module parameter, and call
|
|
<varname>t_relay_cancel()</varname> right after the sanity tests.
|
|
</para>
|
|
<para>
|
|
Return value is 0 (drop) if the corresponding INVITE was found
|
|
and the CANCELs were successfully sent to the pending branches,
|
|
true if the INVITE was not found, and false in case of any error.
|
|
</para>
|
|
<example>
|
|
<title><function>t_relay_cancel</function> usage</title>
|
|
<programlisting>
|
|
|
|
if (method == CANCEL) {
|
|
if (!t_relay_cancel()) { # implicit drop if relaying was successful,
|
|
# nothing to do
|
|
|
|
# corresponding INVITE transaction found but error occurred
|
|
sl_reply("500", "Internal Server Error");
|
|
drop;
|
|
}
|
|
# bad luck, corresponding INVITE transaction is missing,
|
|
# do the same as for INVITEs
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_lookup_cancel">
|
|
<title>
|
|
<function>t_lookup_cancel([1])</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the corresponding INVITE transaction exists
|
|
for a CANCEL request. The function can be called at the beginning
|
|
of the script to check whether or not the CANCEL can be immediately
|
|
forwarded bypassing the rest of the script. Note however that
|
|
<function>t_relay_cancel</function> includes
|
|
<function>t_lookup_cancel</function> as well, therefore it is not
|
|
needed to explicitly call this function unless something has to be
|
|
logged for example.
|
|
</para>
|
|
<para>
|
|
If the function parameter (optional) is set to 1, the message flags
|
|
are overwritten with the flags of the INVITE. isflagset() can be used
|
|
to check the flags of the previously forwarded INVITE in this case.
|
|
</para>
|
|
<example>
|
|
<title><function>t_lookup_cancel</function> usage</title>
|
|
<programlisting>
|
|
|
|
if (method == CANCEL) {
|
|
if (t_lookup_cancel()) {
|
|
log("INVITE transaction exists");
|
|
if (!t_relay_cancel()) { # implicit drop if
|
|
# relaying was successful,
|
|
# nothing to do
|
|
|
|
# corresponding INVITE transaction found
|
|
# but error occurred
|
|
sl_reply("500", "Internal Server Error");
|
|
drop;
|
|
}
|
|
}
|
|
# bad luck, corresponding INVITE transaction is missing,
|
|
# do the same as for INVITEs
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_drop_replies">
|
|
<title>
|
|
<function>t_drop_replies([mode])</function>
|
|
</title>
|
|
<para>
|
|
Drops all the previously received replies in failure_route
|
|
block to make sure that none of them is picked up again.
|
|
</para>
|
|
<para>
|
|
The parameter 'mode' controls which replies are dropped: 'a'
|
|
or missing - all replies are dropped; 'l' - replies received for
|
|
last set of branches are dropped; 'n' - no reply is dropped.
|
|
</para>
|
|
<para>
|
|
Dropping replies works only if a new branch is added to the
|
|
transaction, or it is explicitly replied in the script!
|
|
</para>
|
|
<example>
|
|
<title><function>t_drop_replies()</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
failure_route[0]{
|
|
if (t_check_status("5[0-9][0-9]")){
|
|
# I do not like the 5xx responses,
|
|
# so I give another chance to "foobar.com",
|
|
# and I drop all the replies to make sure that
|
|
# they are not forwarded to the caller.
|
|
t_drop_replies();
|
|
|
|
rewritehostport("foobar.com");
|
|
append_branch();
|
|
t_relay();
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_save_lumps">
|
|
<title>
|
|
<function>t_save_lumps()</function>
|
|
</title>
|
|
<para>
|
|
Forces the modifications of the processed SIP message
|
|
to be saved in shared memory before t_relay() is called.
|
|
The new branches which are created in failure_route will
|
|
contain the same modifications, and any other modification
|
|
after t_save_lumps() will be lost.
|
|
</para>
|
|
<para>
|
|
Note that t_relay() automatically saves the modifications
|
|
when it is called the first time, there is no need for
|
|
t_save_lumps() unless message changes between t_save_lumps()
|
|
and t_relay() must not be propagated to failure_route.
|
|
</para>
|
|
<para>
|
|
The transaction must be created by t_newtran() before
|
|
calling t_save_lumps().
|
|
</para>
|
|
<example>
|
|
<title><function>t_save_lumps()</function> usage</title>
|
|
<programlisting>
|
|
route {
|
|
...
|
|
t_newtran();
|
|
append_hf("hf1: my first header\r\n");
|
|
...
|
|
t_save_lumps();
|
|
append_hf("hf2: my second header\r\n");
|
|
...
|
|
t_on_failure("1");
|
|
t_relay();
|
|
}
|
|
|
|
failure_route[1] {
|
|
append_branch();
|
|
append_hf("hf3: my third header\r\n");
|
|
#
|
|
# This branch contains hf1 and hf3, but does
|
|
# not contain hf2 header.
|
|
# hf2 would be also present here without
|
|
# t_save_lumps().
|
|
...
|
|
t_relay();
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_load_contacts">
|
|
<title>
|
|
<function moreinfo="none">t_load_contacts()</function>
|
|
</title>
|
|
<para>
|
|
This is the first of the three functions that can be used
|
|
to implement
|
|
serial/parallel forking based on q and +sip.instance
|
|
values of individual branches in the destination set.
|
|
</para>
|
|
<para>
|
|
Function <function>t_load_contacts()</function> removes
|
|
all branches from the current destination set and stores
|
|
them into the XAVP whose name is configured with the
|
|
parameter <varname>contacts_avp</varname>.
|
|
Note that you have to
|
|
configure this parameter before you can use the function, the
|
|
parameter is set to NULL by default, which disables
|
|
the function.
|
|
</para>
|
|
<para>
|
|
If the destination set contains only one branch,
|
|
the function does nothing.
|
|
</para>
|
|
<para>
|
|
If the current destination set contains more than one branch,
|
|
the function sorts them
|
|
according to increasing value of the q parameter and
|
|
then stores the branches in reverse order into the XAVP.
|
|
</para>
|
|
<para>
|
|
The q parameter of a branch contains a value from range 0-1.0
|
|
and it expresses relative preferrence of the branch
|
|
among all branches in the destination set.
|
|
The higher the q value the more preference the
|
|
user agent gave to the branch. Branches with higher q
|
|
values will be tried before branches with lower ones
|
|
when serial forking takes place.
|
|
</para>
|
|
<para>
|
|
After calling <function>t_load_contacts()</function>, function
|
|
<function>t_next_contacts()</function> and possibly
|
|
also <function>t_next_contact_flow()</function> need
|
|
to be called
|
|
one or more times in order to retrieve the branches based
|
|
on their q value.
|
|
</para>
|
|
<para>
|
|
Function returns 1 if loading of contacts succeeded or
|
|
there was nothing to do. In case of an error,
|
|
function returns -1 (see syslog).
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>t_load_contacts</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!t_load_contacts()) {
|
|
sl_send_reply("500", "Server Internal Error - Cannot load contacts");
|
|
exit;
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_next_contacts">
|
|
<title>
|
|
<function moreinfo="none">t_next_contacts()</function>
|
|
</title>
|
|
<para>
|
|
Function <function>t_next_contacts()</function> is the
|
|
second of the three functions that can be used to
|
|
implement serial/parallel
|
|
forking based on the q value of the individual branches
|
|
in a destination set.
|
|
</para>
|
|
<para>
|
|
The function adds to request a new destination set that
|
|
includes the highest priority contacts in contacts_avp,
|
|
but only one contact with the same +sip.instance value is
|
|
included. Duplicate contacts are added to contact_flows_avp
|
|
for later consumption by function
|
|
<function>next_contact_flow()</function>.
|
|
Upon each call, Request URI is rewritten with
|
|
the first contact and the remaining contacts (if any) are
|
|
added as branches. Then all highest priority contacts
|
|
are removed from contacts_avp.
|
|
</para>
|
|
<para>
|
|
Function does nothing if <varname>contact_avp</varname> has
|
|
no values.
|
|
</para>
|
|
<para>
|
|
Function returns 1 if contacts_avp was not empty and a
|
|
destination set was successfully added,
|
|
returns -2 if contacts_avp was empty and thus there was
|
|
nothing to do, and returns -1 in case of an error (see
|
|
syslog).
|
|
Function can be called from REQUEST_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<para>
|
|
Note that if you use <function>t_load_contacts</function>
|
|
and <function>t_next_contacts</function> functions then
|
|
you should also set the value of
|
|
<varname>restart_fr_on_each_reply</varname>
|
|
parameter to 0. If you do not do that, it can
|
|
happen that a
|
|
broken user agent that retransmits 180 periodically will keep
|
|
resetting the fr_inv_timer value and serial
|
|
forking never happens.
|
|
</para>
|
|
<para>
|
|
Before calling t_relay(), you can check if the
|
|
previous call of <function>next_contacts()</function>
|
|
consumed all branches
|
|
by checking if <varname>contact_avp</varname> and
|
|
<varname>contact_flows_avp</varname> are not anymore set.
|
|
Based on
|
|
that test, you can then use t_set_fr() function to set
|
|
timers according to your needs.
|
|
</para>
|
|
<example>
|
|
<title><function>t_next_contacts</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# First call after t_load_contacts() when transaction does not exist yet
|
|
# and contacts should be available
|
|
if (!t_next_contacts()) {
|
|
sl_send_reply("500", "Server Internal Error - Cannot get contacts");
|
|
} else {
|
|
t_relay();
|
|
};
|
|
...
|
|
# Following call, when transaction exists and there may or may not be
|
|
# contacts left
|
|
if (!t_next_contacts()) {
|
|
t_reply("408", "Request Timeout");
|
|
} else {
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_next_contact_flow">
|
|
<title>
|
|
<function moreinfo="none">t_next_contact_flow()</function>
|
|
</title>
|
|
<para>
|
|
Function <function>t_next_contact_flow()</function>
|
|
is the last of the three functions that can be used to
|
|
implement serial/parallel forking based on the q value
|
|
and instance value of individual branches in a destination set.
|
|
</para>
|
|
<para>
|
|
Function adds a new branch to the request that includes
|
|
the first contact from <varname>contact_flows_avp</varname>
|
|
that matches the +sip.instance value of the flow that has failed.
|
|
Upon each call, Request URI is rewritten with the contact. The
|
|
used contact is removed from <varname>contact_flows_avp</varname>.
|
|
</para>
|
|
<para>
|
|
Function does nothing if there are
|
|
no <varname>contact_flows_avp</varname> values.
|
|
</para>
|
|
<para>
|
|
Function returns 1 if <varname>contact_flows_avp</varname>
|
|
was not empty and a destination set was successfully added,
|
|
returns -2 if <varname>contacts_avp</varname>
|
|
was empty and thus there was
|
|
nothing to do, and returns -1 in case of an error (see
|
|
syslog).
|
|
This function can be used from a BRANCH_FAILURE event route.
|
|
</para>
|
|
<example>
|
|
<title><function>t_next_contact_flow</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
event_route[tm:branch-failure:outbound]
|
|
{
|
|
if (t_next_contact_flow())
|
|
{
|
|
t_relay();
|
|
} else {
|
|
xlog("L_INFO", "No more flows\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_check_status">
|
|
<title>
|
|
<function moreinfo="none">t_check_status(re)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the regular 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 ANY_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 id="tm.f.t_check_trans">
|
|
<title>
|
|
<function>t_check_trans()</function>
|
|
</title>
|
|
<para>
|
|
<function>t_check_trans()</function> can be used to quickly check if
|
|
a message belongs or is related to a transaction. It behaves
|
|
differently for different types of messages:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>For a SIP Reply it returns true if the reply belongs to
|
|
an existing transaction and false otherwise.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>For a CANCEL it behaves exactly as
|
|
<function>t_lookup_cancel()</function>: returns true if a
|
|
corresponding INVITE transaction exists for the CANCEL and
|
|
false otherwise.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>For ACKs to negative replies or for ACKs to local
|
|
transactions it will terminate the script if the ACK belongs
|
|
to a transaction (it would make very little sense to process
|
|
an ACK to a negative reply for an existing transaction in
|
|
some other way then to simply pass it to tm) or return false
|
|
if not.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>For end-to-end ACKs (ACKs to 2xx responses for forwarded
|
|
INVITE transactions) it will return true if the corresponding
|
|
INVITE transaction is found and still active and false if not.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Note that the e2e ACK matching is more of a hint
|
|
then a certainty. A delayed e2e ACK might arrive after the
|
|
transaction wait time elapses, when the INVITE transaction no
|
|
longer exists and thus would not match anything. There are
|
|
also cases when tm would not keep all the information needed
|
|
for e2e ACK matching (since this is not needed for a statefull
|
|
proxy and it requires additional memory, tm will not keep this
|
|
information unless needed by some other module or callbacks).
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>For other requests (non ACKs and non CANCELs), in case of
|
|
a retransmission matching a transaction, it resends the last
|
|
reply for that transaction and terminates the config execution.
|
|
Otherwise, it returns false (in case of new requests for which
|
|
no transaction exists yet).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<note><para>
|
|
An important difference from kamailio version is that for an ACK to
|
|
negative reply or for a local transaction, the script execution will be
|
|
immediately stopped and the message handled by tm, instead of returning
|
|
true.
|
|
</para></note>
|
|
<para><function>t_check_trans()</function> functionality for requests,
|
|
except for the e2e ACK matching, can be replicated in the script
|
|
using <function>t_lookup_cancel()</function> and
|
|
<function>t_lookup_request()</function>.
|
|
</para>
|
|
<para>See also: <function>t_lookup_request()</function>,
|
|
<function>t_lookup_cancel()</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_check_trans</function> usage</title>
|
|
<programlisting>
|
|
|
|
if ( method == "CANCEL" && !t_check_trans())
|
|
sl_reply("403", "cancel out of the blue forbidden");
|
|
# note: in this example t_check_trans() can be replaced by t_lookup_cancel()
|
|
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_disable_6xx">
|
|
<title>
|
|
<function>t_set_disable_6xx(0|1)</function>
|
|
</title>
|
|
<para>
|
|
Turn off/on 6xx replies special rfc conformant handling on a per
|
|
transaction basis. If turned off
|
|
(<function>t_set_disable_6xx("1")</function>) 6XXs will be treated
|
|
like normal replies.
|
|
</para>
|
|
<para>
|
|
It overrides the <varname>disable_6xx_block</varname> value for
|
|
the current transaction.
|
|
</para>
|
|
<para>
|
|
See also: <varname>disable_6xx_block</varname>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_disable_6xx</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
if (src_ip==1.2.3.4) # bad user agent that sends 603
|
|
t_set_disable_6xx(1); # turn off 6xx special handling
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_disable_failover">
|
|
<title>
|
|
<function>t_set_disable_failover(0|1)</function>
|
|
</title>
|
|
<para>
|
|
Turn off/on dns failover on a per transaction basis.
|
|
</para>
|
|
<para>
|
|
See also: <varname>use_dns_failover</varname>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_disable_failover</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
if (uri=~"@foo.bar$")
|
|
t_set_disable_failover(1); # turn off dns failover
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_set_disable_internal_reply">
|
|
<title>
|
|
<function>t_set_disable_internal_reply(0|1)</function>
|
|
</title>
|
|
<para>
|
|
Turn off/on sending internally a SIP reply in case of relay errors.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_disable_internal_reply</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_set_disable_internal_reply(1); # turn off sending internal reply on error
|
|
if(!t_relay()) {
|
|
send_reply("500", "Server error");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_replicate">
|
|
<title>
|
|
<function>t_replicate([params])</function>
|
|
</title>
|
|
<para>
|
|
Replicate the SIP request to a specific address.
|
|
</para>
|
|
<para>
|
|
There are several function prototypes:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<function>t_replicate([uri])</function>,
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate(host, port)</function>,
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate_udp(host, port)</function>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate_tcp(host, port)</function>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate_tls(host, port)</function>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate_sctp(host, port)</function>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_replicate_to(proto, hostport)</function>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>uri</emphasis> - SIP URI where the message should be sent.
|
|
It can be given via a script variable. It is optional - when missing, the
|
|
dst-uri or r-uri are used as next hop address.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>host</emphasis> - host address where the message should be sent.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>port</emphasis> - port number.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>proto</emphasis> - transport protocol to be used.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>hostport</emphasis> - address in "host:port" format. It can be
|
|
given via an AVP.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_replicate</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# sent to 1.2.3.4:5060 over tcp
|
|
t_replicate("sip:1.2.3.4:5060;transport=tcp");
|
|
|
|
# sent to 1.2.3.4:5061 over tls
|
|
$var(h) = "1.2.3.4:5061";
|
|
t_replicate("sip:$var(h);transport=tls");
|
|
|
|
# sent to 1.2.3.4:5060 over udp
|
|
t_replicate_to_udp("1.2.3.4", "5060");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="tm.f.t_relay_to">
|
|
<title>
|
|
<function>t_relay_to(proxy, flags)</function>
|
|
</title>
|
|
<para>
|
|
Forward the SIP request to a specific address, controlling internal
|
|
behavior via flags.
|
|
</para>
|
|
<para>
|
|
There are several function prototypes:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<function>t_relay_to()</function>,
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_relay_to(proxy)</function>,
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_relay_to(flags)</function>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<function>t_relay_to(proxy, flags)</function>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>proxy</emphasis> - address where the request should
|
|
be sent. Format is: "proto:host:port" - any of proto or port can be
|
|
ommitted, along with the semicolon after or before.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>flags</emphasis> - bitmask integer value to control
|
|
the internal behavior. Bits can be:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>0x01</emphasis> - do not generate 100 reply.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>0x02</emphasis> - do not generate reply on internal
|
|
error.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>0x04</emphasis> - disable dns failover.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_relay_to</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# sent to 1.2.3.4:5060 over tcp
|
|
t_relay_to("tcp:1.2.3.4:5060");
|
|
|
|
# sent to 1.2.3.4 over tls
|
|
t_relay_to("tls:1.2.3.4");
|
|
|
|
# sent to dst URI or R-URI without a 100 reply
|
|
t_relay_to("0x01");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="tm.f.t_set_no_e2e_cancel_reason">
|
|
<title>
|
|
<function>t_set_no_e2e_cancel_reason(0|1)</function>
|
|
</title>
|
|
<para>
|
|
Enables/disables reason header (RFC 3326) copying from the triggering
|
|
received CANCEL to the generated hop-by-hop CANCEL. 0 enables and
|
|
1 disables.
|
|
</para>
|
|
<para>
|
|
It overrides the <varname>e2e_cancel_reason</varname> setting (module
|
|
parameter) for the current transaction.
|
|
</para>
|
|
<para>
|
|
Note: the function has to be used when processing the INVITE
|
|
(not when processing the CANCEL).
|
|
</para>
|
|
<para>
|
|
See also: <varname>e2e_cancel_reason</varname>.
|
|
</para>
|
|
<example>
|
|
<title><function>t_set_no_e2e_cancel_reason</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
route {
|
|
...
|
|
if (src_ip!=10.0.0.0/8) # don't trust CANCELs from the outside
|
|
t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header copying
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_is_set">
|
|
<title>
|
|
<function>t_is_set(target)</function>
|
|
</title>
|
|
<para>
|
|
Return true if the attribute specified by 'target' is set for transaction.
|
|
</para>
|
|
<para>The target parameter can be:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>branch_route</emphasis> - the function returns true if a
|
|
branch route is set to be executed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>failure_route</emphasis> - the function returns true if a
|
|
failure route is set to be executed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>onreply_route</emphasis> - the function returns true if an
|
|
onreply route is set to be executed.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_replicate</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if(!t_is_set("failure_route"))
|
|
LM_DBG("no failure route will be executed for current transaction\n");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tm.f.t_use_uac_headers">
|
|
<title>
|
|
<function>t_use_uac_headers()</function>
|
|
</title>
|
|
<para>
|
|
Set internal flags to tell tm to use UAC side for building headers for
|
|
local generated requests (ACK, CANCEL) - useful when changing From/To
|
|
headers using other functions than uac_replace_[from|to]().
|
|
</para>
|
|
<para>It returns true.</para>
|
|
<example>
|
|
<title><function>t_use_uac_headers</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
t_use_uac_headers();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="tm.f.t_is_retr_async_reply">
|
|
<title>
|
|
<function>t_is_retr_async_reply()</function>
|
|
</title>
|
|
<para>
|
|
Check to see if the reply is a retransmitted reply on a transaction that is
|
|
currently suspended asynchronously (suspended during reply processing). Right now the check is only on the
|
|
transaction, we don't actually check to see if the reply message is an actual
|
|
retransmission of the suspended reply. This is expected as you should not process
|
|
another reply until the suspended reply processing has been completed. The trick here
|
|
is to make sure you don't suspend for too long or even worse, indefinitely.
|
|
</para>
|
|
<para>returns true if the transaction is currently reply suspended or false if not.</para>
|
|
<example>
|
|
<title><function>t_is_retr_async_reply</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (t_is_retr_async_reply()) {
|
|
xlog("L_DBG", "Dropping retransmitted reply which is still currently suspended\n");
|
|
drop();
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|