<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		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.
	</para>
	<para>
		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)
	</para>
	<para>
		The module is based on code (copy/paste) from pua_usrloc and nat_traversal
		module.
	</para>
	<para>
		Following you will show some examples of a dialog-info XML document taken
		from RFC 4235. This will help you to understand the meaning of the module
		parameters:

			<programlisting format="linespecific">
<![CDATA[
<?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>
]]>
</programlisting>

		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.

	</para>
	<para>

		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 initiator of the dialog or the recipient (aka
		if the entity sent or received the first INVITE).

	</para>
	<para>

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

	</para>
	<para>

        The dialog element can contain optional "local" and "remote" elements which
        describes the local and the remote party in more detail, for example:

        <programlisting format="linespecific">
<![CDATA[
<?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>
]]>
</programlisting>

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

	</para>
	<para>

		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.

			<programlisting format="linespecific">
<![CDATA[
<?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>
]]>
</programlisting>

		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.

	</para>
	<para>

		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.
	</para>
	</section>
	<section>
	<title>Activate Functionality</title>
	<para>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.
	</para>
	</section>
	<section>
	<title>Known issues</title>
	<para>
		<itemizedlist>
			<listitem><para>
				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.
			</para></listitem>
			<listitem><para>
				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.
			</para></listitem>
			<listitem><para>
				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.
			</para></listitem>
		</itemizedlist>
	</para>
	</section>
		<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>dialog</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>pua</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
		<title>Parameters</title>

		<section>
		<title><varname>include_callid</varname> (int)</title>
		<para>
			If this parameter is set, the optional call-id will be put into the
			dialog element. This is needed for call-pickup features.
		</para>
		<para>
			<emphasis>Default value is <quote>1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>include_callid</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "include_callid", 0)
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>include_tags</varname> (int)</title>
		<para>
			If this parameter is set, the local and remote tag will be put
			into the dialog element. This is needed for call-pickup features.
		</para>
		<para>
			<emphasis>Default value is <quote>1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>include_tags</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "include_tags", 0)
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>include_localremote</varname> (int)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>include_localremote</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "include_localremote", 0)
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>override_lifetime</varname> (int)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>override_lifetime</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "override_lifetime", 300)
...
</programlisting>
		</example>
		</section>

	<section>
		<title><varname>include_req_uri</varname> (int)</title>
		<para>
			controls if R-URI is going to be used instead of To header value in
			the PUBLISH as "identity" on "remote" node.
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>. Disabled</emphasis>
		</para>
		<example>
			<title>Set <varname>include_req_uri</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "include_req_uri", 1)
...
</programlisting>
		</example>
	</section>

		<section>
		<title><varname>caller_confirmed</varname> (int)</title>
		<para>
			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 signaled as "confirmed" even
			in "early" state. This is a workaround for the buggy Linksys SPA962
			phones. SNOM phones work well with the default setting.
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>caller_confirmed</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "caller_confirmed", 1)
...
</programlisting>
		</example>
		</section>

	<section>
		<title><varname>send_publish_flag</varname> (int)</title>
		<para>
			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).
		</para>
		<para>
			<emphasis>Default value is <quote>-1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>send_publish_flag</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "send_publish_flag", 8)
...
</programlisting>
		</example>
		</section>

	<section>
		<title><varname>disable_caller_publish_flag</varname> (int)</title>
		<para>
			This message flag indicates whether to send caller (initiator) PUBLISH requests or not.
			If set, PUBLISH requests are not sent for the caller (initiator).
		</para>
		<para>
			<emphasis>Default value is <quote>-1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>disable_caller_publish_flag</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "disable_caller_publish_flag", 9)
...
</programlisting>
		</example>
		</section>

	<section>
		<title><varname>disable_callee_publish_flag</varname> (int)</title>
		<para>
			This message flag indicates whether to send callee (recipient) PUBLISH requests or not.
			If set, PUBLISH requests are not sent for the callee (recipient).
		</para>
		<para>
			<emphasis>Default value is <quote>-1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>disable_callee_publish_flag</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "disable_callee_publish_flag", 10)
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>use_pubruri_avps</varname> (int)</title>
		<para>
			Get Publish R-Uri from avps (see corresponding avp params), not from request to/from uri.
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>use_pubruri_avps</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "use_pubruri_avps", 1)
...
</programlisting>
		</example>
		</section>

	<section id="pua_dialoginfo.p.refresh_pubruri_avps_flag">
		<title><varname>refresh_pubruri_avps_flag</varname> (int)</title>
		<para>
			If use_pubruri_avps is enabled, this message flag indicates whether to refresh R-Uri from avps before sending the PUBLISH requests.
		</para>
		<para>
			<emphasis>Default value is <quote>-1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>refresh_pubruri_avps_flag</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "refresh_pubruri_avps_flag", 11)
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>pubruri_caller_avp</varname> (str)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>NULL</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>pubruri_caller_avp</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "pubruri_caller_avp", "$avp(s:puburis_caller)")
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>pubruri_callee_avp</varname> (str)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>NULL</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>pubruri_callee_avp</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "pubruri_callee_avp", "$avp(s:puburis_callee)")
...
</programlisting>
		</example>
		</section>

		<section id="pua_dialoginfo.p.pubruri_caller_dlg_var">
		<title><varname>pubruri_caller_dlg_var</varname> (str)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>NULL</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>pubruri_caller_avp</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "pubruri_caller_dlg_var", "pubruri_caller")
...
</programlisting>
		</example>
		</section>

		<section id="pua_dialoginfo.p.pubruri_callee_dlg_var">
		<title><varname>pubruri_callee_dlg_var</varname> (str)</title>
		<para>
			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.
		</para>
		<para>
			<emphasis>Default value is <quote>NULL</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>pubruri_callee_dlg_var</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "pubruri_callee_dlg_var", "pubruri_callee")
...
</programlisting>
		</example>
		</section>

		<section>
		<title><varname>callee_trying</varname> (int)</title>
		<para>
			If this parameter is set, a "Trying" state will be sent for both the
			caller and callee, rather than just the caller.
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>callee_trying</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "callee_trying", 1)
...
</programlisting>
		</example>
		</section>

                <section>
                <title><varname>caller_entity_when_publish_disabled</varname> (int)</title>
                <para>
                        Must be a valid sip uri.
                        If this parameter is set, this uri is used as caller entity in
                        publish xml body if associated dialog has the flag
                        disable_caller_publish_flag set.
                        Note only the flag received on dialog creation is used to activate
                        this feature.
                </para>
                <para>
                        <emphasis>Default value is <quote>NULL</quote>.</emphasis>
                </para>
                <example>
                        <title>Set <varname>caller_entity_when_publish_disabled</varname> parameter</title>
                        <programlisting format="linespecific">
...
modparam("pua_dialoginfo", "caller_entity_when_publish_disabled", "sip:caller@publish.disabled.com")
...
			</programlisting>
                </example>
                </section>

                <section>
                <title><varname>callee_entity_when_publish_disabled</varname> (int)</title>
                <para>
                        Must be a valid sip uri.
                        If this parameter is set, this uri is used as callee entity in
                        publish xml body if associated dialog has the flag
                        disable_callee_publish_flag set.
                        Note only the flag received on dialog creation is used to activate
                        this feature.
                </para>
                <para>
                        <emphasis>Default value is <quote>NULL</quote>.</emphasis>
                </para>
                <example>
                        <title>Set <varname>callee_entity_when_publish_disabled</varname> parameter</title>
                        <programlisting format="linespecific">
...
modparam("pua_dialoginfo", "callee_entity_when_publish_disabled", "sip:callee@publish.disabled.com")
...
			</programlisting>
                </example>
                </section>

                <section>
                <title><varname>publish_dialog_req_within</varname> (int)</title>
                <para>
                        If this parameter is set to 1, subsequents requests received in dialog generate
                        corresponding publish request.
                </para>
                <para>
                        <emphasis>Default value is <quote>1</quote>.</emphasis>
                </para>
                <example>
                        <title>Set <varname>publish_dialog_req_within</varname> parameter</title>
                        <programlisting format="linespecific">
...
modparam("pua_dialoginfo", "publish_dialog_req_within", 0)
...
			</programlisting>
                </example>
                </section>

		<section id="pua_dialoginfo.p.local_identity_dlg_var">
		<title><varname>local_identity_dlg_var</varname> (str)</title>
		<para>
			PUBLISH-requests reporting dialog-information will use the value of
			the dialog variable if exists
		</para>
		<para>
			<emphasis>Default value is <quote>NULL</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>local_identity_dlg_var</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "local_identity_dlg_var", "local_identity")
...
</programlisting>
		</example>
		</section>

        <section id="pua_dialoginfo.p.attribute_display">
            <title><varname>attribute_display</varname> (int)</title>
            <para>
            If set to 1, the display name attribute is added with user part of the
            URI for local and remote targets.
            </para>
            <para>
                <emphasis>Default value is <quote>0</quote>.</emphasis>
            </para>
            <example>
                <title>Set <varname>attribute_display</varname> parameter</title>
                <programlisting format="linespecific">
...
modparam("pua_dialoginfo", "attribute_display", 1)
...
</programlisting>
            </example>
        </section>

    </section>

	<section>
	<title>Functions</title>
	</section>

</chapter>

