presence_dialoginfo Module
Juha Heinanen
<jh@tutpro.com>
Klaus
Darilion
<klaus.darilion@mailinglists@pernau.at>
Edited by
Juha Heinanen
<jh@tutpro.com>
Edited by
Klaus Darilion
<klaus.darilion@mailinglists@pernau.at>
Copyright © 2007 Juha Heinanen
Copyright © 2008 Klaus Darilion, IPCom (Module implementation
was partly sponsored by Silver Server (www.sil.at))
Revision History
Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300
(Tue, 21 Jul 2009) $
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. force_single_dialog (int)
1.4. Exported Functions
List of Examples
1.1. Set parameter
Chapter 1. Admin Guide
1.1. Overview
The 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 ..... 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.
1.2. Dependencies
1.2.1. OpenSIPS Modules
The following modules must be loaded before this module:
* presence.
1.2.2. External Libraries or Applications
None.
1.3. Exported Parameters
1.3.1. force_single_dialog (int)
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".
Example 1.1. Set parameter
...
modparam("presence_dialoginfo", "force_single_dialog", 1)
...
1.4. Exported Functions
None to be used in configuration file.
