presence_dialoginfo Module
     __________________________________________________________

   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

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   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
   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.

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.

Chapter 2. Contributors

2.1. By Commit Statistics

   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) 14 12 62 30
   2. Liviu Chircu (@liviuchircu) 13 10 29 78
   3. Razvan Crainea (@razvancrainea) 11 9 15 19
   4. Klaus Darilion 11 1 1181 0
   5. Walter Doekes (@wdoekes) 7 4 66 82
   6. Ovidiu Sas (@ovidiusas) 6 4 78 18
   7. shiningstarj 4 2 2 2
   8. Angel Marin 4 1 123 1
   9. Anca Vamanu 3 1 14 18
   10. Vallimamod Abdullah 3 1 4 3

   All remaining contributors: Maksym Sobolyev (@sobomax), Peter
   Lemenkov (@lemenkov), Vlad Patrascu (@rvlad-patrascu).

   (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

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   2.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2009 - May 2022
   3.  Liviu Chircu (@liviuchircu)         Mar 2014 - Apr 2020
   4.  Razvan Crainea (@razvancrainea)     Aug 2015 - Sep 2019
   5.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - May 2017
   7.  shiningstarj                        Oct 2015 - Oct 2015
   8.  Walter Doekes (@wdoekes)            Apr 2010 - Mar 2014
   9.  Ovidiu Sas (@ovidiusas)             Oct 2010 - Jan 2013
   10. Anca Vamanu                         Dec 2010 - Dec 2010

   All remaining contributors: Vallimamod Abdullah, Angel Marin,
   Klaus Darilion.

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Walter
   Doekes (@wdoekes), Klaus Darilion.

   Documentation Copyrights:

   Copyright © 2008 Klaus Darilion, IPCom (Module implementation
   was partly sponsored by Silver Server (www.sil.at))

   Copyright © 2007 Juha Heinanen
