1.1.1. Per-Branch flags

First what is the idea with the branch concept: branch route is a route to be execute separately for each branch before being sent out - changes in that route should reflect only on that branch.

There are two types of flags in OpenSER :

• global flags - global because they are visible everywhere in the transaction (in all routes and in all sequential replies/request).

• branch flags - flags that are visible only from a specific branch - in all replies and routes connected to this branch.

For example: I have a call parallel forking to GW and to a user. And I would like to know from which branch I will get the final negative reply (if so). I will set a branch route before relaying the calls (with the 2 branches). The branch route will be separately executed for each branch; in the branch going to GW (I can identified it by looking to RURI), I will set a branch flag. This flag will appear only in the onreply route run for replied from GW. It will be also be visible in failure route if the final elected reply belongs to the GW branch. This flags will not be visible in the other branch (in routes executing replies from the other branch).

For how to define branch flags and use via script, see Section 1.3.17 and Section 1.4.18.

Also, modules may set branch flags before transaction creation (for the moment this feature is not available in script). The REGISTRAR module is the first to use this feature. If the "use_branch_flags" param is enabled, the NAT flag will be push in branch flags instead in message flags - IMPORTANT: be sure that NAT flag is in the range of the branch flags ad defined in TM. Using this, NAT traversal per branch may be implemented.

1.2.1. OpenSER Modules

The following modules must be loaded before this module:

• No dependencies on other OpenSER modules.

1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSER with this module loaded:

• None.

1.3.1. fr_timer (integer)

Timer which hits if no final reply for a request or ACK for a negative INVITE reply arrives (in seconds).

Default value is 30 seconds.

...
modparam("tm", "fr_timer", 10)
...

1.3.2. fr_inv_timer (integer)

Timer which hits if no final reply for an INVITE arrives after a provisional message was received (in seconds).

Default value is 120 seconds.

...
modparam("tm", "fr_inv_timer", 200)
...

1.3.3. wt_timer (integer)

Time for which a transaction stays in memory to absorb delayed messages after it completed; also, when this timer hits, retransmission of local cancels is stopped (a puristic but complex behavior would be not to enter wait state until local branches are finished by a final reply or FR timer--we simplified).

Default value is 5 seconds.

...
modparam("tm", "wt_timer", 10)
...

1.3.4. delete_timer (integer)

Time after which a to-be-deleted transaction currently ref-ed by a process will be tried to be deleted again.

Default value is 2 seconds.

...
modparam("tm", "delete_timer", 5)
...

1.3.5. retr_timer1p1 (integer)

Retransmission period.

Default value is 1 second.

...
modparam("tm", "retr_timer1p1", 2)
...

1.3.6. retr_timer1p2 (integer)

Retransmission period.

Default value is 2 * retr_timer1p1 second.

...
modparam("tm", "retr_timer1p2", 4)
...

1.3.7. retr_timer1p3 (integer)

Retransmission period.

Default value is 4 * retr_timer1p1 second.

...
modparam("tm", "retr_timer1p3", 8)
...

1.3.8. retr_timer2 (integer)

Maximum retransmission period.

Default value is 4 seconds.

...
modparam("tm", "retr_timer2", 8)
...

1.3.9. noisy_ctimer (integer)

If set, on FR timer INVITE transactions will be explicitly canceled if possible, silently dropped otherwise. Preferably, it is turned off to allow very long ringing. This behavior is overridden if a request is forked, or some functionality explicitly turned it off for a transaction (like acc does to avoid unaccounted transactions due to expired timer).

Default value is 0 (false).

...
modparam("tm", "noisy_ctimer", 1)
...

1.3.10. ruri_matching (integer)

Should be request-uri matching used as a part of pre-3261 transaction matching as the standard wants us to do so? Turn only off for better interaction with devices that are broken and send different r-uri in CANCEL/ACK than in original INVITE.

Default value is 1 (true).

...
modparam("tm", "ruri_matching", 0)
...

1.3.11. via1_matching (integer)

Should be top most VIA matching used as a part of pre-3261 transaction matching as the standard wants us to do so? Turn only off for better interaction with devices that are broken and send different top most VIA in CANCEL/ACK than in original INVITE.

Default value is 1 (true).

...
modparam("tm", "via1_matching", 0)
...

1.3.12. unix_tx_timeout (integer)

Send timeout to be used by function which use UNIX sockets (as t_write_unix).

Default value is 2 seconds.

...
modparam("tm", "unix_tx_timeout", 5)
...

1.3.13. restart_fr_on_each_reply (integer)

If true (non null value), the final response timer will be re-triggered for each received provisional reply. In this case, final response timeout may occure after a time longe than fr_inv_timer (if UAS keeps sending provisional replies)

Default value is 1 (true).

...
modparam("tm", "restart_fr_on_each_reply", 0)
...

1.3.14. fr_timer_avp (string)

Full specification (NAME, ID, Alias) of an AVP which contains a final response timeout value. If present, ths value will overeide the static fr_timer parameter.

If set to empty string, the whole mechanism for variable timeout will be disabled, falling back to the static value.

Default value is "callee_fr_timer".

...
modparam("tm", "fr_timer_avp", "i:24")
...

1.3.15. fr_inv_timer_avp (string)

Full specification (NAME, ID, Alias) of an AVP which contains a final INVITE response timeout value. If present, ths value will overeide the static fr_inv_timer parameter.

If set to empty string, the whole mechanism for variable timeout will be disabled, falling back to the static value.

Default value is "callee_fr_inv_timer".

...
modparam("tm", "fr_inv_timer_avp", "i:25")
...

1.3.16. tw_append (string)

List of additional information to be appended by t_write_fifo and t_write_unix functions.

Default value is null string.

Syntax of the parameter is:

• tw_append = append_name':' element (';'element)*

• element = ( [name '='] pseudo_variable)

The full list of supported pseudo-variables in OpenSER is availabe at: http://openser.org/docs/pseudo-variables.html

Each element will be appended per line in "name: value" format. Element "$rb (message body)" is the only one which does not accept name; the body it will be printed all the time at the end, disregarding its position in the definition string.

...
modparam("tm", "tw_append",
   "test: ua=$hdr(User-Agent) ;avp=$avp(i:10);$rb;time=$Ts")
...

1.3.17. branch_flag_mask (string)

Defined which flags shall be as branch flags. The branch flags will be visible only in the messages belonging to that branch (in branch, onreply and failure route). The global flags are visible for all messages of the corresponding transaction.

The value of the parameter is a 32-bits mask. It may be defined using 2, 10 or 16 bases.

Default value is NULL (no branch flags, all being global).

...
# using base 16
modparam("tm", "branch_flag_mask", "0xff000000")
# or using base 2
modparam("tm", "branch_flag_mask", "b11111111000000000000000000000000")
# or using base 10
modparam("tm", "branch_flag_mask", "4278190080")
...

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

NOTE that the changes on the request that are made after this function call will not be saved into transaction!!!

This function can be used from REQUEST_ROUTE.

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

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

This function can be used from REQUEST_ROUTE.

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

1.4.3. t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port), t_relay_to_tls(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.

This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

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

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

1.4.5. 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_uri()

Similar to t_relay() but it expects the transaction to be aleady created - this why it cannot handle ACK (which are statelessly forwarded). It should be used along with t_newtran().

Meaning of the parameters is as follows:

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

• port - Port number.

t_forward_nonack_uri() will determin the detination address (proto:IP:port) based on the RURI.

This functions can be used from REQUEST_ROUTE.

...
t_forward_nonack("1.2.3.4", "5060");
t_forward_nonack_udp("1.2.3.4", "5060"); # force UDP proto
t_forward_nonack_tcp("1.2.3.4", "5060"); # force TCP proto
t_forward_nonack_tls("1.2.3.4", "5060"); # force TLS proto
t_forward_nonack_uri();
...

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

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

1.4.7. t_retransmit_reply()

Retransmits a reply sent previously by UAS transaction.

This function can be used from REQUEST_ROUTE.

...
t_retransmit_reply();
...

1.4.8. t_replicate(ip, port) t_replicate_udp(ip, port) t_replicate_tcp(ip, port)

Replicates a request to another address. No information due the replicated request (like reply code) will be forwarded to the original SIP UAC.

Meaning of the parameters is as follows:

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

• port - Port number.

This functions can be used from REQUEST_ROUTE.

...
t_replicate("1.2.3.4", "5060");
t_replicate_udp("1.2.3.4", "5060"); # force UDP proto
t_replicate_tcp("1.2.3.4", "5060"); # force TCP proto
...

1.4.9. t_release()

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

This function can be used from REQUEST_ROUTE.

...
t_release();
...

1.4.10. t_check_status(re)

Returns true if the regualr expresion "re" match the reply code of the response message as follows:

• in routing block - the code of the last sent reply.

• in on_reply block - the code of the current received reply.

• in on_failure block - the code of the selected negative final reply.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE.

...
if (t_check_status("(487)|(408)")) {
    log("487 or 408 negative reply\n");
}
...

1.4.11. t_flush_flags()

Flush the flags from current request into the already created transaction. It make sens only in routing block if the trnasaction was created via t_newtran() and the flags have been altered since.

This function can be used from REQUEST_ROUTE.

...
t_flush_flags();
...

1.4.12. t_local_replied(reply)

Returns true if all or last (depending of the parameter) reply(es) were local generated (and not received).

Parameter may be "all" or "last".

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE.

...
if (t_local_replied("all")) {
	log ("no reply received\n");
}
...

1.4.13. t_write_fifo(info,fifo) t_write_unix(info,sock)

Write via FIFO file or UNIX socket a lot of information regarding the request. Which information should be written may be control via the "tw_append" parameter.

This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE.

...
modparam("tm","tw_append","append1:Email=avp[i:12];UA=hdr[User-Agent]")
modparam("tm","tw_append","append2:body=msg[body]")
...
t_write_fifo("voicemail/append1","/tmp/appx_fifo");
...
t_write_unix("logger/append2","/var/run/logger.sock");
...

1.4.14. t_check_trans()

Returns true if the current request is associated to a transaction. The relationship between the request ans transaction is defined as follow:

• non-CANCEL/non-ACK requests - is true if the request belongs to a transaction; if so, it means that the request is a retransmision.

• CANCEL request - true if the cancelled INVITE transaction exists.

• ACK request - true if the ACK is a local end-to-end ACK for an existent INVITE transaction.

This function can be used from REQUEST_ROUTE.

...
if ( is_method("CANCEL") ) {
	if ( t_check_trans() )
		t_relay();
	exit;
}
...

1.4.15. t_was_cancelled()

Retuns true if called for an INVITE transaction that was explicitly cancelled by UAC side via a CANCEL request.

This function can be used from ONREPLY_ROUTE, FAILURE_ROUTE.

...
if (t_was_cancelled()) {
    log("transaction was cancelled by UAC\n");
}
...

1.4.16. t_on_failure(failure_route)

Sets reply routing block, to which control is passed after a transaction completed with a negative result but before sending a final reply. In the referred block, you can either start a new branch (good for services such as forward_on_no_reply) or send a final reply on your own (good for example for message silo, which received a negative reply from upstream and wants to tell upstream "202 I will take care of it").

As not all functions are available from failure route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

Note that whenever failure_route is entered, RURI is set to value of the winning branch.

Meaning of the parameters is as follows:

• failure_route - Reply route block to be called.

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

failure_route[1] {
	seturi("sip:user@voicemail");
	append_branch();
	t_relay();
}
...

1.4.17. t_on_reply(reply_route)

Sets reply routing block, to which control is passed each time a reply (provisional or final) for the transaction is received. The route is not called for local generated replies! In the referred block, you can inspect the reply and perform text operations on it.

As not all functions are available from this type of route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

If the processed reply is provisionla reply (1xx code), by calling the drop() function (exported by core), the execution of the route will end and the reply will not be forwarded further.

Meaning of the parameters is as follows:

• reply_route - Reply route block to be called.

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

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

1.4.18. t_on_branch(branch_route)

Sets a branch route to be execute separately for each branch of the transaction before being sent out - changes in that route should reflect only on that branch.

As not all functions are available from this type of route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

The per-branch flags which are modified in the branch route will be visible only in the replies related to that branch. See Section 1.3.17 also.

By calling the drop() function (exported by core), the execution of the branch route will end and the branch will not be forwarded further.

Meaning of the parameters is as follows:

• branch_route - Branch route block to be called.

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

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

2.1.1. load_tm(*import_structure)

For programmatic use only--import the TM API. See the cpl-c, acc or jabber modules to see how it works.

Meaning of the parameters is as follows:

• import_structure - Pointer to the import structure - see "struct tm_binds" in modules/tm/tm_load.h