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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para> 
	The module does specific handling for notify-subscribe events using xml bodies.
	It is used with the general event handling module, presence. It constructs and adds
	3 events to it: presence, presence.winfo, dialog;sla. 
	</para>
	<para>
	This module takes the xcap permission rule documents from xcap_table.

	The presence permission rules are interpreted according to the specifications
	in RFC 4745 and RFC 5025.
	</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 module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>presence</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>signaling</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xcap</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xcap_client</emphasis>.
			</para>
			<para>
			Only compulsory if not using an integrated xcap server 
			(if 'integrated_xcap_server' parameter is not set).
			</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-dev</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_force_active" xreflabel="force_active">
		<title><varname>force_active</varname> (int)</title>
		<para>
		This parameter is used for permissions when handling Subscribe messages.
		If set to 1, subscription state is considered active and the presentity
		is not queried for permissions(should be set to 1 if not using an xcap 
		server). 
		Otherwise,the xcap server is queried and the subscription states is
		according to user defined permission rules. If no rules are defined for
		a certain watcher, the subscriptions remains in pending state and the
		Notify sent will have no body.
		</para>
		<para>
		Note: When switching from one value to another, the watchers table must
		be emptied.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>force_active</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "force_active", 1)
...
</programlisting>
		</example>
	</section>
	<section id="param_pidf_manipulation" xreflabel="pidf_manipulation">
		<title><varname>pidf_manipulation</varname> (int)</title>
		<para>
		Setting this parameter to 1 enables the features described in RFC 4827.
		It gives the possibility to have a permanent state notified to the users
		even in the case in which the phone is not online. The presence document
		is taken from the xcap server and aggregated together with the other
		presence information, if any exist, for each Notify that is sent to the
		watchers. It is also possible to have information notified even if not 
		issuing any Publish (useful for services such as email, SMS, MMS).
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pidf_manipulation</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "pidf_manipulation", 1)
...
</programlisting>
		</example>
	</section>
	<section id="param_xcap_server" xreflabel="xcap_server">
		<title><varname>xcap_server</varname> (str)</title>
		<para>
		The address of the xcap servers used for storage.
		This parameter is compulsory if the integrated_xcap_server parameter
		is not set. It can be set more that once, to construct an address
		list of trusted XCAP servers.</para>
		<example>
		<title>Set <varname>xcap_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "xcap_server", "xcap_server.example.org")
modparam("presence_xml", "xcap_server", "xcap_server.ag.org")
...
</programlisting>
		</example>
	</section>
	<section id="param_pres_rules_auid" xreflabel="pres_rules_auid">
		<title><varname>pres_rules_auid</varname> (str)</title>
		<para>
		This parameter should be configured if you are using the non integrated xcap
		mode and you need to use another pres-rules auid than the default 'pres-rules'.
		</para>
		<example>
		<title>Set <varname>pres_rules_auid</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "pres_rules_auid", "org.openmobilealliance.pres-rules")
...
</programlisting>
		</example>
	</section>

	<section id="param_pres_rules_filename" xreflabel="pres_rules_filename">
		<title><varname>pres_rules_filename</varname> (str)</title>
		<para>
		This parameter should be configured if you are using the non integrated xcap
		mode and you need to configure another filename than the default 'index'.
		</para>
		<example>
		<title>Set <varname>pres_rules_filename</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "pres_rules_filename", "pres-rules")
...
</programlisting>
		</example>
	</section>

	<section id="param_generate_offline_body" xreflabel="generate_offline_body">
		<title><varname>generate_offline_body</varname> (str)</title>
		<para>
                This parameter should be set to 0 if you want to prevent OpenSIPS from automatically
                generating a PIDF body when a publication expires or is explicitly terminated
                (a PUBLISH request is received with Expires: 0).
		</para>
		<example>
		<title>Set <varname>generate_offline_body</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "generate_offline_body", 0)
...
</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>

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

</chapter>

