Call.route

Message sent by a channel when a new call is coming inwards Yate and a routing decision need 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 

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)

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

See also

• call.preroute