SIP Methods
(→Enable MESSAGE Method) |
(→Example setups for MESSAGE/SUBSCRIBE methods) |
||
| Line 202: | Line 202: | ||
* Regexroute receives msg.route and renames it to call.route | * Regexroute receives msg.route and renames it to call.route | ||
* Another module(regfile in current setup) handles call.route and returns the uri for which we need to deliver the received chat message. | * Another module(regfile in current setup) handles call.route and returns the uri for which we need to deliver the received chat message. | ||
| − | * Lateroute replaces callto parameter with the | + | * Lateroute replaces callto parameter with the returned value of the call.route message and leaves msg.execute unhandled |
| − | * | + | * msg.execute is received in regexroute and is renamed to xsip.generate if callto param is a valid SIP uri. |
* xsip.generate will be handled by ysipchan module that will finish delivering the chat message | * xsip.generate will be handled by ysipchan module that will finish delivering the chat message | ||
Revision as of 16:03, 12 November 2012
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.
Requests genenerated from Yate
In some cases you might need to initiate SIP requests from a module in Yate and send them to a specific party.
In this case you should send xsip.generate message from the module/script where the logic is implemented. ysipchan module handles this message and sends the SIP request to the specified party.
This happens when Yate sends NOTIFY requests to the users that subscribed to a certain event. Or you can see below the setup for sending chat messages between SIP users that uses both SIP generic messages and xsip.generate.
SIP generic message
SIP generic messages are messages generated by the ysipchan module on receiving the specified requests in [methods] section.
Syntax
The syntax is: sip.methodname, where methodname is the name of the received SIP request (e.g. sip.subscribe).
Parameters
- xsip_dlgtag
- The dialog tag of the received request.
- sip_uri
- The request URI of the received SIP method.
- xsip_type
- The content type header.
- sip_headername
- Where headername is the name of the header received with the request. This parameter is repeated for each header in the request (e.g. sip_from, sip_to, etc).
Return
A module processing this message should set the 'code' parameter of the message to a SIP response code.
The processing module may also set message's parameters named osip_headername to be returned in the SIP response (e.g. osip_Expires).
Example
Yate receives a SIP request for MESSAGE method as below:
<sip:INFO> 'udp:0.0.0.0:5062' received 381 bytes SIP message from 192.168.168.156:5060 [0x890f858] ------ MESSAGE sip:234@192.168.168.156 SIP/2.0 Via: SIP/2.0/UDP 192.168.168.156;rport;branch=z9hG4bKmibzipmn Max-Forwards: 70 To: <sip:234@192.168.168.156> From: "DanielaGrigore" <sip:123@192.168.168.156>;tag=hhzbn Call-ID: xgjfitpjqqffbmz@localhost.localdomain CSeq: 427 MESSAGE Content-Type: text/plain;charset=utf-8 User-Agent: Twinkle/1.4.1 Content-Length: 12 hello Monica ------
Sends code 100 Trying and generates the following SIP generic 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'
Follow the example below for a full configuration on how the enable and handle the MESSAGE method.
Example setups for MESSAGE/SUBSCRIBE methods
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
Yate receives a MESSAGE SIP Request. This will be handled generically, so a Yate message named sip.message will be sent.
- Regexroute receives this message:
- If xsip_type parameter is not set a 415 error code will be returned in SIP module, otherwise echo a message for debug purpose.
- Enqueue msg.execute message in which we'll copy the parameters defining message: caller, called, domain, callto, body_encoding, type, text. In order to deliver the message we have to find the URI for the receiving end, and for that we use lateroute. Set callto=lateroute/${called}.
- Handle message and return code 200 OK.
- Lateroute module receives the msg.execute message and sends msg.route message with called parameter the ${called} from above
- Regexroute receives msg.route and renames it to call.route
- Another module(regfile in current setup) handles call.route and returns the uri for which we need to deliver the received chat message.
- Lateroute replaces callto parameter with the returned value of the call.route message and leaves msg.execute unhandled
- msg.execute is received in regexroute and is renamed to xsip.generate if callto param is a valid SIP uri.
- xsip.generate will be handled by ysipchan module that will finish delivering the chat message
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
