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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision$</revnumber>
		<date>$Date$</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para> The modules handles PUBLISH and SUBSCRIBE messages and generates
	NOTIFY messages in a general, event independent way. It allows registering 
	events to it from other &ser modules. Events that can currently be added to
	it are: presence, presence.winfo, dialog;sla from presence_xml
	module and message-summary from presence_mwi module.
	</para>
	<para>
	The modules uses database storage. 
	It has later been improved with memory caching operations to improve
	performance. The Subscribe dialog information are stored in memory and 
	are periodically updated in database, while for Publish only the presence
	or absence of stored info for a certain resource is maintained in memory
	to avoid unnecessary, costly db operations. 
	It is possible to configure a fallback to database mode(by setting module
	parameter "fallback2db"). In this mode, in case a searched record is not 
	found in cache, the search is continued	in database. This is useful for
	an architecture in which processing and memory load might be divided on 
	more machines using the same database.
	</para>
	<para>The module can also work only with the functionality of a library,
	with no message processing and generation, but used only for the exported
	functions.
	This mode of operation is enabled if the db_url parameter is not set to any value.
	</para>
	<para>
	The server follows the specifications in: RFC3265, RFC3856, RFC3857, 
	RFC3858.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>a database module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>sl</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
			None.
		</para>
	</section>
	</section>
	
	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>db_url</varname>(str)</title>
		<para>
		The database url.
		</para>
		<para>If set, the module is a fully operational
		presence server. Otherwise, it is used as a 'library', for 
		its exported functions.
		</para>
		<para>
		<emphasis>	Default value is <quote>NULL</quote>.	
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "db_url", 
	"mysql://openser:openserrw@192.168.2.132/openser")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>presentity_table</varname>(str)</title>
		<para>
		The name of the db table where Publish information are stored.
		</para>
		<para>
		<emphasis>	Default value is <quote>presentity</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>presentity_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "presentity_table", "presentity");
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>active_watchers_table</varname>(str)</title>
		<para>
		The name of the db table where active subscription information are 
		stored. 
		</para>
		<para>
		<emphasis>	Default value is <quote>active_watchers</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>active_watchers_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "active_watchers_table", "active_watchers")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>watchers_table</varname>(str)</title>
		<para>
		The name of the db table where subscription states are stored.
		</para>
		<para>
		<emphasis>	Default value is <quote>watchers</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>watchers_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "watchers_table", "watchers")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>clean_period</varname> (int)</title>
		<para>
		The period at which to verify if there are expired messages stored in
		database.
		</para>
		<para>
		<emphasis>Default value is <quote>100</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "clean_period", 100)
...
</programlisting>
		</example>
	</section>

<section>
		<title><varname>to_tag_pref</varname> (str)</title>
		<para>
		The prefix used when generating to_tag when sending replies for
		SUBSCRIBE requests.
		</para>
		<para>
		<emphasis>Default value is <quote>10</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>to_tag_pref</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "to_tag_pref", 'a')
...
	</programlisting>
		</example>
	</section>

	<section>
		<title><varname>lock_set_size</varname> (int)</title>
		<para>
		The size of the lock used for synchronizing updating information 
		from database.
		</para>
		<para>
		<emphasis>Default value is <quote>8</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>lock_set_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "lock_set_size", 8)
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>expires_offset</varname> (int)</title>
		<para>
		The value that should be subtracted from the expires value when
		sending a 200OK for a publish. It is used for forcing the client
		cu send an update before the old publish expires.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>expires_offset</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "expires_offset", 10)
...
</programlisting>
		</example>

</section>
       <section>
               <title><varname>max_expires</varname> (int)</title>
               <para>
               The the maximum admissible expires value for PUBLISH/SUBSCRIBE
               message.
               </para>
               <para>
               <emphasis>Default value is <quote>3600</quote>.
               </emphasis>
               </para>
               <example>
               <title>Set <varname>max_expires</varname> parameter</title>
               <programlisting format="linespecific">
...
modparam("presence", "max_expires", 3600)
...
</programlisting>
               </example>
       </section>

<section>
		<title><varname>server_address</varname> (str)</title>
		<para>
		The presence server address which will become the value of Contact header filed 
		for 200OK replies to Subscribe and Publish and in Notify messages.
		</para>
		<example>
		<title>Set <varname>server_address</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...
</programlisting>
		</example>
	</section>
<section>
		<title><varname>fallback2db</varname> (int)</title>
		<para>
		Setting this parameter enables a fallback to db mode of operation.
		In this mode, in case a searched record is not found in cache, 
		the search is continued	in database. Useful for an architecture in
		which processing and memory load might be divided on more machines
		using the same database.
		</para>
		<example>
		<title>Set <varname>fallback2db</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence", "fallback2db", 1)
...
</programlisting>
		</example>
	</section>


</section>

<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">handle_publish(char* sender_uri)</function>
		</title>
		<para>
		The function handles PUBLISH requests. It stores and updates 
		published information in database and calls functions to send 
		NOTIFY messages when changes in the published information occur.
		It takes one argument -> sender_uri. The parameter was added 
		for enabling BLA implementation. If present, Notification of
		a change in published state is not sent to the respective uri
		even though a subscription exists.
		It should be taken from the Sender header. It was left at the
		decision of the administrator whether or not to transmit the 
		content of this header as parameter for handle_publish, to 
		prevent security problems.  
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>handle_publish</function> usage</title>
		<programlisting format="linespecific">
...
	if(is_method("PUBLISH"))
	{
		if($hdr(Sender)!= NULL)
			handle_publish("$hdr(Sender)");
		else
			handle_publish();
		t_release();
	} 
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">handle_subscribe()</function>
		</title>
		<para>
		The function which handles SUBSCRIBE requests. It stores or 
		updates information in database and calls functions to send Notify 
		messages when a Subscribe which initiate a dialog is received
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>handle_subscribe</function> usage</title>
		<programlisting format="linespecific">
...
if(method=="SUBSCRIBE")
    handle_subscribe();
...
</programlisting>
		</example>
	</section>
</section>

<section>
	<title>Installation</title>
	<para>
	The module requires 3 table in OpenSER database: presentity,
	active_watchers and watchers tables. The SQL 
	syntax to create them can be found in presence_xml-create.sql     
	script in the database directories in the openser/scripts folder.
	You can also find the complete database documentation on the
	project webpage, &openserdbdocslink;.
	</para>
</section>

</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("presence.sgml" "Book" "chapter")
End:
-->