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

<chapter>
	

	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	  <title>Overview</title>
	    <para> 
	      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.
	    </para>
	    <para>
 	      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 
	      &osips; configuration file before calling handle_publish() 
	      and handle_subscribe() functions.
	    </para>
	    <para>
	      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 
	      &osips; instances.
	    </para>
	    <para>
			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.
	    </para>
	    <para>
			To get better understanding how all the module works together please take a
			look at the follwing figure:
        <programlisting format="linespecific">
<![CDATA[

    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--------------|
     |             |            |               |
]]>
</programlisting>

			<itemizedlist>
				<listitem><para>
					The watcher subscribes the "Event: dialog" of Bob.
				</para></listitem>
				<listitem><para>
					Alice calls Bob.
				</para></listitem>
				<listitem><para>
					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)
				</para></listitem>
				<listitem><para>
					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.
				</para></listitem>
			</itemizedlist>

			The presence server can also be separated from the main proxy by using a separate 
			&osips; 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).

        <programlisting format="linespecific">
<![CDATA[

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


]]>
</programlisting>

	    </para>
	    <para>
			Known issues:
			<itemizedlist>
				<listitem><para>
					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.
				</para></listitem>
			</itemizedlist>



	    </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>presence</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	  </section>

	  <section>
		<title>External Libraries or Applications</title>
		<para>
		None.
		</para>
	  </section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>

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

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<para>
			None to be used in configuration file.
		</para>
	</section>

</chapter>
