(:allVersions Script-Routes 1.5:)

!!!!!Documentation -> [[Documentation.Manuals|Manuals]] -> [[Documentation.Manual-1-5|Manual 1.5]] -> Types of routes
(:title Types of routes - ver 1.5 :)

[- Page for other versions: [[Script-Routes|devel]] [[Script-Routes-1-9|1.9]] [[Script-Routes-1-8|1.8]] old versions: [[Script-Routes-1-7|1.7]] [[Script-Routes-1-6|1.6]] 1.5 [[Script-Routes-1-4|1.4]] -]

\\

|| %color=#185662%[+'''Types of Routes v1.5'''+]%% ||

||[[Script-CoreParameters-1-5|Prev]] || [[Script-Operators-1-5|Next]]||
----

!![[Documentation.Documentation | Documentation]] -> Script -> [[Documentation.Script-Routes-1-5 | Routing Blocks 1.5]]

(:commentboxchrono:)

!!Resources -> [[Resources.Documentation | Documentation]] -> [[Resources.DocsCookbooks | CookBooks]] -> Routing Blocks v1.5.x
----
(:toc-float Table of Content:)

This Documentation is for '''OpenSIPS 1.5.x'''

'''OpenSIPS''' routing logic uses several types of routes. Each type of route is triggered by a certain event and allows you to process a certain type of message (request or reply).


-----
!!!!route

Request routing block. It contains a set of actions to be taken for SIP requests.

'''Triggered by''' : receiving an external request from the network.

'''Processing''' : the triggering SIP request.

'''Type''' : initially stateless, may be forced to stateful by using TM functions.

'''Default action''' : if the request is not either forwarded nor replied, the route will simply discard the request at the end.

The main 'route' block identified by 'route{...}' or 'route[0]{...}' is executed for each SIP request.

The implicit action after execution of the main route block is to drop the SIP request. To send a reply or forward the request, explicit actions must be called inside the route block.

Example of usage:
[@
route {
if(is_method("OPTIONS")) {
# send reply for each options request
sl_send_reply("200", "ok");
exit();
}
route(1);
}
route[1] {
# forward according to uri
forward();
}
@]

Note that if a 'route(X)' is called from a 'branch_route[Y]' then in 'route[X]' is just processed each separate branch instead of all branches together as occurs in main route.


----
!!!!branch_route

Request's branch routing block. It contains a set of actions to be taken for each branch of a SIP request.

'''Triggered by''' : preparation a new branch (of a request); the branch is well formed, but not yet sent out.

'''Processing''' : the SIP request (with the branch particularities, like RURI, branch flags)

'''Type''' : stateful

'''Default action''' : if the branch is not dropped (via "drop" statement), the branch will be automatically sent out.

It is executed only by TM module after it was armed via t_on_branch("branch_route_index").

Example of usage:
[@
route {
lookup("location");
t_on_branch("1");
if(!t_relay()) {
sl_send_reply("500", "relaying failed");
}
}
branch_route[1] {
if(uri=~"10\.10\.10].10") {
# discard branches that go to 10.10.10.10
drop();
}
}
@]


----
!!!!failure_route

Failed transaction routing block. It contains a set of actions to be taken each transaction that received only negative replies (>=300) for all branches.


'''Triggered by''' : receiving or generation(internal) of a negative reply that completes the transaction (all branches are terminated with negative replies)

'''Processing''' : the original SIP request (that was sent out)

'''Type''' : stateful

'''Default action''' : if no new branch is generated or no reply is forced over, by default, the winning reply will be sent back to UAC.

The 'failure_route' is executed only by TM module after it was armed via t_on_failure("failure_route_index").

Note that in 'failure_route' is processed the request that initiated the transaction, not the reply .


Example of usage:
[@
route {
lookup("location");
t_on_failure("1");
if(!t_relay()) {
sl_send_reply("500", "relaying failed");
}
}
failure_route[1] {
if(is_method("INVITE")) {
# call failed - relay to voice mail
t_relay("udp:voicemail.server.com:5060");
}
}
@]


----
!!!!onreply_route


Reply routing block. It contains a set of actions to be taken for SIP replies.

'''Triggered by''' : receiving of a reply from the network

'''Processing''' : the received reply

'''Type''' : stateful (if bound to a transaction) or stateless (if global reply route).

'''Default action''' : if the reply is not dropped (only provisional replies can be), it will be injected and processed by the transaction engine.

The main 'onreply_route' identified by 'onreply_route {...}' or 'onreply_route[0] {...}' is executed for all replies received.

Certain 'onreply_route' blocks can be executed by TM module for special replies. For this, the 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index").

[@
route {
lookup("location");
t_on_reply("1");
if(!t_relay()) {
sl_send_reply("500", "relaying failed");
}
}
onreply_route[1] {
if(status=~"1[0-9][0-9]") {
log("provisional response\n");
}
}
@]


----
!!!!error_route

The error route is executed automatically when a parsing error occurred during SIP request processing. This allow the administrator to decide what to do in case of error.

'''Triggered by''' : parsing error in "route"

'''Processing''' : failed request

'''Type''' : stateless (recommended)

'''Default action''' : discard request.


In error_route, the following pseudo-variables are available to get access to error details:
* $(err.class) - the class of error (now is '1' for parsing errors)
* $(err.level) - severity level for the error
* $(err.info) - text describing the error
* $(err.rcode) - recommended reply code
* $(err.rreason) - recommended reply reason phrase

[@
error_route {
xlog("--- error route class=$(err.class) level=$(err.level)
info=$(err.info) rcode=$(err.rcode) rreason=$(err.rreason) ---\n");
xlog("--- error from [$si:$sp]\n+++++\n$mb\n++++\n");
sl_send_reply("$err.rcode", "$err.rreason");
exit;
}
@]


----
!!!!local_route

The local route is executed automatically when a new SIP request is generated by TM, internally (no UAC side). This is a route intended to be used for message inspection, accouting and for applying last changes on the message headers. Routing and signalling functions are not allowed.

'''Triggered by''' : TM generating a brand new request

'''Processing''' : the new request

'''Type''' : stateful

'''Default action''' : send the request out



[@
local_route {
if (is_method("INVITE") && $ru=~"@foreign.com") {
append_hf("P-hint: foreign request\r\n");
exit;
}
if (is_method("BYE") ) {
acc_log_request("internally generated BYE");
}
}
@]


----

(:commentboxchrono:)