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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module offer the internal support for OpenSIPS to act as a 
		Presence User Agent client, by sending Subscribe and Publish messages.
	</para>
	<para>
	Note that the module does NOT provide any functionality to be used
	directly from the script, but it is providing this PUA client support
	(via an internal API) for other event-specific modules to do PUA 
	client operations.
	</para>
	<para>
		 Some of modules build on top of the PUA module are pua_mi, pua_usrloc,
		 pua_dialoginfo, pua_bla and pua_xmpp.
		 The pua_mi offer the possibility to publish any kind of information
		 or subscribing to a resource through fifo. The pua_usrloc module calls
		 a function exported by pua modules to publish elementary presence
		 information, such as basic status "open" or "closed", for clients that
		 do not implement client-to-server presence.
		 The pua_dialoginfo provideds BLF support, by publishing the status of
		 the participants into a call (like ringing, established, terminated).
		 Through pua_bla , BRIDGED LINE APPEARANCE features are added to 
		 OpenSIPs.
		 The pua_xmpp module represents a gateway between SIP and XMPP, so 
		 that jabber and SIP clients can exchange presence information.
	</para>
	<para>
		The module use cache to store presentity list and writes to database
		on timer to be able to recover upon restart.
	</para>
	<para>
		Notice: This module must not be used in no fork mode (the locking 
		mechanism used may cause deadlock in no fork mode).
	</para>
	</section>

	<section id="pua_clustering">
	<title>PUA clustering</title>
	<para>
	Starting 3.2, the module was extended with clustering support also. This 
	means multiple OpenSIPS instance, configured with PUA module, may work 
	together. For example, the publishing for a certain presentity may be done 
	via different node (PUA OpenSIPS instance) in the cluster.
	</para>
	<para>
	The clustering support is a mixture of DB sharing and OpenSIPS clustering.
	The OpenSIPS clustering layer is used for broadcasting notifications with 
	the cluster when a presentity is modified by one of the nodes (so that, 
	the other nodes in cluster may refresh the presentity via DB.
	</para>
	<para>
	The shared DB is used by sharing between the nodes the actual presentity
	data. A node caches into memory only the presentities created by the node
	or the presentitites the node worked with. A presentity record may be
	loaded into memory (from DB) if the node needs to perform an operation 
	with that presentity.
	</para>
	<para>
	IMPORTANT: because the actual presentity data is shared between the nodes
	via DB (the clustering layer is used for notifications only), it is
	important to set a very low update interval for the DB (for data being
	flushed from memoryc cache into DB), to get the DB content updated as 
	realtime as possible. See the the <xref linkend="param_update_period"/>,
	module parameter, with recomanded values like 2-5 seconds.
	</para>
	<para>
	On the OpenSIPS clustering layer, the PUA module use the sharing-tags
	mechanism in order to control (between all the nodes in the cluster) which
	node is responsible for performing the expiring operation on the
	presentity (like sending the PUBLISH with expires 0).
	</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>a database modules</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>clusterer</emphasis>, if the cluster_id 
				module parameter is set and clustering support activated.
			</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_hash_size" xreflabel="hash_size">
		<title><varname>hash_size</varname> (int)</title>
		<para>
		The size of the hash table used for storing Subscribe and 
		Publish information. 
        This parameter will be used as the power of 2 when computing table size.
        </para>
		<para>
		<emphasis>Default value is <quote>9</quote>.	
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "hash_size", 11)
...
</programlisting>
		</example>
	</section>
	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (str)</title>
		<para>
		Database url.
		</para>
		<para>
		<emphasis>Default value is <quote>>&defaultdb;</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "db_url" "&exampledb;")
...
</programlisting>
		</example>
	</section>
	<section id="param_db_table" xreflabel="db_table">
		<title><varname>db_table</varname> (str)</title>
		<para>
		The name of the database table.
		</para>
		<para>
		<emphasis>Default value is <quote>pua</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "db_table", "pua")
...
</programlisting>
		</example>
	</section>
	<section id="param_min_expires" xreflabel="min_expires">
		<title><varname>min_expires</varname> (int)</title>
		<para>
		The inferior expires limit for both Publish and Subscribe.
		</para>
		<para>
		<emphasis>Default value is <quote>300</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>min_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "min_expires", 0)
...
</programlisting>
		</example>
	</section>
	<section id="param_default_expires" xreflabel="default_expires">
		<title><varname>default_expires</varname> (int)</title>
		<para>
		The default expires value used in case this information is not provisioned.
		</para>
		<para>
		<emphasis>Default value is <quote>3600</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "default_expires", 3600)
...
</programlisting>
		</example>
	</section>
	<section id="param_update_period" xreflabel="update_period">
		<title><varname>update_period</varname> (int)</title>
		<para>
		The interval at which the information in database and hash table
		should be updated. In the case of the hash table updating is 
		deleting expired messages.
		</para>
		<para>
		<emphasis>Default value is <quote>30</quote>.
		</emphasis>
		</para>
		<para>
		IMPORTANT - if you use clustering support for this module, set a low
		value here, like 2-5, see the clustering chapter above.
		</para>
		<example>
		<title>Set <varname>update_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "update_period", 100)
...
</programlisting>
		</example>
	</section>

	<section id="param_cluster_id" xreflabel="cluster_id">
		<title><varname>cluster_id</varname> (int)</title>
		<para>
		The cluster ID where the PUA data should be replicated/shared.
		This parameter is to be used only if clustering mode is needed.
		In order to understand the concept of a cluster ID, please see the 
		<emphasis>clusterer</emphasis> module.
		</para>
		<para>
		For more on PUA clustering see the 
		<xref linkend="pua_clustering"/> chapter.
		</para>
		<para>
		<emphasis>Default value is <quote>None</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cluster_id</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "cluster_id", 10)
...
</programlisting>
		</example>
	</section>

	<section id="param_cluster_sharing_tag" xreflabel="cluster_sharing_tag">
		<title><varname>cluster_sharing_tag</varname> (int)</title>
		<para>
		The clustering share-tag to be used by the PUA module when creating
		any new presentity record. The tag will by used to decide which
		OpenSIPS instance (owning the tag as active) will be responsible
		for expiring this presentity.
		This parameter is to be used only if clustering mode is needed.
		In order to understand the concept of sharing TAG, please see the 
		<emphasis>clusterer</emphasis> module.
		</para>
		<para>
		For more on PUA clustering see the 
		<xref linkend="pua_clustering"/> chapter.
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cluster_sharing_tag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua", "cluster_sharing_tag", "vip")
...
</programlisting>
		</example>
	</section>

	</section>

<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
		
	<section id="func_pua_update_contact" xreflabel="pua_update_contact()">
		<title>
		<function moreinfo="none">pua_update_contact()</function>
		</title>
		<para>
		The remote target can be updated by the Contact of a subsequent in
		dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
		this means that the remote target for the following Subscribe messages
		can be updated at any time by the contact of a Notify message. 
		If this function is called on request route on receiving a Notify
		message, it will try to update the stored remote target.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<para>
		<emphasis>Return code:</emphasis>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis> 1 - if success</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis> -1 - if error</emphasis>.
			</para>
			</listitem>
		</itemizedlist>
		</para>
	
		<example>
		<title><function>pua_update_contact</function> usage</title>
		<programlisting format="linespecific">
...
if($rm=="NOTIFY")
    pua_update_contact();
...
</programlisting>
		</example>
	</section>
</section>


<section>
	<title>Installation</title>
	<para>
	The module requires 1 table in OpenSIPS database: pua. The SQL 
	syntax to create it can be found in presence_xml-create.sql     
	script in the database directories in the opensips/scripts folder.
	You can also find the complete database documentation on the
	project webpage, &osipsdbdocslink;.
	</para>
</section>


</chapter>

