Call.route
From Yate Documentation
(Difference between revisions)
(→call.route) |
|||
| (11 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | |||
| − | Message sent by a channel when a new call is coming inwards Yate and a routing decision | + | Message sent by a channel when a new call is coming inwards Yate and a routing decision needs to be made. The returned value is the logical destination of the call. |
| + | |||
| + | ===Sample scenario=== | ||
| − | |||
#Call comes to (let's say) H.323 module | #Call comes to (let's say) H.323 module | ||
#H323chan sends a '''call.route''' and waits for a returned value | #H323chan sends a '''call.route''' and waits for a returned value | ||
| Line 13: | Line 13: | ||
=== Parameters === | === Parameters === | ||
| − | + | ;driver : The module that makes the request | |
| − | + | ;id : The id of the channel | |
| − | + | ;callername : Module-specific caller name string | |
| − | + | ;caller : The caller id | |
| − | + | ;called : The called number | |
| − | + | ;address : Module-specific remote endpoint address | |
| − | + | ;context : The routing context selected by the current call | |
| − | + | ;timeout :Timeout for the outgoing channel (milliseconds) | |
| − | + | ;maxcall : Maximum call time until answered (milliseconds), possible values are between 2000 (2 seconds) and 120000 (120 seconds) | |
| − | + | ===Scenarios=== | |
| − | In some cases | + | *In some cases a routing module may decide to add one more parameter to this message and to let message pass to the next routing module. |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | *In some cases you may need to return an error with a code and reason to the sender. | |
| + | ====Send a 403 Forbidden==== | ||
| − | if(some_condition_met()) | + | To do that, you have to set the return value of the message to "-" (to a dash) or "error" string. |
| + | |||
| + | Then set the parameters called ''error'' and ''reason'' to forbidden (using setParam() method) to write the error. | ||
| + | |||
| + | e.g. | ||
| + | |||
| + | if (some_condition_met()) | ||
{ | { | ||
| − | msg.retValue() = "-"; | + | msg.retValue() = "-"; // msg.retValue() = "error"; |
| − | msg.setParam("error", "forbidden"); //will set the | + | msg.setParam("error", "forbidden"); //will set the SIP message as 403 |
| − | msg.setParam("reason", "Forbidden"); //The text that appears in the | + | msg.setParam("reason", "Forbidden"); //The text that appears in the SIP message (403 Forbidden) |
return true; //make sure no other modules handle the message | return true; //make sure no other modules handle the message | ||
} | } | ||
| + | You can use this message to make very complex routing systems based on the information you get. | ||
| + | ====Send other SIP errors==== | ||
| − | + | Other status codes than "forbidden" can be generated in a similar way, by setting other values in the ''error'' parameter. However, this parameter cannot have an arbitrary value. It must match one of the values defined and implemented in Yate. | |
| + | |||
| + | For a list of all valid values in SIP, look at the ''dict_errors'' definition in the ''modules/ysipchan.cpp'' file in the Yate source code. | ||
| + | |||
| + | '''See also''' | ||
| + | |||
| + | * [[call.preroute]] | ||
Latest revision as of 18:07, 18 November 2013
Message sent by a channel when a new call is coming inwards Yate and a routing decision needs to be made. The returned value is the logical destination of the call.
Contents |
[edit] Sample scenario
- Call comes to (let's say) H.323 module
- H323chan sends a call.route and waits for a returned value
- H323chan sends a call.execute based on the returned value of the call.route
- It gets a call.ringing
- It gets a call.answered
- It hangs up either by a request from the remote H.323 endpoint or from a call.drop or for any other reason.
[edit] Parameters
- driver
- The module that makes the request
- id
- The id of the channel
- callername
- Module-specific caller name string
- caller
- The caller id
- called
- The called number
- address
- Module-specific remote endpoint address
- context
- The routing context selected by the current call
- timeout
- Timeout for the outgoing channel (milliseconds)
- maxcall
- Maximum call time until answered (milliseconds), possible values are between 2000 (2 seconds) and 120000 (120 seconds)
[edit] Scenarios
- In some cases a routing module may decide to add one more parameter to this message and to let message pass to the next routing module.
- In some cases you may need to return an error with a code and reason to the sender.
[edit] Send a 403 Forbidden
To do that, you have to set the return value of the message to "-" (to a dash) or "error" string.
Then set the parameters called error and reason to forbidden (using setParam() method) to write the error.
e.g.
if (some_condition_met())
{
msg.retValue() = "-"; // msg.retValue() = "error";
msg.setParam("error", "forbidden"); //will set the SIP message as 403
msg.setParam("reason", "Forbidden"); //The text that appears in the SIP message (403 Forbidden)
return true; //make sure no other modules handle the message
}
You can use this message to make very complex routing systems based on the information you get.
[edit] Send other SIP errors
Other status codes than "forbidden" can be generated in a similar way, by setting other values in the error parameter. However, this parameter cannot have an arbitrary value. It must match one of the values defined and implemented in Yate.
For a list of all valid values in SIP, look at the dict_errors definition in the modules/ysipchan.cpp file in the Yate source code.
See also
