View source for Routing Script Tutorial: Script Parameters Definition for SIP

{{DISPLAYTITLE: Script Parameters Definition for SIP}}
== request_uri  ==

Enables access to the Request-Line URI.<br> 

For example, if the Request-Line is: 
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre> 
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". <br> 

In the routing scripts, to retrieve only the called number, this script can be used:<br> 
<pre>    if call_params[:request_uri] &amp;&amp; call_params[:request_uri] =~ /sip:(.*)@.*/
       call_params[:called] = $1
    end
</pre> 
=== request_uri_forward_enabled ===

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message.<br>

Values for this parameter are "0", "1", "false" or "true. <br> 

* 0/false: Request uri is not forwarded to outgoing call leg <br> 

* 1/true: Request uri is forwarded to outgoing call leg <br> 

The default value for this parameters is false. <br>


=== sip_scheme  ===
(Available in Toolpack 3.1+)
This call parameter indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows the control of the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

== sip_header values  ==
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg:<br />

'''Note:'''

The  SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept               Error-Info             Remote-Party-ID      
Accept-Contact       Event                  Replaces                        
Accept-Encoding      Expires                Reply-To               
Accept-Language      From                   Request-Disposition    
Alert-Info           In-Reply-To            Subject          
Allow                Max-Forwards           Subscription-State  
Allow-Events         MIME-version           Supported           
Also                 Min-Expires            Timestamp           
Anonymity            Min-SE                 To             
Authorization        Organization           Unsupported  
Authentication-Info  Path                   User-Agent  
Call-ID              Priority               Via  
Call-Info            Privacy                Warning  
Contact              Proxy-Authenticate     WWW-Authenticate  
Content-Disposition  Proxy-Authorization    Require  
Content-Encoding     Proxy-Require          Response-Key  
Content-Language     P-Media-Authorization  Retry-After  
Content-Length       P-Preferred-Identity   RPID-Privacy  
Content-Type         P-Asserted-Identity    Route  
CSeq                 RAck                   RSeq  
RAck                 Reason                 Security-Client  
Reason               Record-Route           Security-Server  
Date                 Refer-To               Security-Verify
Diversion            *Referred-By            Server
Encryption           Reject-Contact         Service-Route             
                                            Session-Expires
</pre>
Note: Since version 3.0.57, Referred-By is now a SIP custom parameter

== sip header parameters  ==
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

=== Available parameters ===
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :supp_private_address_parameters ]''' (SIP supplementary/second "P-Asserted-Identity" header)
* '''call[ :preferred_id_parameters ]''' (SIP "P-Preferred-Identity" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example  <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example  <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example  <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
  call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
  call[ :called_parameters ][ :uri_param ] = "user=phone"

=== Exceptions ===
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They will not appear in the generic SIP header parameters structures above.

=== Forwarding from inbound to outbound call ===

=== Legacy behavior ===
(For base_routing version 1.32 or older)
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

=== Current behavior ===
(For Toolpack 3.0.118+, with base_routing version 1.33+)
SIP headers host and parameters are forwarded by default.

A route attribute "forward_sip_domain" (along with filter script "forward_sip_domain.rb") will control, per route, if SIP headers host+parameters must be forwarded.

=== Example use ===
Example to print the user parameters:
<pre>
  if call[:calling_parameters]
    puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
  end
</pre>

Example SIP "From" header:
  From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
  call[:calling_parameters].inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = { 
  :user_param => "user_param7=7;user_param8=8",
  :uri_param => "uri_param9=value9",
  :header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
  call[:calling_parameters] ||= {} # Create a hash if not already present
  call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
  call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
  call[:calling_parameters][:uri_param] += "user=phone"
</pre>

[[Image:BackToMain.png|thumb|center|400px|link=https://docs.telcobridges.com/Routing_script_tutorial:Mini_Development_Guide]]