How to setup chat and short file transfer using MESSAGE Request Method
Starting with Yate 5 or svn revision 5629 yate changed the way it handles SIP MESSAGE request method. If you have a newer version of yate or you can update we suggest you follow this guide.
This article applies for svn revisions lower than 5629.
This example explains how to setup chat and short files transfer between Twinkle clients.
This explains how to use SIP MESSAGE and SIP PUBLISH requests with Yate.
For setting chat, the SIP MESSAGE request method is used to transports instant messages. File transfer uses the SIP PUBLISH request method.
Both MESSAGE and PUBLISH requests are one of the generically handled methods in Yate. This means that when MESSAGE request is received, Yate won't handle it automatically, but a sip.message yate message will be emitted. The handling of the message is custom and can be done from regexroute/external module/custom yate module.
Contents |
Configuration
Enable MESSAGE and PUBLISH requests and generate option
- Generically handled methods are not enabled by default. You need to configure Yate to accept the MESSAGE and PUBLISH requests. In order to do this you have enable the requests in [methods] section in ysipchan.conf.
- You also have to set generate to true so you allow Yate to generate SIP requests on behalf of other modules/scripts. This allows ysipchan module to handle xsip.generate and send SIP requests of behalf on scripts or other modules.
- Set maxpkt to limit the maximum size if the file that can be transfered.
In ysipchan.conf:
[general] maxpkt=4096 generate=yes [methods] message=yes publish=yes
Handle messages
The handling of the messages: sip.message and sip.publish is custom. Below you can see a test setup where the handling is done in regexroute.
- enable the receiving of the messages in [extra] section.
- define section for each of the messages
How this configuration works is explained below.
regexroute.conf:
[extra]
sip.message=120
sip.publish=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
[sip.publish]
${xsip_type}^application/pidf+xml$^=415
${xsip_body}<status><basic>\(.*\)</basic></status>=echo Got SIP PRESENCE from '${username}': \1
.*=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};connection_id=${oconnection_id}
Configure users to test setup
To configure twinkle clients, register users in regfile.conf:
[123] password=mypass123 [234] password=mypass234
Note: Regfile(or other module/script depending on the setup) will also handle the call.route message used to find the SIP uri where the MESSAGE request should be sent.
How it works
This section explains the flow of the messages in Yate:
- Yate receives a SIP MESSAGE 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 pass to the below steps.
- Echo a message for debug purpose.
- Enqueue msg.execute message in which we'll copy the parameters defining message: caller, called, domain, 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
- Regexroute receives msg.execute and renames it 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. Ysipchan will emit a MESSAGE request and will send it to the SIP uri specified in xsip.generate.
See also
