modules_k/presence_dialoginfo/README
e9e0c85e
 presence_dialoginfo Module
fed075fa
 
 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>
 
d9bb387b
    Copyright © 2007 Juha Heinanen
fed075fa
 
d9bb387b
    Copyright © 2008 Klaus Darilion, IPCom (Module implementation was
    partly sponsored by Silver Server (www.sil.at))
      __________________________________________________________________
fed075fa
 
    Table of Contents
 
    1. Admin Guide
 
d9bb387b
         1. Overview
         2. Dependencies
fed075fa
 
d9bb387b
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
fed075fa
 
d9bb387b
         3. Exported Parameters
fed075fa
 
d9bb387b
               3.1. force_single_dialog (int)
fed075fa
 
d9bb387b
         4. Exported Functions
fed075fa
 
    List of Examples
 
    1.1. Set parameter
 
 Chapter 1. Admin Guide
 
d9bb387b
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Exported Parameters
 
         3.1. force_single_dialog (int)
 
    4. Exported Functions
 
 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 Kamailio configuration file
    before calling handle_publish() and handle_subscribe() functions.
fed075fa
 
d9bb387b
    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 Kamailio instances.
fed075fa
 
d9bb387b
    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:
fed075fa
     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.
d9bb387b
      * 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 Kamailio 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).
fed075fa
     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:
d9bb387b
      * 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.
fed075fa
 
d9bb387b
 2. Dependencies
fed075fa
 
d9bb387b
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
fed075fa
 
    The following modules must be loaded before this module:
      * presence.
 
d9bb387b
 2.2. External Libraries or Applications
fed075fa
 
    None.
 
d9bb387b
 3. Exported Parameters
 
    3.1. force_single_dialog (int)
fed075fa
 
d9bb387b
 3.1. force_single_dialog (int)
fed075fa
 
d9bb387b
    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.
fed075fa
 
d9bb387b
    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.
fed075fa
 
d9bb387b
    Default value is “0”.
fed075fa
 
    Example 1.1. Set parameter
 ...
 modparam("presence_dialoginfo", "force_single_dialog", 1)
 ...
 
d9bb387b
 4. Exported Functions
fed075fa
 
    None to be used in configuration file.