SIP Methods

From Yate Documentation
Revision as of 10:50, 12 November 2012 by Monica (Talk | contribs)

Jump to: navigation, search

This page describes how Yate handles the SIP requests depending on the request method.

Contents

What is a SIP Request Method?

A SIP request method defines the nature and the purpose of the SIP request.

This the list of SIP request methods:

  • INVITE - Requests a session.
  • ACK - Final response to the INVITE
  • OPTIONS - Ask for server capabilities
  • BYE - Terminates a session
  • PRACK - Similar to ACK, but a provisional confirmation.
  • CANCEL - Cancel any pending requests.
  • REGISTER - Registers the client with the server according to the address in the To he
  • INFO - Sends information in the middle of a session that doesn't modify the session's state.
  • SUBSCRIBE -Subscribes the device for an event notification.
  • NOTIFY - Notifies all subscribers of an event.
  • PUBLISH - Publishes an event to a server.
  • REFER - Asks the client to issue a SIP request, typically a call transfer.
  • MESSAGE - Sends an instant message using SIP.
  • UPDATE - Modifies a session's state without altering the dialog state.

SIP Methods in Yate

In Yate some SIP requests are handled internally while others are handled generically.

When a SIP request comes in Yate, depending on the request method it will be either handled in ysipchan module(internally handled), or an internal yate message named sip.methodname will be sent(generically handled).

Generically handled methods are not handled in ysipchan module. A yate message is sent for them and the handling is done in other modules/external scripts. Some methods have yate modules that handle them while others don't, so you need to define the handling of the message in a custom way when enabling them.

Internally handled Methods

Internally handled request methods are requests handled directly by ysipchan module. Yate messages like sip.methodname won't be generated for them.

The methods are handled internally by Yate:

  • methods that are always handled when ysipchan module is enabled
    • INVITE
    • CANCEL
    • ACK
    • BYE
  • methods that are handled in the default configuration and that can be enabled/disabled from [general] section
    • INFO - controlled by info setting. If request is received during a dialog initiated by an INVITE and it's used for application/dtmf-relay or application/dtmf then it's handled internally. Outside a dialog it's handled generically.
    • OPTIONS - controlled by options setting.
  • methods that are handled in the default configuration when yate is started in server mode, and are disabled when yate is started in client mode. They can be enabled/disabled from [general] section
    • REFER - controlled by transfer setting
    • REGISTER - controlled by register setting. If register=enabled then [registrar] section defines how Yate will work as a SIP REGISTRAR. Before starting yate as SIP registrar set users in regfile.conf or in register.conf.
  • methods that are disabled in the default configuration but can be enabled/disabled from [general] section
    • PRACK - controlled by prack setting

Generically handled Methods

In order to handle other methods besides those listed above you must enable them in [methods] section.

When Yate receives a request for one of the enabled methods, it will generate a generic SIP message. This message will be handled from a module or from an external script.

  • INFO - if it's receive outside a dialog started by an INVITE request, or it's not for application/dtmf or application/dtmf-relay

Enabling additional Methods

Use section [methods] from ysipchan.conf to allow/restrict the processing of specific SIP methods. For enabled methods yate will generate internal messages with name sip.<methodname> that can be handled from other modules.

Examples

Enable MESSAGE Method

This example allows chat and short files transfer between Twinkle clients using MESSAGE Request Method.

A MESSAGE request method transports instant messages using SIP.

regexroute.conf:

[extra]
sip.message=120
msg.route=25
msg.execute=90

[sip.message]
${xsip_type}^$=415
.*=echo Got SIP MESSAGE type '${xsip_type}' ${xsip_body_encoding} from '${username}': ${xsip_body}
.*=enqueue msg.execute;caller=${caller};called=${called};\
 domain=${domain};callto=lateroute/${called};\
 body_encoding=${xsip_body_encoding};type=${xsip_type};text=${xsip_body}
.*=200
  
[msg.route]
.*=rename call.route;message=msg.route

[msg.execute]
${callto}^sip/\(sip:.*\)$=rename xsip.generate;\
method=MESSAGE;uri=\1;sip_From=<sip:${caller}@${domain$nosuch.dom}>;\
xsip_type=${type$text/plain};xsip_body_encoding=${body_encoding};\
xsip_body=${text}


In ysipchan.conf:

[general]
maxpkt=4096
generate=yes

[methods]
message=yes

To configure twinkle clients, register users in regfile.conf:

[123]
password=mypass123

[234]
password=mypass234

If sniffer is enabled in telnet

sip.message

Sniffed 'sip.message' time=1352472395.780609                                                                                                                         
  thread=0x890d348 'YSIP EndPoint'                                                                                                                                   
  data=(nil)                                                                                                                                                         
  retval='(null)'                                                                                                                                                    
  param['username'] = '123'                                                                                                                                          
  param['realm'] = 'Yate'                                                                                                                                            
  param['ip_transport'] = 'UDP'                                                                                                                                      
  param['newcall'] = 'false'                                                                                                                                         
  param['domain'] = '192.168.168.156'                                                                                                                                
  param['device'] = 'Twinkle/1.4.1'                                                                                                                                  
  param['connection_id'] = 'general'                                                                                                                                 
  param['connection_reliable'] = 'false'                                                                                                                             
  param['username'] = '123'                                                                                                                                          
  param['called'] = '234'                                                                                                                                            
  param['caller'] = '123'                                                                                                                                            
  param['callername'] = 'DanielaGrigore'                                                                                                                             
  param['antiloop'] = '19'                                                                                                                                           
  param['address'] = '192.168.168.156:5060'                                                                                                                          
  param['ip_host'] = '192.168.168.156'                                                                                                                               
  param['ip_port'] = '5060'                                                                                                                                          
  param['ip_transport'] = 'UDP'                                                                                                                                      
  param['sip_uri'] = 'sip:234@192.168.168.156'                                                                                                                       
  param['sip_callid'] = 'xgjfitpjqqffbmz@localhost.localdomain'                                                                                                      
  param['xsip_dlgtag'] = '2078093122'                                                                                                                                
  param['sip_to'] = '<sip:234@192.168.168.156>'                                                                                                                      
  param['sip_from'] = '"DanielaGrigore" <sip:123@192.168.168.156>;tag=hhzbn'                                                                                         
  param['sip_content-type'] = 'text/plain;charset=utf-8'                                                                                                             
  param['sip_user-agent'] = 'Twinkle/1.4.1'                                                                                                                          
  param['xsip_type'] = 'text/plain'                                                                                                                                  
  param['xsip_body'] = 'hello Monica'                                                                                                                                
Got SIP MESSAGE type 'text/plain'  from '123': hello Monica                                                                                                          
<RegexRoute:ALL> Enqueueing new message 'msg.execute' by rule #3 '.*' in context 'sip.message'                                                                       
Returned true 'sip.message' delay=0.001392                                                                                                                           
  thread=0x890d348 'YSIP EndPoint'                                                                                                                                   
  data=(nil)                                                                                                                                                         
  retval='200'                                                                                                                                                       
  param['username'] = '123'                                                                                                                                          
  param['realm'] = 'Yate'                                                                                                                                            
  param['ip_transport'] = 'UDP'                                                                                                                                      
  param['newcall'] = 'false'                                                                                                                                         
  param['domain'] = '192.168.168.156'                                                                                                                                
  param['device'] = 'Twinkle/1.4.1'                                                                                                                                  
  param['connection_id'] = 'general'                                                                                                                                 
  param['connection_reliable'] = 'false'                                                                                                                             
  param['username'] = '123'                                                                                                                                          
  param['called'] = '234'                                                                                                                                            
  param['caller'] = '123'                                                                                                                                            
  param['callername'] = 'DanielaGrigore'                                                                                                                             
  param['antiloop'] = '19'                                                                                                                                           
  param['address'] = '192.168.168.156:5060'                                                                                                                          
  param['ip_host'] = '192.168.168.156'                                                                                                                               
  param['ip_port'] = '5060'                                                                                                                                          
  param['ip_transport'] = 'UDP'                                                                                                                                      
  param['sip_uri'] = 'sip:234@192.168.168.156'                                                                                                                       
  param['sip_callid'] = 'xgjfitpjqqffbmz@localhost.localdomain'                                                                                                      
  param['xsip_dlgtag'] = '2078093122'                                                                                                                                
  param['sip_to'] = '<sip:234@192.168.168.156>'                                                                                                                      
  param['sip_from'] = '"DanielaGrigore" <sip:123@192.168.168.156>;tag=hhzbn'                                                                                         
  param['sip_content-type'] = 'text/plain;charset=utf-8'                                                                                                             
  param['sip_user-agent'] = 'Twinkle/1.4.1'                                                                                                                          
  param['xsip_type'] = 'text/plain'                                                                                                                                  
  param['xsip_body'] = 'hello Monica'                                                                                                                                
  param['handlers'] = 'regexroute:120' 

msg.execute

Sniffed 'msg.execute' time=1352472395.781897                                                                                                                         
 thread=0x89228a8 'Engine Worker'                                                                                                                                   
 data=(nil)                                                                                                                                                         
 retval='(null)'                                                                                                                                                    
 param['caller'] = '123'                                                                                                                                            
 param['called'] = '234'                                                                                                                                            
 param['domain'] = '192.168.168.156'                                                                                                                                
 param['callto'] = 'lateroute/234'                                                                                                                                  
 param['body_encoding'] =                                                                                                                                         
 param['type'] = 'text/plain'                                                                                                                                       
 param['text'] = 'hello Monica'  

msg.route

Sniffed 'msg.route' time=1352472395.781897                                                                                                                           
 thread=0x89228a8 'Engine Worker'                                                                                                                                   
 data=(nil)                                                                                                                                                         
 retval='(null)'                                                                                                                                                    
 param['caller'] = '123'                                                                                                                                            
 param['called'] = '234'                                                                                                                                            
 param['domain'] = '192.168.168.156'                                                                                                                                
 param['body_encoding'] =                                                                                                                                         
 param['type'] = 'text/plain'                                                                                                                                       
 param['text'] = 'hello Monica'                                                                                                                                     
 param['handlers'] = 'lateroute:75'                                                                                                                                 
<RegexRoute:ALL> Renaming message 'msg.route' to 'call.route' by rule #1 '.*' in context 'msg.route'                                                                 
<INFO> Could not route call to '234' in context 'default', wasted 178 usec                                                                                           
<regfile:INFO> Routed '234' via 'sip/sip:234@192.168.168.11(null)'                                                                                                   
Returned true 'call.route' delay=0.003463                                                                                                                            
 thread=0x89228a8 'Engine Worker'                                                                                                                                   
 data=(nil)                                                                                                                                                         
 retval='sip/sip:234@192.168.168.11'                                                                                                                                
 param['caller'] = '123'                                                                                                                                            
 param['called'] = '234'                                                                                                                                            
 param['domain'] = '192.168.168.156'                                                                                                                                
 param['body_encoding'] =                                                                                                                                         
 param['type'] = 'text/plain'                                                                                                                                       
 param['text'] = 'hello Monica'                                                                                                                                     
 param['handlers'] = 'lateroute:75,regexroute:25,cdrbuild:50,iax:100,h323:100,jingle:100,regexroute:100,sip:100,regfile:100'                                        
 param['message'] = 'msg.route'                                                                                                                                     
 param['oconnection_id'] = 'general'                                                                                                                                
 param['driver'] = 'sip'                                                                                                                                            
<INFO> Late routing call to 'lateroute/234' via 'sip/sip:234@192.168.168.11'                                                                                         
<RegexRoute:ALL> Renaming message 'msg.execute' to 'xsip.generate' by rule #1 '${callto}^sip/\(sip:.*\)$' in context 'msg.execute'                                   
<sip:INFO> SipHandler::received() [0x890ec68]                                                                                                                        
Returned true 'xsip.generate' delay=0.003973                                                                                                                         
 thread=0x89228a8 'Engine Worker'                                                                                                                                   
 data=(nil)                                                                                                                                                         
 retval='(null)'                                                                                                                                                    
 param['caller'] = '123'                                                                                                                                            
 param['called'] = '234'                                                                                                                                            
 param['domain'] = '192.168.168.156'                                                                                                                                
 param['body_encoding'] =                                                                                                                                         
 param['type'] = 'text/plain'                                                                                                                                       
 param['text'] = 'hello Monica'                                                                                                                                     
 param['handlers'] = 'lateroute:75,regexroute:25,cdrbuild:50,iax:100,h323:100,jingle:100,regexroute:100,sip:100,regfile:100,regexroute:90,sip:110'                  
 param['message'] = 'msg.route'                                                                                                                                     
 param['oconnection_id'] = 'general'                                                                                                                                
 param['driver'] = 'sip'                                                                                                                                            
 param['callto'] = 'sip/sip:234@192.168.168.11'                                                                                                                     
 param['method'] = 'MESSAGE'                                                                                                                                        
 param['uri'] = 'sip:234@192.168.168.11'                                                                                                                            
 param['sip_From'] = '<sip:123@192.168.168.156>'                                                                                                                    
 param['xsip_type'] = 'text/plain'                                                                                                                                  
 param['xsip_body_encoding'] =                                                                                                                                    
 param['xsip_body'] = 'hello Monica'
Enable SUBSCRIBE Method

ysipchan.conf

[methods]
subscribe=yes

You then configure the allowed events for subscribing in sipfeatures.conf and define the logic for SUBSCRIBE/NOTIFY in subscription.conf.


See also

Personal tools
Namespaces

Variants
Actions
Preface
Configuration
Administrators
Developers