mod_jingle_sip
Module Description
This module enables Jingle to SIP and SIP to Jingle translation. When this module is enabled, MongooseIM will intercept any Jingle IQ set stanza with action:
- session-initiate
- session-terminate
- session-accept
- transport-info
and translate it to SIP messages with appropriate SDP content based on the details in the Jingle stanza.
The translation back from SIP to Jingle is done for the following SIP requests:
INVITE
re-INVITE
-INVITE
message sent for an accepted sessionCANCEL
BYE
INFO
and following responses to the INVITE request:
200
when the call invite was accepted180
and183
to indicate that the invitation was sent to the device486
when the call's recipient rejects it- from
400
to600
- other error codes indicating session termination
Jingle to SIP translation
The table below summarises the bilateral translation for standard Jingle and SIP messages:
Jingle action | SIP message | comment |
---|---|---|
session-initiate |
INVITE request |
|
session-accept |
200 OK response |
|
session-terminate with reason success |
BYE request |
Only for accepted session |
session-terminate with reason decline |
CANCEL request |
When sent by call's initiator |
session-terminate with reason decline |
486 Busy Here response |
When sent by the invite user |
transport-info |
INFO request |
Ringing notification
Both Jingle and SIP have the ringing
notification.
It's generated as a response code 180 Ringing
by a SIP entity when the INVITE is sent to the device.
In SIP world a 183 Session Progress
response code is also generated in some cases.
Both 180
and 183
codes are translated as session-info
Jingle stanza with ringing
sub element.
MongooseIM generates only 180 Ringing
response code the INVITE
request, if the recipient's online.
If the recipient is online, MongooseIM generates the 180 Ringing
response code to the INVITE
request.
Recipient unavailable
When MongooseIM receives a SIP INVITE
request addressed to an offline user,
it replies with a 480 Temporarily Unavailable
code.
The same code is expected from the SIP Proxy when MongooseIM sends the INVITE
request.
Other error codes
When an error response to the INVITE
request is from the range 400
to 699
but not 486
,
MongooseIM will send a Jingle session-terminate
stanza to the call's initiator.
The stanza has reason general-error
with the SIP error code in the sip-error
sub element.
Non-standard Jingle stanzas used by jingle.js
The following non-standard Jingle stanzas were integrated with Jingle.js:
source-remove
source-add
source-update
When MongooseIM observes the above Jingle stanzas, it will translate them to a SIP in-dialog INVITE
request.
In the SDP content of the request, there will be a custom attribute a=jingle-action
.
The value of the custom attribute is one of the three presented above.
Similarly when MongooseIM gets a SIP in-dialog INVITE
request,
it will check if there is a custom attribute and use it as the action
attribute of the Jingle stanza sent to the user.
If there is no such attribute, the action will be set to regular Jingle transport-info
.
Non-standard Jingle existing-session-initiate stanza
MongooseIM allows a user to ask for an unanswered session-initiate
request.
This may be useful in web applications when there is a need to handle the call in a new browser window.
In order to get the session-initiate
, which was not answered yet, the user can send a get
Jingle stanza to self with action set to existing-session-initiate
.
As a result, MongooseIM will resend the original session-initiate
request to the device which sent the query.
Prerequisites
By default, MongooseIM is built without SIP support.
In order to build the server with SIP support, please use tools/configure
script before the release generation.
You may either pick only certain drivers (with SIP included) or simply use with-all
option. Examples:
1 2 3 |
|
MongooseIM packages are built with Jingle/SIP support.
Options
modules.mod_jingle_sip.proxy_host
- Syntax: string
- Default:
"localhost"
- Example:
proxy_host = "localhost"
The name or IP address of the SIP Proxy to which MongooseIM will send SIP messages.
modules.mod_jingle_sip.proxy_port
- Syntax: non-negative integer
- Default:
5600
- Example:
proxy_port = 5600
The port of the SIP Proxy.
modules.mod_jingle_sip.listen_port
- Syntax: non-negative integer
- Default:
5600
- Example:
listen_port = 5600
The port on which MongooseIM will listen for incomming SIP messages.
modules.mod_jingle_sip.local_host
- Syntax: string
- Default:
"127.0.0.1"
- Example:
local_host = "localhost"
The value used to create SIP URIs (including VIA headers).
modules.mod_jingle_sip.sdp_origin
- Syntax: string
- Default:
"127.0.0.1"
- Example:
sdp_origin = "127.0.0.1"
The value of the c=
SDP attribute.
The simplest configuration is the following:
1 |
|
With this configuration MongooseIM will try sending SIP messages to a SIP proxy listening on localhost and port 5600.
Use cases covered by tests
Currently to test the functionality we use a SIP Proxy mock written in Erlang.
The following scenarios are covered by our tests in big_tests/tests/jingle_SUITE.erl
All the sequence diagrams where generated with textart.io/sequence.
The source code is embedded in the markdown file below every diagram inside a comment <!--- --->
1. Establishing a session with another XMPP user
With the mod_jingle_sip enabled, all Jingle IQ set stanzas listed above are intercepted, translated to SIP packets and sent to a SIP Proxy. This means that the current implementation will also translate stanzas addressed to a user in the same domain. This allows the SIP entity to control how the call between XMPP users is established. Below there are sequence diagrams showing the communication between XMPP users, MongooseIM and SIP Proxy as in our tests. It's possible that the SIP Proxy or other SIP entity decides that the call needs to be forked and delivered to the user's phone number instead of generating a corresponding call back to MongooseIM.
1.1 Signaling session-initiate to other XMPP user via SIP Proxy
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
1.2 Signaling session-accept to other XMPP user via SIP Proxy
When the other user accepts the call invite sent by the first, the following sequence is executed. This is a continuation of the previous example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
1.3 Terminating a call
Any Jingle session (accepted or not) can be terminated by sending a Jingle stanza with action session-terminate
and a reason.
In the SIP world it's more complex.
See the following examples for more information.
1.3.1 Terminating an accepted call
The easiest scenario is when the call was accepted as in 1.2.
In this case one of the users sends a session-terminate
Jingle action with a reason success
.
This is translated to a SIP BYE
request with to
and from
headers set appropriately -
from
is the user who wants to terminate the call and to
is the user on the other end of the session.
The BYE
request is sent to the SIP Proxy and then to the other user in a similar way to session acceptance.
1.3.2 Terminating an unanswered call by initiator
To terminate the call before it's accepted, the initiator sends a Jingle session-terminate
stanza with a reason decline
.
Then MongooseIM translates this to a SIP CANCEL
request which is sent to the SIP Proxy.
1.3.3 Rejecting the call
When the invitee wants to terminate the call, on the XMPP level this is also a Jingle session-terminate
stanza with a reason decline
.
MongooseIM translates this to SIP 486 Busy Here
Response (because this is a response to the invite request).
2. Establishing a session with a SIP user
Establishing a session with a SIP user (or a SIP entity) works the same as in the previous section. The only difference is that the SIP Proxy will not call MongooseIM back (as it may happen for call to other XMPP user). Instead the SIP message sent by MongooseIM to SIP Proxy will be delivered directly to the SIP user's device.