[sip-router] / src / modules / pua_dialoginfo / README

pua dialoginfo

Anca-Maria Vamanu

   Voice Sistem SRL

Edited by

Anca-Maria Vamanu

Klaus Darilion

   IPCom (Module implementation was partly sponsored by Silver Server
   (www.sil.at))

Edited by

Klaus Darilion

   IPCom

Edited by

Phil Lavin

   Copyright © 2006 Voice Sistem SRL

   Copyright © 2008 Klaus Darilion IPCom
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Activate Functionality
        3. Known issues
        4. Dependencies

              4.1. Kamailio Modules
              4.2. External Libraries or Applications

        5. Parameters

              5.1. include_callid (int)
              5.2. include_tags (int)
              5.3. include_localremote (int)
              5.4. override_lifetime (int)
              5.5. caller_confirmed (int)
              5.6. send_publish_flag (int)
              5.7. use_pubruri_avps (int)
              5.8. pubruri_caller_avp (int)
              5.9. pubruri_callee_avp (int)
              5.10. pubruri_caller_dlg_var (str)
              5.11. pubruri_callee_dlg_var (int)
              5.12. callee_trying (int)

        6. Functions

   List of Examples

   1.1. Set include_callid parameter
   1.2. Set include_tags parameter
   1.3. Set include_localremote parameter
   1.4. Set override_lifetime parameter
   1.5. Set caller_confirmed parameter
   1.6. Set send_publish_flag parameter
   1.7. Set use_pubruri_avps parameter
   1.8. Set pubruri_caller_avp parameter
   1.9. Set pubruri_callee_avp parameter
   1.10. Set pubruri_caller_avp parameter
   1.11. Set pubruri_callee_dlg_var parameter
   1.12. Set callee_trying parameter

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Activate Functionality
   3. Known issues
   4. Dependencies

        4.1. Kamailio Modules
        4.2. External Libraries or Applications

   5. Parameters

        5.1. include_callid (int)
        5.2. include_tags (int)
        5.3. include_localremote (int)
        5.4. override_lifetime (int)
        5.5. caller_confirmed (int)
        5.6. send_publish_flag (int)
        5.7. use_pubruri_avps (int)
        5.8. pubruri_caller_avp (int)
        5.9. pubruri_callee_avp (int)
        5.10. pubruri_caller_dlg_var (str)
        5.11. pubruri_callee_dlg_var (int)
        5.12. callee_trying (int)

   6. Functions

1. Overview

   The pua_dialoginfo retrieves dialog state information from the dialog
   module and PUBLISHes the dialog-information using the pua module. Thus,
   in combination with the presence_xml module this can be used to derive
   dialog-info from the dialog module and NOTIFY the subscribed watchers
   about dialog-info changes. This can be used for example with SNOM and
   Linksys phones.

   Note: This implements dialog-info according to RFC 4235 and is not
   compatible with the BLA feature defined in
   draft-anil-sipping-bla-03.txt. (Actually the BLA draft is really crap
   as it changes SIP semantics)

   The module is based on code (copy/paste) from pua_usrloc and
   nat_traversal module.

   Following you will show some examples of an dialog-info XML document
   taken from RFC 4235. This will help you to understand the meaning of
   the module parameters:
<?xml version="1.0"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
             version="1"
             state="full"
             entity="sip:alice@example.com">
    <dialog id="as7d900as8"
            call-id="a84b4c76e66710"
            local-tag="1928301774"
            remote-tag="456887766"
            direction="initiator">
        <state>early</state>
    </dialog>
</dialog-info>

   The root element is the "dialog-info". It contains the namespace, the
   version (which must be incremented for each new PUBLISH for this
   certain dialog), the state (this module only supports state=full) and
   the entity for which we publish the dialog-info.

   The "dialog" element must contain an id parameter. The id parameter is
   usually different to the optional call-id parameter (which is the
   call-id of the INVITE request) as an INVITE can create multiple dialogs
   (forked request). But as the dialog module does not support multiple
   dialogs created by a single transaction, the pua_dialoginfo module sets
   the id parameter to the same value as the call-id parameter. The
   "local-tag" indicates the local tag of the entity. The remote-tag
   indicates the tag of the remote party. The "direction" indicates if the
   entity was the initator of the dialog or the recepient (aka if the
   entity sent or received the first INVITE).

   The "state" element describes the state of the dialog state machine and
   must be either: trying, proceeding, early, confirmed or terminated.

   The dialog element can contain optional "local" and "remote" elements
   which decsribes the local and the remote party in more detail, for
   example:
<?xml version="1.0" encoding="UTF-8"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
             version="1" state="full">
    <dialog id="as7d900as8"
            call-id="a84b4c76e66710"
            local-tag="1928301774"
            remote-tag="456887766"
            direction="initiator">
        <state>early</state>
        <local>
            <identity display="Alice">sip:alice@example.com</identity>
            <target uri="sip:alice@phone11.example.com"/>
        </local>
        <remote>
            <identity display="Bob">sip:bob@example.org</identity>
            <target uri="sip:bobster@phone21.example.org"/>
        </remote>
    </dialog>
</dialog-info>

   The local and remote elements are needed to implement call pickup. For
   example if the above XML document is received by somebody who
   SUBSCRIBEd the dialog-info of Alice, then it can pick-up the call by
   sending an INVITE to Bob (actually I am not sure if it should use the
   URI in the identity element or the URI in the target parameter) which
   contains a Replaces header which contains the call-id and the tags.
   This was tested successfully with Linksys SPA962 phones and with SNOM
   320 Firmware 7.3.7 (you have to set the function key to "Extension").

   A dialog-info XML document may contain multiple "dialog" elements, for
   example if the entity has multiple ongoing dialogs. For example the
   following XML document shows a confirmed dialog and an early (probably
   a second incoming call) dialog.
<?xml version="1.0"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
             version="3"
             state="full"
             entity="sip:alice@example.com">
    <dialog id="as7d900as8" call-id="a84b4c76e66710"
            local-tag="1928301774" remote-tag="hh76a"
            direction="initiator">
        <state>confirmed</state>
    </dialog>
    <dialog id="j7zgt54" call-id="ASDRRVASDRF"
            local-tag="123456789" remote-tag="EE345"
            direction="recipient">
        <state>early</state>
    </dialog>
</dialog-info>

   As the dialog module callbacks only address a certain dialog, the
   pua_dialoginfo always PUBLISHes XML documents with a single "dialog"
   element. If an entity has multiple concurrent dialogs, the
   pua_dialoginfo module will send PUBLISH for each dialog. These multiple
   "presenties" can be aggregated by the presence_dialoginfo module into a
   single XML document with multiple "dialog" elements. Please see the
   description of the presence_dialoginfo module for details about the
   aggregation.

   If there are problems with the callbacks from dialog module and you
   want to debug them you define PUA_DIALOGINFO_DEBUG in pua_dialoginfo.c
   and recompile.

2. Activate Functionality

   This module is directly coupled with the dialog module. Thus, if the
   module is loaded, it is automatically active for all calls tracked by
   the dialog module. Thus, make sure that you activate the dialog module
   for a certain call if you want dialog-state to be PUBLISHED. This
   means, the dlg_flag of the dialog module must be configured and the
   respective flag must be set during call processing.

3. Known issues

     * The module tries to find out if the entity is a local user. Only
       PUBLISH to local user are sent. Therefore, the module needs to find
       out if the domain is a local one or not. It uses the same mechanism
       as the "==myself" mechanism. Thus, all domains have to be declared
       with the "alias=..." option in Kamailio.cfg. DB-based multidomain
       support as offered by "domain" module is not supported yet.
       Conclusion: The module has the same "domain" problems as the "rr"
       module.
     * The module puts the call-id of the dialog into an XML parameter.
       Thus, if the call-id contains quotes, they should be escaped. This
       is not yet implemented. Thus, if the call-id contains quotes the
       XML document will be invalid.
     * The module derives the AoR of the callee from the To: header. Thus,
       if the To header does not contain the canonical AoR the PUBLISH
       might have the wrong SIP URI in the RURI and the entity parameter.

4. Dependencies

   4.1. Kamailio Modules
   4.2. External Libraries or Applications

4.1. Kamailio Modules

   The following modules must be loaded before this module:
     * dialog.
     * pua.

4.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libxml.

5. Parameters

   5.1. include_callid (int)
   5.2. include_tags (int)
   5.3. include_localremote (int)
   5.4. override_lifetime (int)
   5.5. caller_confirmed (int)
   5.6. send_publish_flag (int)
   5.7. use_pubruri_avps (int)
   5.8. pubruri_caller_avp (int)
   5.9. pubruri_callee_avp (int)
   5.10. pubruri_caller_dlg_var (str)
   5.11. pubruri_callee_dlg_var (int)
   5.12. callee_trying (int)

5.1. include_callid (int)

   If this parameter is set, the optional call-id will be put into the
   dialog element. This is needed for call-pickup features.

   Default value is “1”.

   Example 1.1. Set include_callid parameter
...
modparam("pua_dialoginfo", "include_callid", 0)
...

5.2. include_tags (int)

   If this parameter is set, the local and remote tag will be put into the
   dialog element. This is needed for call-pickup features.

   Default value is “1”.

   Example 1.2. Set include_tags parameter
...
modparam("pua_dialoginfo", "include_tags", 0)
...

5.3. include_localremote (int)

   If this parameter is set, the optional local and remote elements will
   be put into the dialog element. This is needed for call-pickup
   features.

   Default value is “1”.

   Example 1.3. Set include_localremote parameter
...
modparam("pua_dialoginfo", "include_localremote", 0)
...

5.4. override_lifetime (int)

   The PUBLISH requests used to send the dialog-info contain an Expires
   header. The value of the expires is usually taken from the lifetime of
   the dialog (see README of dialog module). If the override_lifetime is
   set, the value specified here is used instead of the lifetime of the
   dialog module. If used, the value should at least be a few seconds more
   than the fr_inv_timer of the tm module.

   Default value is “0”.

   Example 1.4. Set override_lifetime parameter
...
modparam("pua_dialoginfo", "override_lifetime", 300)
...

5.5. caller_confirmed (int)

   Usually the dialog-info of the caller will be "trying -> early ->
   confirmed" and the dialog-info of the callee will be "early ->
   confirmed". On some phones the function LED will start blinking if the
   state is early, regardless if is is the caller or the callee (indicated
   with the "direction" parameter). To avoid blinking LEDs for the caller,
   you can enable this parameter. Then the state of the caller will be
   singaled as "confirmed" even in "early" state. This is a workaround for
   the buggy Linksys SPA962 phones. SNOM phones work well with the default
   setting.

   Default value is “0”.

   Example 1.5. Set caller_confirmed parameter
...
modparam("pua_dialoginfo", "caller_confirmed", 1)
...

5.6. send_publish_flag (int)

   This message flag indicates whether to send PUBLISH requests or not. If
   not set, PUBLISH requests are sent out only if their R-URI is local
   (according to myself).

   Default value is “-1”.

   Example 1.6. Set send_publish_flag parameter
...
modparam("pua_dialoginfo", "send_publish_flag", 8)
...

5.7. use_pubruri_avps (int)

   Get Publish R-Uri from avps (see corresponding avp params), not from
   reqeust to/from uri.

   Default value is “0”.

   Example 1.7. Set use_pubruri_avps parameter
...
modparam("pua_dialoginfo", "use_pubruri_avps", 1)
...

5.8. pubruri_caller_avp (int)

   If use_pubruri_avps is enabled, PUBLISH-requests reporting
   dialog-information about the caller (entity=caller) are sent using the
   value of the specified avp as R-Uri. If multiple AVPs with the same
   name (but different indexes) are present, for each value a
   corresponding PUBLISH-request is generated. If no AVP with the
   specified name exists, no caller-related PUBLISH requests are sent.

   Default value is “NULL”.

   Example 1.8. Set pubruri_caller_avp parameter
...
modparam("pua_dialoginfo", "pubruri_caller_avp", "$avp(s:puburis_caller)")
...

5.9. pubruri_callee_avp (int)

   If use_pubruri_avps is enabled, PUBLISH-requests reporting
   dialog-information about the callee (entity=callee) are sent using the
   value of the specified avp as R-Uri. If multiple AVPs with the same
   name (but different indexes) are present, for each value a
   corresponding PUBLISH-request is generated. If no AVP with the
   specified name exists, no callee-related PUBLISH requests are sent.

   Default value is “NULL”.

   Example 1.9. Set pubruri_callee_avp parameter
...
modparam("pua_dialoginfo", "pubruri_callee_avp", "$avp(s:puburis_callee)")
...

5.10. pubruri_caller_dlg_var (str)

   Must be set to the name of dialog variable where to store the URI for
   caller, used to send the notifications. This is needed to restored the
   value after Kamailio restart. If not set, loaded dialogs at restart are
   no longer sending notifications. New dialogs are working fine.

   Default value is “NULL”.

   Example 1.10. Set pubruri_caller_avp parameter
...
modparam("pua_dialoginfo", "pubruri_caller_dlg_var", "pubruri_caller")
...

5.11. pubruri_callee_dlg_var (int)

   Must be set to the name of dialog variable where to store the URI for
   callee, used to send the notifications. This is needed to restored the
   value after Kamailio restart. If not set, loaded dialogs at restart are
   no longer sending notifications. New dialogs are working fine.

   Default value is “NULL”.

   Example 1.11. Set pubruri_callee_dlg_var parameter
...
modparam("pua_dialoginfo", "pubruri_callee_dlg_var", "pubruri_callee")
...

5.12. callee_trying (int)

   If this parameter is set, a "Trying" state will be sent for both the
   caller and callee, rather than just the caller.

   Default value is “0”.

   Example 1.12. Set callee_trying parameter
...
modparam("pua_dialoginfo", "callee_trying", 1)
...

6. Functions