Call.route

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

1. Call comes to (let's say) H.323 module
2. H323chan sends a call.route and waits for a returned value
3. H323chan sends a call.execute based on the returned value of the call.route
4. It gets a call.ringing
5. It gets a call.answered
6. It hangs up either by a request from the remote H.323 endpoint or from a call.drop or for any other reason.

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

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.

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