Call.route

Revision as of 16:21, 3 October 2012

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

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. e.g. Send a 403 Forbidden to do that, you set the parameter :retValue(): to "-" (to a dash) Then set the parameters :error: and :reason: (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.