$Revision$
$Date$

# Functions

## `t_relay_to_udp(ip, port)`, `t_relay_to_udp()`, `t_relay_to_tcp(ip, port)` `t_relay_to_tcp()` `t_relay_to_tls(ip, port)` `t_relay_to_tls()` `t_relay_to_sctp(ip, port)` `t_relay_to_sctp()`

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 `t_relay` are the functions most users want to use--all other are mostly for programming. Programmers interested in writing TM logic should review how t_relay is implemented in tm.c and how TM callbacks work.

Meaning of the parameters is as follows:

- ip - IP address where the message should be sent.

- port - Port number.

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.

### `t_relay_to_udp` usage

    ...
    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
    ...

## `t_relay()` `t_relay(host, port)`

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.

`t_relay()` is the statefull version for `forward(uri:host, uri:port)` while `t_relay(host, port)` is similar to `forward(host, port)`.

In the forward to uri case (`t_relay()`), 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).

Returns a negative value on failure--you may still want to send a negative reply upstream statelessly not to leave upstream UAC in lurch.

### `t_relay` usage

    ...
    if (!t_relay())
    {
        sl_reply_error();
        break;
    };
    ...

## `t_on_failure(failure_route)`

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 (`t_reply`). 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.

Meaning of the parameters is as follows:

- failure_route - Failure route block to be called.

### `t_on_failure` usage

    ...
    route {
        t_on_failure("1");
        t_relay();
    }

    failure_route[1] {
        revert_uri();
        setuser("voicemail");
        append_branch();
    }
    ...

See `test/onr.cfg` for a more complex example of combination of serial with parallel forking.

## `t_on_reply(onreply_route)`

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.

Meaning of the parameters is as follows:

- onreply_route - Onreply route block to be called.

### `t_on_reply` usage

    ...
    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();
    	}
    }

## `t_on_branch(branch_route)`

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 drop a message or generate a reply.

Meaning of the parameters is as follows:

- branch_route - branch route block to be called.

### `t_on_branch` usage

    ...
    route {
    	t_on_branch("1");
    	t_relay();
    }

    branch_route[1] {
    	if (uri=~"sip:[0-9]+"){
    		append_hf("P-Warn: numeric uri\r\n");
    	}
    }

## `append_branch()`

Similarly to `t_fork_to`, it extends destination set by a new entry. The difference is that current URI is taken as new entry.

### `append_branch` usage

    ...
    set_user("john");
    t_fork();
    set_user("alice");
    t_fork();
    t_relay();
    ...

## `t_newtran()`

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.

### `t_newtran` usage

    ...
    if (t_newtran()) {
        log("UAS logic");
        t_reply("999","hello");
    } else sl_reply_error();
    ...

See test/uas.cfg for more examples.

## `t_reply(code, reason_phrase)`

Sends a stateful reply after a transaction has been established. See `t_newtran` for usage.

Meaning of the parameters is as follows:

- code - Reply code number.

- reason_phrase - Reason string.

### `t_reply` usage

    ...
    t_reply("404", "Not found");
    ...

## `t_lookup_request()`

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 looku-up is to introduce a new transaction if none was found. However this is safely (atomically) done using `t_newtran`.

### `t_lookup_request` usage

    ...
    if (t_lookup_request()) {
        ...
    };
    ...

## `t_retransmit_reply()`

Retransmits a reply sent previously by UAS transaction.

### `t_retransmit_reply` usage

    ...
    t_retransmit_reply();
    ...

## `t_release()`

Remove transaction from memory (it will be first put on a wait timer to absorb delayed messages).

### `t_release` usage

    ...
    t_release();
    ...

## `t_forward_nonack()` `t_forward_nonack(ip, port)` `t_forward_nonack_udp(ip, port)` `t_forward_nonack_tcp(ip, port)` `t_forward_nonack_tls(ip, port)` `t_forward_nonack_sctp(ip, port)`

mainly for internal usage--forward a non-ACK request statefully.

Meaning of the parameters is as follows:

- ip - IP address where the message should be sent.

- port - Port number.

### `t_forward_nonack` usage

    ...
    t_forward_nonack("1.2.3.4", "5060");
    ...

## `t_set_fr(fr_inv_timeout [, fr_timeout])`

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 `t_relay()` 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.

Meaning of the parameters is as follows:

- fr_inv_timeout - new final response timeout (in milliseconds) for INVITEs. See also `fr_inv_timer`.

  fr_timeout - new final response timeout (in milliseconds) for non-INVITE transaction, or INVITEs which haven't received yet a provisional response. See also `fr_timer`.

See also: `fr_timer`, `fr_inv_timer`, `t_reset_fr()`.

### `t_set_fr` usage

    ...
    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);
    	}
    }

## `t_reset_fr()`

Resets the `fr_inv_timer` and `fr_timer` for the current transaction to the default values (set using the tm module parameters `fr_inv_timer` and `fr_timer`).

It will effectively cancel any previous calls to `t_set_fr` for the same transaction.

See also: `fr_timer`, `fr_inv_timer`, `t_set_fr`.

### `t_reset_fr` usage

    ...
    route {
    ...
    		t_reset_fr();
    ...
    }

## `t_set_max_lifetime(inv_lifetime, noninv_lifetime)`

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.

It works as a per transaction `max_inv_lifetime` or `max_noninv_lifetime`.

Meaning of the parameters is as follows:

- inv_lifetime - maximum INVITE transaction lifetime (in milliseconds). See also `max_inv_lifetime`.

  noninv_lifetime - maximum non-INVITE transaction lifetime (in milliseconds). See also `max_noninv_lifetime`.

See also: `max_inv_lifetime`, `max_noninv_lifetime`, `t_reset_max_lifetime`.

### `t_set_max_lifetime` usage

    ...
    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
    }

## `t_reset_max_lifetime()`

Resets the the maximum lifetime for the current INVITE or non-INVITE transaction to the default value (set using the tm module parameter `max_inv_lifetime` or `max_noninv_lifetime`).

It will effectively cancel any previous calls to `t_set_max_lifetime` for the same transaction.

See also: `max_inv_lifetime`, `max_noninv_lifetime`, `t_set_max_lifetime`.

### `t_reset_max_lifetime` usage

    ...
    route {
    ...
    		t_reset_max_lifetime();
    ...
    }

## `t_set_retr(retr_t1_interval, retr_t2_interval)`

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 `t_relay()` 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).

Meaning of the parameters is as follows:

- retr_t1_interval - new T1 retransmission interval (in milliseconds). See also `retr_t1_timeout`.

  retr_t2_interval - new T2 (or maximum) retransmission interval (in milliseconds). See also `retr_t2_timeout`.

See also: `retr_timer1`, `retr_timer2`, `t_reset_retr()`.

### `t_set_retr` usage

    ...
    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);
    	}
    }

## `t_reset_retr()`

Resets the `retr_timer1` and `retr_timer2` for the current transaction to the default values (set using the tm module parameters `retr_timer1` and `retr_timer2`).

It will effectively cancel any previous calls to `t_set_retr` for the same transaction.

See also: `retr_timer1`, `retr_timer2`, `t_set_retr`.

### `t_reset_retr` usage

    ...
    route {
    ...
    		t_reset_retr();
    ...
    }

## `t_set_auto_inv_100(0|1)`

Switch automatically sending 100 replies to INVITEs on/off on a per transaction basis. It overrides the `auto_inv_100` value for the current transaction.

See also: `auto_inv_100`.

### `t_set_auto_inv_100` usage

    ...
    route {
    ...
    	if (src_ip==1.2.3.0/24)
    		t_set_auto_inv_100(0); # turn off automatic 100 replies
    ...
    }

## `t_branch_timeout()`

Returns true if the failure route is executed for a branch that did timeout. It can be used only from the failure_route.

### `t_branch_timeout` usage

    ...
    failure_route[0]{
    	if (t_branch_timeout()){
    		log("timeout\n");
    		# ...
    	}
    }

## `t_branch_replied()`

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 failure_route.

### `t_branch_replied` usage

    ...
    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");
    		# ...
    	}
    }

## `t_any_timeout()`

Returns true if at least one of the current transactions branches did timeout.

### `t_any_timeout` usage

    ...
    failure_route[0]{
    	if (!t_branch_timeout()){
    		if (t_any_timeout()){
    			log("one branch did timeout\n");
    			sl_send_reply("408", "Timeout");
    		}
    	}
    }

## `t_any_replied()`

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.

### `t_any_replied` usage

    ...
    onreply_route[0]{
    	if (!t_any_replied()){
    		log("first reply received\n");
    		# ...
    	}
    }

## `t_grep_status("code")`

Returns true if "code" is the final reply received (or locally generated) in at least one of the current transactions branches.

### `t_grep_status` usage

    ...
    onreply_route[0]{
    	if (t_grep_status("486")){
    		/* force a 486 reply, even if this is not the winning branch */
    		t_reply("486", "Busy");
    	}
    }

## `t_is_canceled()`

Returns true if the current transaction was canceled.

### `t_is_canceled` usage

    ...
    failure_route[0]{
    	if (t_is_canceled()){
    		log("transaction canceled\n");
    		# ...
    	}
    }

## `t_is_expired()`

Returns true if the current transaction has already been expired, i.e. the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.

### `t_is_expired` usage

    ...
    failure_route[0]{
    	if (t_is_expired()){
    		log("transaction expired\n");
    		# There is no point in adding a new branch.
    	}
    }

## `t_relay_cancel()`

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 `reparse_invite` module parameter, and call `t_relay_cancel()` right after the sanity tests.

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.

### `t_relay_cancel` usage

    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
    }

## `t_lookup_cancel()`, `t_lookup_cancel(1)`

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 `t_relay_cancel` includes `t_lookup_cancel` as well, therefore it is not needed to explicitly call this function unless something has to be logged for example.

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.

### `t_lookup_cancel` usage

    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
    }

## `t_drop_replies()`

Drops all the previously received replies in failure_route block to make sure that none of them is picked up again. Works only if a new branch is added to the transaction, or it is explicitly replied in the script!

### `t_drop_replies()` usage

    ...
    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();
    	}
    }

## `t_save_lumps()`

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.

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.

The transaction must be created by t_newtran() before calling t_save_lumps().

### `t_save_lumps()` usage

    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();
    }