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.
1496 lines
42 KiB
1496 lines
42 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>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
</sectioninfo>
|
|
|
|
<title>Functions</title>
|
|
|
|
<section id="t_relay_to_udp">
|
|
<title>
|
|
<function>t_relay_to_udp(ip, port)</function>,
|
|
<function>t_relay_to_udp()</function>,
|
|
<function>t_relay_to_tcp(ip, port)</function>
|
|
<function>t_relay_to_tcp()</function>
|
|
<function>t_relay_to_tls(ip, port)</function>
|
|
<function>t_relay_to_tls()</function>
|
|
<function>t_relay_to_sctp(ip, port)</function>
|
|
<function>t_relay_to_sctp()</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="t_relay">
|
|
<title>
|
|
<function>t_relay()</function>
|
|
<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(uri:host, uri:port)</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="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="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="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="append_branch">
|
|
<title>
|
|
<function>append_branch()</function>
|
|
</title>
|
|
<para>
|
|
Similarly to <function>t_fork_to</function>, it extends destination
|
|
set by a new entry. The difference is that current URI is taken
|
|
as new entry.
|
|
</para>
|
|
<example>
|
|
<title><function>append_branch</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
set_user("john");
|
|
t_fork();
|
|
set_user("alice");
|
|
t_fork();
|
|
t_relay();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="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="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>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="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="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="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="t_forward_nonack">
|
|
<title>
|
|
<function>t_forward_nonack()</function>
|
|
<function>t_forward_nonack(ip, port)</function>
|
|
<function>t_forward_nonack_udp(ip, port)</function>
|
|
<function>t_forward_nonack_tcp(ip, port)</function>
|
|
<function>t_forward_nonack_tls(ip, port)</function>
|
|
<function>t_forward_nonack_sctp(ip, port)</function>
|
|
</title>
|
|
<para>
|
|
mainly for internal usage--forward a non-ACK request statefully.
|
|
</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="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="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="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="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="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="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="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="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 only from the
|
|
<emphasis>failure_route</emphasis>.
|
|
</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="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 only from the
|
|
<emphasis>failure_route</emphasis>.
|
|
</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="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="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="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="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="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="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="t_lookup_cancel">
|
|
<title>
|
|
<function>t_lookup_cancel()</function>,
|
|
<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="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="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>
|
|
<title>
|
|
<function moreinfo="none">t_load_contacts()</function>
|
|
</title>
|
|
<para>
|
|
This is the first of the two functions that can be used to implement
|
|
serial/parallel forking based on the q value of individual branches
|
|
in a destination set.
|
|
</para>
|
|
<para>
|
|
The function <function>t_load_contacts()</function> takes all
|
|
branches from the current destination set and encodes them into the
|
|
AVP whose name or ID 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 Request-URI) or
|
|
if all branches have the same q value then the function does nothing
|
|
to minimize performance impact. In such case all branches should be
|
|
tried in parallel and that is the default mode of operation of
|
|
functions like <function>t_relay()</function>, so there is no need
|
|
to create the AVP or sort the branches.
|
|
</para>
|
|
<para>
|
|
If the current destination set contains more than one branch and not
|
|
all branches have the same q value then the function sorts them
|
|
according to the increasing value of the q parameter. The resulting
|
|
sorted list of branches is then encoded into the AVP.
|
|
</para>
|
|
<para>
|
|
The q parameter contains a value from a range of 0 to 1.0 and it
|
|
expresses relative preferrence of the branch among all branches in
|
|
the destination set. The higher the q value the more preferrence the
|
|
user agent gave to the branch. Branches with higher q values will be
|
|
tried first when serial forking takes place.
|
|
</para>
|
|
<para>
|
|
After that the function clears all branches and you have to
|
|
call <function>t_next_contacts</function> to retrieve them sorted
|
|
according to their q value. Note that if you
|
|
use <function>t_load_contacts</function> then you also have to
|
|
use <function>t_next_contacts</function> before
|
|
calling <function>t_relay</function>.
|
|
</para>
|
|
<para>
|
|
The AVP created by the function may contain multiple values, with
|
|
one encoded branch per value. The first value will contain the
|
|
branch with the highest q value. Each value contains the
|
|
Request-URI, the destination URI, the path vector, the outgoing
|
|
socket description and branch flags. All these fields are delimited
|
|
with the LF character.
|
|
</para>
|
|
<para>
|
|
The function returns 1 if loading of contacts succeeded or there was
|
|
nothing to do. Returns -1 on error (see syslog).
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_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>
|
|
<title>
|
|
<function moreinfo="none">t_next_contacts()</function>
|
|
</title>
|
|
<para>
|
|
The function <function>t_next_contacts</function> is the second of
|
|
the two functions that can be used to implement serial/parallel
|
|
forking based on the q value of individual branches in a destination
|
|
set.
|
|
</para>
|
|
<para>
|
|
This function takes the contact_avp created
|
|
by <function>t_load_contacts</function> and extracts
|
|
branches with
|
|
highest q value from it into the destination set when
|
|
called for the
|
|
first time. When you call the function second time it extracts
|
|
branches with lower q value, and so on until all branches have been
|
|
extracted. At each call, Request URI is rewritten with
|
|
first branch and the remaining branches (if any) are
|
|
added as branches. Then these "used" branches are remove
|
|
from the AVP.
|
|
</para>
|
|
<para>
|
|
The function does nothing if there are
|
|
no <varname>contact_avp</varname> values.
|
|
</para>
|
|
<para>
|
|
The function returns 1 if the AVP was not empty and a
|
|
destination set was successfully added,
|
|
returns -2 if contact_avp 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 REQUEST_ROUTE and FAILURE_ROUTE.
|
|
</para>
|
|
<para>
|
|
Note that if use 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 then 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 next_contacts() consumed all branches
|
|
by checking if contact_avp is 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="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), it will
|
|
terminate the script for retransmissions and return false for
|
|
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="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="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="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_replicat_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.
|
|
</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="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 (NOTE: has no effect anymore).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>0x04</emphasis> - disable dns failover.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>t_replicate</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="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>
|
|
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>
|