Table of Contents
List of Tables
List of Examples
parameterThe module enables the handling of "Event: dialog" (as defined in RFC 4235) inside of the presence module. This can be used distribute the dialog-info status to the subscribed watchers.
The module does not currently implement any authorization rules. It assumes that publish requests are only issued by an authorized application and subscribe requests only by authorized users. Authorization can thus be easily done in OpenSIPS configuration file before calling handle_publish() and handle_subscribe() functions.
Note: This module only activates the processing of the "dialog" in the presence module. To send dialog-info to watchers you also need a source which PUBLISH the dialog info to the presence module. For example you can use the pua_dialoginfo module or any external component. This approach allows to have the presence server and the dialog-info aware publisher (e.g. the main proxy) on different OpenSIPS instances.
This module by default does body aggregation. That means, if the presence module received PUBLISH from multiple presentities (e.g. if the entity has multiple dialogs the pua_dialoginfo will send multiple PUBLISH), the module will parse all the received (and still valid, depending on the Expires header in the PUBLISH request) XML documents and generate a single XML document with multiple "dialog" elements. This is perfectly valid, but unfortunately not supported by all SIP phones, e.g. Linksys SPA962 crashes when it receives dialog-info with multiple dialog elements. In this case use the force_single_dialog module parameter.
To get better understanding how all the module works together please take a look at the follwing figure:
Main Proxy and Presence Server on the same Instance caller proxy & callee watcher alice@example presence bob@example watcher@example server | | | | | |<-------SUBSCRIBE bob-------| | |--------200 OK------------->| | |--------NOTIFY------------->| | |<-------200 OK--------------| | | | | |--INV bob--->| | | | |--INV bob-->| | | |<-100-------| | | | | | | |<-180 ring--| | |<--180 ring--| | | | |-- | | | | \ | | | | PUBLISH bob| | | | / | | | |<- | | | | | | | |-- | | | | \ | | | | 200 ok | | | | / | | | |<- | | | |--------NOTIFY------------->| | |<-------200 OK--------------| | | | |
The watcher subscribes the "Event: dialog" of Bob.
Alice calls Bob.
Bob replies with ringing, the dialog in the dialog module transits to "early". The callback in pua_dialoginfo is executed. The pua_dialoginfo module creates the XML document and uses the pua module to send the PUBLISH. (pua module itself uses tm module to send the PUBLISH stateful)
PUBLISH is received and handled by presence module. Presence module updates the "presentity". Presence module checks for active watchers of the presentity. It gives all the XML dcouments to presence_dialoginfo module to aggregate them into a single XML document. Then it sends the NOTIFY with the aggregated XML document to all active watchers.
The presence server can also be separated from the main proxy by using a separate OpenSIPS instance as shown in the following figure. (Either set the outbound_proxy parameter of pua module or make sure to route the "looped" PUBLISH requests from the main proxy to the presence server).
Main Proxy and Presence Server use a separate Instance caller proxy & presence callee watcher alice@example server server bob@example watcher@example | | | | | | |<--------------------SUBSCRIBE bob-------| | |-SUBSC bob->| | | | |<-200 ok----| | | | |---------------------200 OK------------->| | | .... NOTIFY ... 200 OK ... | | | | | | | | | | | |--INV bob--->| | | | | |--INV bob------------------>| | | |<-100-----------------------| | | | | | | | |<-180 ring------------------| | |<--180 ring--| | | | | |--PUBL bob->| | | | |<-200 ok----| | | | | |--------NOTIFY------------->| | | |<-------200 OK--------------| | | | | |
Known issues:
The "version" attribute is increased for every NOTIFY, even if the XML document has not changed. This is of course valid, but not very smart.
By default the module aggregates all available dialog info into a single dialog-info document containing multiple "dialog" elements. If the phone does not support this, you can activate this parameter.
If this parameter is set, only the dialog element with the currently most interesting dialog state will be put into the dialog-info document. Thus, the dialog-info element will contain only a single "dialog" element. The algorithm chooses the state based onf the following order of priority (least important first): terminated, trying, proceeding, confirmed, early. Note: I consider the "early" state more intersting than confirmed as often you might want to pickup a call if the originall callee is already busy in a call.
Default value is “0”.
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
Name | DevScore | Commits | Lines ++ | Lines -- | |
---|---|---|---|---|---|
1. | Bogdan-Andrei Iancu (@bogdan-iancu) | 13 | 11 | 58 | 27 |
2. | Klaus Darilion | 11 | 1 | 1181 | 0 |
3. | Liviu Chircu (@liviuchircu) | 9 | 6 | 21 | 58 |
4. | Walter Doekes (@wdoekes) | 7 | 4 | 66 | 82 |
5. | Ovidiu Sas (@ovidiusas) | 6 | 4 | 78 | 18 |
6. | shiningstarj | 4 | 2 | 2 | 2 |
7. | Angel Marin | 3 | 1 | 123 | 1 |
8. | Anca Vamanu | 3 | 1 | 14 | 18 |
9. | Razvan Crainea (@razvancrainea) | 3 | 1 | 8 | 8 |
10. | Vallimamod Abdullah | 3 | 1 | 4 | 3 |
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
Name | Commit Activity | |
---|---|---|
1. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jul 2009 - Jun 2018 |
2. | Liviu Chircu (@liviuchircu) | Mar 2014 - Jun 2018 |
3. | shiningstarj | Oct 2015 - Oct 2015 |
4. | Razvan Crainea (@razvancrainea) | Aug 2015 - Aug 2015 |
5. | Walter Doekes (@wdoekes) | Apr 2010 - Mar 2014 |
6. | Ovidiu Sas (@ovidiusas) | Oct 2010 - Jan 2013 |
7. | Anca Vamanu | Dec 2010 - Dec 2010 |
8. | Vallimamod Abdullah | Oct 2010 - Oct 2010 |
9. | Angel Marin | Mar 2010 - Mar 2010 |
10. | Klaus Darilion | Dec 2008 - Dec 2008 |
(1) including any documentation-related commits, excluding merge commits
Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Walter Doekes (@wdoekes), Klaus Darilion.
doc copyrights:
Copyright © 2008 Klaus Darilion, IPCom (Module implementation was partly sponsored by Silver Server (www.sil.at))
Copyright © 2007 Juha Heinanen