$Revision: 1.8 $
$Date: 2007/06/05 14:12:37 $

# Functions

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

Relay a message statefully to a fixed destination. This along with `t_relay` is the function 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.

### `t_relay_to_udp` usage

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

## `t_relay()`

Relay a message statefully to destination indicated in current URI. (If the original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the new URI will be taken). Returns a negative value on failure--you may still want to send a negative reply upstream statelessly not to leave upstream UAC in lurch.

### `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(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, it's 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`.

### `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_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`.

### `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_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_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_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
    }