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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<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 an 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 initator of the dialog or the recepient (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>

		To enable dialoginfo notifications for a certain dialog, you must call
		<xref linkend="func_dialoginfo_set"/> function for that dialog.
		This function can take one parameter which through which you can tell the
		module to publish dialoginfo only for one side of the call. This is useful
		because you want to store dialoginfo only for the local users, and you can
		decide from the script if the call parties are local users and give the correct
		parameter to this function to tell it to send generate dialoginfo only for the
		local users. The possible values are : "A" - corresponding to generate dialoginfo
		only for the caller and "B" - generate dialoginfo only for the callee. If no parameter
		is given, the module will generate dialoginfo for both parties.

		It is possible to specify what URIs should be used for caller and callee by setting the
		the pseudovariables with the names defined as module parameter "caller_spec_param" and
		"callee_spec_param" before calling <xref linkend="func_dialoginfo_set"/> function.
		Please read the description of this parameters in
		<xref linkend="exported_parameters"/> section. If this parameters are
		not set, the default sources will be used, From header for the caller
		and display name in To header + RURI for the callee.
	</para>
	<para>
		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 id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; 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
		&osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>

		<section id="param_include_callid" xreflabel="include_callid">
		<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 id="param_include_tags" xreflabel="include_tags">
		<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 id="param_include_localremote" xreflabel="include_localremote">
		<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 id="param_caller_confirmed" xreflabel="caller_confirmed">
		<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 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.
		</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 id="param_publish_on_trying" xreflabel="publish_on_trying">
		<title><varname>publish_on_trying</varname> (int)</title>
		<para>
			Usually the dialog-info of the caller will be
			"trying -> early -> confirmed". The "trying" state will be triggered as soon
			as you call <xref linkend="func_dialoginfo_set"/> on the caller, while "early" is triggered
			as soon as the callee is ringing (triggered by a 180 or 183 provisional reply).
			Sometimes, it is advisable to be notified only when the callee reaches
			the early state and not before. In other cases, it is advisable to
			notify the early state. This setting allows controlling the behavior.
		</para>
		<para>
			The intended purpose of this parameter is to reduce the rate of notifications
			(see RFC4235, section 3.10. Rate of Notifications).
		</para>
		<para>
			<emphasis>Default value is <quote>0</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>publish_on_trying</varname> parameter to 0</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "publish_on_trying", 0)

# Successful call scenario:
#
# UAC       proxy       UAS     presence server
#  |--INVITE-&gt;|          |            |
#  |&lt;-100-----|--INVITE-&gt;|            |
#  |          |&lt;-100-----|            |
#  |          |          |            |
#  |          |&lt;-18x-----|            |
#  |&lt;-18x-----|--PUBLISH(early)------&gt;|
#  |          |          |            |
#  |          |&lt;-200-----|            |
#  |&lt;-200-----|--PUBLISH(confirmed)--&gt;|
#  |--ACK----&gt;|          |            |
#  |          |--ACK----&gt;|            |
#  |          |          |            |
#
#
# Unsuccessful call scenario:
#
# UAC       proxy       UAS     presence server
#  |--INVITE-&gt;|          |            |
#  |&lt;-100-----|--INVITE-&gt;|            |
#  |          |&lt;-100-----|            |
#  |          |          |            |
#  |          |&lt;-456xx---|            |
#  |&lt;-456xx---|--ACK----&gt;|            |
#  |--ACK----&gt;|          |            |
...
</programlisting>
		</example>
		<example>
			<title>Set <varname>publish_on_trying</varname> parameter to 1</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "publish_on_trying", 1)

# Successful call scenario:
#
# UAC       proxy       UAS     presence server
#  |--INVITE-&gt;|          |            |
#  |&lt;-100-----|--INVITE-&gt;|            |
#  |          |--PUBLISH(trying)-----&gt;|
#  |          |&lt;-100-----|            |
#  |          |          |            |
#  |          |&lt;-18x-----|            |
#  |&lt;-18x-----|--PUBLISH(early)------&gt;|
#  |          |          |            |
#  |          |&lt;-200-----|            |
#  |&lt;-200-----|--PUBLISH(confirmed)--&gt;|
#  |--ACK----&gt;|          |            |
#  |          |--ACK----&gt;|            |
#  |          |          |            |
#
#
# Unsuccessful call scenario:
#
# UAC       proxy       UAS     presence server
#  |--INVITE-&gt;|          |            |
#  |&lt;-100-----|--INVITE-&gt;|            |
#  |          |--PUBLISH(trying)-----&gt;|
#  |          |&lt;-100-----|            |
#  |          |          |            |
#  |          |&lt;-456xx---|            |
#  |          |--PUBLISH(terminated)-&gt;|
#  |&lt;-456xx---|--ACK----&gt;|            |
#  |--ACK----&gt;|          |            |
...
</programlisting>
		</example>
		</section>

		<section id="param_nopublish_flag" xreflabel="nopublish_flag">
		<title><varname>nopublish_flag</varname> (str)</title>
		<para>
			By default, reINVITEs will trigger a PUBLISH. They are actually
			the only in-dialog request for which it makes sense.
			In some cases, it does not make sense to republish a dialog state.
			(e.g. when handling a B2BUA reINVITE).
			This setting defines the flag that needs to be set in the request
			route to prevent the generation of a PUBLISH request in case of a
			specific reINVITE.
		</para>
		<example>
			<title>Set <varname>nopublish_flag</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "nopublish_flag", "no_publish")
...
</programlisting>
		</example>
		</section>

		<section id="param_presence_server" xreflabel="presence_server">
		<title><varname>presence_server</varname> (string)</title>
		<para>
		The address of the presence server, where the PUBLISH messages
		should be sent (not compulsory).
		</para>
		<example>
			<title>Set <varname>presence_server</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "presence_server", "sip:ps@opensips.org:5060")
...
</programlisting>
		</example>
		</section>

	<section id="param_caller_spec_param" xreflabel="caller_spec_param">
		<title><varname>caller_spec_param</varname> (string)</title>
		<para>
		The name of the pseudovariable that will hold a custom caller URI.
		If this variable is not set, the information in From header is used.
		If you want to use another caller definition, you have to fill in this
		pseudovariable before calling <xref linkend="func_dialoginfo_set"/> 
		function. The format of the string
		resemples the format of To/From SIP headers:
		"display_name&lt;sip_uri&gt;"  or "sip_uri".
		</para>
		<example>
			<title>Set <varname>caller_spec_param</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "caller_spec_param", "$avp(10)")
...
		</programlisting>
		</example>
	</section>

	<section id="param_callee_spec_param" xreflabel="callee_spec_param">
		<title><varname>callee_spec_param</varname> (string)</title>
		<para>
		The name of the pseudovariable that will hold the callee URI.
		If this variable will not be set, the callee information used
		will be made of To display uri + RURI.
		the. The format of the string to set this pseudovariable to is
		the same as described in caller_spec_param section.
		</para>
		<example>
			<title>Set <varname>caller_spec_param</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "callee_spec_param", "$avp(11)")
...
		</programlisting>
		</example>
	</section>

	<section id="param_osips_ps" xreflabel="osips_ps">
		<title><varname>osips_ps</varname> (int)</title>
		<para>
			It is advisable to specify if you use a different presence server
			than OpenSIPS presence server, by setting this parameter to 0.
			By default, a trick (version in the Publish body is set '0000000') is
			used when working with Opensips Presence Server
			to make the processing faster and this might not be accepted by other
			presence servers.
		</para>
		<para>
			<emphasis>Default value is <quote>1</quote>.</emphasis>
		</para>
		<example>
			<title>Set <varname>osips_ps</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("pua_dialoginfo", "osips_ps", 0)
...
		</programlisting>
		</example>
	</section>


	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_dialoginfo_set" xreflabel="dialoginfo_set()">
		<title>
		<function moreinfo="none">dialoginfo_set([side])</function>
		</title>
		<para>
		This function must be called for INVITE messages that initialize a
		dialog for which dialoginfo information must be published.
		</para>
		<para>
		Meaning of the parameters:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>side</emphasis> (string, optional) - can be "A" or/and "B"
			for caller or callee PUBLISH only - if missing, both sides will
			be published.</para>
		</listitem>
		</itemizedlist>
		<example>
		<title><function>dialoginfo_set</function> usage</title>
		<programlisting format="linespecific">
...
	if(is_method("INVITE"))
		if($ru =~ "opensips.org")
			dialoginfo_set();
...
		</programlisting>
		</example>
	</section>

	<section id="func_dialoginfo_set_branch_callee" xreflabel="dialoginfo_set_branch_callee()">
		<title>
		<function moreinfo="none">dialoginfo_set_branch_callee(callee)</function>
		</title>
		<para>
		This function is to be used only from a branch route for setting 
		a per-branch callee/peer specification. This peer value will be used
		onyl for the dialoginfo record created for that particular branch.
		</para>
		<para>
		This function makes sense only in call forking (serial / parallel)
		scenarios, where a caller may be in relation with multiple different
		callees.
		</para>
		<para>
		Meaning of the parameters:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>callee</emphasis> (string) - a SIP nams addr description of
			the callee (the name_addr format is '[display] &lt;uri&gt;' or 
			'uri', as in the To or From headers)
			</para>
		</listitem>
		</itemizedlist>
		<example>
		<title><function>dialoginfo_set_branch_callee</function> usage</title>
		<programlisting format="linespecific">
...
branch_route[out]
{
....
	#align the published info with the RURI of the branch
	dialoginfo_set_branch_callee("sip:$rU@opensips.org");
...
}
		</programlisting>
		</example>
	</section>

	<section id="func_dialoginfo_mute_branch" xreflabel="dialoginfo_mute_branch()">
		<title>
		<function moreinfo="none">dialoginfo_mute_branch([side])</function>
		</title>
		<para>
		This function must be called for INVITE messages, in the branch route
		only, in order to mute the publishing of the dialoginfo information
		for caller/callee/both parties involved in that branch.
		</para>
		<para>
		Meaning of the parameters:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>side</emphasis> (string, optional) - can be
			"A" or/and "B" for caller or callee muting only - if missing,
			both sides will be muted.</para>
		</listitem>
		</itemizedlist>
		<example>
		<title><function>dialoginfo_mute_branch</function> usage</title>
		<programlisting format="linespecific">
...
	branch_route[out] {
		# mute publishing for callee side if not a local domain
		if (!is_domain_local("$rd"))
			dialoginfo_mute_branch("B");
	}
...
		</programlisting>
		</example>
	</section>

	</section>

</chapter>

