<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

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

<chapter>

	<title>&adminguide;</title>

	<section>
	<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:
		<itemizedlist>
			<listitem>
				<para>presence - SIMPLE status presence: RFC 3856</para>
			</listitem>
			<listitem>
				<para>presence.winfo - SIMPLE watcher info: RFC 3857</para>
			</listitem>
			<listitem>
				<para>dialog;sla (or dialog;ma) - Bridged Line Appearances
				(BLA) (or Multiple Line Appearances (MLA)):
				draft-anil-sipping-bla</para>
			</listitem>
		</itemizedlist>
	</para>
	<para>
	You can control which events are enabled via module parameters.
	</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>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; 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>sl</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xcap_client</emphasis>.
			</para>
			<para>
			Needed only when not using the integrated xcap server
			(if 'integrated_xcap_server' parameter is set to 0).
			</para>
			</listitem>

			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="presence_xml.p.db_url">
		<title><varname>db_url</varname>(str)</title>
		<para>
		The 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("presence_xml", "db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>
	<section id="presence_xml.p.xcap_table">
		<title><varname>xcap_table</varname>(str)</title>
		<para>
		The name of the database table where XCAP documents are stored.
		</para>
		<para>
		<emphasis>Default value is <quote>xcap</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xcap_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "xcap_table", "xcaps")
...
</programlisting>
		</example>
	</section>

	<section id="presence_xml.p.disable_presence">
		<title><varname>disable_presence</varname>(int)</title>
		<para>
		Set this parameter to disable the handling of the "presence" event.
		</para>
		<para>
		<emphasis>Default value: <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disable_presence</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "disable_presence", 1)
...
</programlisting>
		</example>
	</section>
	<section id="presence_xml.p.disable_winfo">
		<title><varname>disable_winfo</varname>(int)</title>
		<para>
		Set this parameter to disable the handling of the "presence.winfo" event.
		</para>
		<para>
		<emphasis>Default value: <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disable_winfo</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "disable_winfo", 1)
...
</programlisting>
		</example>
	</section>
	<section id="presence_xml.p.disable_bla">
		<title><varname>disable_bla</varname>(int)</title>
		<para>
		Set this parameter to disable the handling of the "dialog;sla" event.
		</para>
		<para>
		<emphasis>Default value: <quote>1</quote> (0 - enabled, 1 - disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disable_bla</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "disable_bla", 1)
...
</programlisting>
		</example>
	</section>

	<section id="presence_xml.p.disable_xcapdiff">
		<title><varname>disable_xcapdiff</varname>(int)</title>
		<para>
		Set this parameter to disable the handling of the "xcap-diff" event.
		</para>
		<para>
		<emphasis>Default value: <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disable_xcapdiff</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "disable_xcapdiff", 1)
...
</programlisting>
		</example>
	</section>

	<section id="presence_xml.p.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="presence_xml.p.integrated_xcap_server">
		<title><varname>integrated_xcap_server</varname> (int)</title>
		<para>
		This parameter is a flag for the type of XCAP servers
		used. If the XCAP server is integrated with &kamailio; presence_xml
		module and access the same database tables directly, like the embedded
		XCAP server implemented in xcap_server module, the parameter has to be
		set to 1. Apart from updating in xcap table,
		if the integrated server is not running on the same &kamailio; instance,
		it must send an RPC command presence.refreshWatchers
		[pres_uri] [event] when a user modifies a rules document, to
		instruct the presence_xml module to update states from the database
		and, if needed, send NOTIFY updates.
		</para>
		<para>
		Otherwise (if set to 0) it uses xcap_client module to fetch documents
		from the XCAP servers with HTTP requests.</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>integrated_xcap_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "integrated_xcap_server", 1)
...
</programlisting>
		</example>
	</section>
	<section id="presence_xml.p.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 than 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="presence_xml.p.passive_mode">
		<title><varname>passive_mode</varname>(int)</title>
		<para>
		If set to 1, module acts in passive mode - no bind to presence module,
		no connection to database. Useful when needing only to use $xml(...)
		pseudo-variable.
		</para>
		<para>
			<emphasis>Default value: <quote>0</quote> (0 - active mode,
				1 - passive mode).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>passive_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "passive_mode", 1)
...
</programlisting>
		</example>
	</section>

	<section id="presence_xml.p.xcapauth_userdel_reason">
		<title><varname>xcapauth_userdel_reason</varname>(str)</title>
		<para>
		This parameter represents the reason that will be included in the
		Subscription-State header of the Notify when a rule is no longer found
		in the XCAP pres-auth document for a user that was previously allowed.
		The Subscription state in this case switches to "terminated". Because
		it is not clear which reason is most appropriate in this case from
		the ones defined by the RFC 3265, this parameter offers the possibility
		for the admin to decide which one he wishes to use.
		</para>
		<para>
			<emphasis>Default value: <quote>probation</quote> </emphasis> . Since
			probation also accepts a retry-after parameter to specify after at
			least how may seconds the client should reattempt to resubscribe,
			you can include this in the parameter also.
		</para>
		<example>
		<title>Set <varname>xcapauth_userdel_reason</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("presence_xml", "xcapauth_userdel_reason", "probation;retry-after=30")
modparam("presence_xml", "xcapauth_userdel_reason", "rejected")
...
</programlisting>
		</example>
	</section>
    <section id="presence_xml.p.force_dummy_presence">
        <title><varname>force_dummy_presence</varname>(int)</title>
        <para>
        Set this parameter to enable simple body notify with status 'open' when presentity info is not available.
        </para>
        <para>
        <emphasis>Default value: <quote>0</quote>.
        </emphasis>
        </para>
        <example>
        <title>Set <varname>force_dummy_presence</varname> parameter</title>
        <programlisting format="linespecific">
...
modparam("presence_xml", "force_dummy_presence", 1)
...
</programlisting>
        </example>
    </section>
    <section id="presence_xml.p.force_presence_single_body">
        <title><varname>force_presence_single_body</varname>(int)</title>
        <para>
        Set this parameter to enable single body notify.
        One presentity can have multiple dialogs and will by default notify all the dialogs and this can be a problem
        when dealing with large ring-groups or attendants, use this parameter to only send one body.
        Look at <varname>presence_single_body_priorities</varname> and <varname>presence_single_body_lookup_element</varname> to customize the behaviour.
        </para>
        <para>
        <emphasis>Default value: <quote>0</quote>.
        </emphasis>
        </para>
        <example>
        <title>Set <varname>force_presence_single_body</varname> parameter</title>
        <programlisting format="linespecific">
...
modparam("presence_xml", "force_presence_single_body", 1)
...
</programlisting>
        </example>
    </section>
    <section id="presence_xml.p.presence_single_body_priorities">
        <title><varname>presence_single_body_priorities</varname>(str)</title>
        <para>
        Change this parameter to set the priorities when choosing the dialog that will be the final.
        </para>
        <para>
        Importance is left to right.
        </para>
        <para>
        <emphasis>Default value: <quote>Available|Ringing|On the Phone</quote>.
        </emphasis>
        </para>
        <example>
        <title>Set <varname>presence_single_body_priorities</varname> parameter</title>
        <programlisting format="linespecific">
...
modparam("presence_xml", "presence_single_body_priorities", "Offline|Online|Busy|Really Busy")
...
</programlisting>
        </example>
    </section>
    <section id="presence_xml.p.presence_single_body_lookup_element">
        <title><varname>presence_single_body_lookup_element</varname>(str)</title>
        <para>
        Set the name of the element that should be used to get the priority.
        If the value obtained is not in the list of <varname>presence_single_body_priorities</varname> the priority is 0.
        </para>
        <para>
        <emphasis>Default value: <quote>note</quote>.
        </emphasis>
        </para>
        <example>
        <title>Set <varname>presence_single_body_lookup_element</varname> parameter</title>
        <programlisting format="linespecific">
...
modparam("presence_xml", "presence_single_body_lookup_element", "status")
...
</programlisting>
        </example>
    </section>

<section id="presence_xml.p.default_expires">
        <title><varname>default_expires</varname> (int)</title>
        <para>
        The default expires value used when missing from SUBSCRIBE
        message (in seconds).
        </para>
        <para>
        <emphasis>Default value is <quote>3600</quote>.
        </emphasis>
        </para>
        <example>
        <title>Set <varname>default_expires</varname> parameter</title>
        <programlisting format="linespecific">
...
modparam("presence_xml", "default_expires", 3600)
...
</programlisting>
    </example>
</section>

	</section>


<section>
	<title>Functions</title>
	<section id="presence_xml.f.pres_check_basic">
		<title>
		<function moreinfo="none">pres_check_basic(presentity_uri, status)</function>
		</title>
		<para>
		Checks the /presence/tuple/status/basic nodes in the presentity for
		<emphasis>presentity_uri</emphasis> against the value in status.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<para>
		<emphasis>Return code:</emphasis>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis> 1 - if a match is found</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis> -1 - if a match is not found</emphasis>.
			</para>
			</listitem>
		</itemizedlist>
		</para>
		<example>
		<title><function>pres_check_basic</function> usage</title>
		<programlisting format="linespecific">
...
    if (pres_check_basic("$ru", "open")) {
        ...
    } else {
        if (is_method("MESSAGE"))
            m_store();
    else
        send_reply("404", "Not Found");
    }
...
</programlisting>
		</example>
	</section>
	<section id="presence_xml.f.pres_check_activities">
		<title>
		<function moreinfo="none">pres_check_activities(presentity_uri, activity)</function>
		</title>
		<para>
		Checks whether a /presence/person/activities/<emphasis>activity</emphasis>
		node exists in the presentity for <emphasis>presentity_uri</emphasis>.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<para>
		<emphasis>Return code:</emphasis>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis> 1 - if a match is found</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis> -1 - if a match is not found</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis> -2 - if /presence/person or /presence/person/activity do not exist</emphasis>.
			</para>
			</listitem>

		</itemizedlist>
		</para>
		<example>
		<title><function>pres_check_activities</function> usage</title>
		<programlisting format="linespecific">
...
    if (pres_check_basic("$ru", "open")) {
	pres_check_activities("$ru", "unknown");
	if ($retcode || $retcode == -2 || !is_method("INVITE"))
            t_relay();
	else
            send_reply("486", "Busy Here");
    } else {
        ...
    }
...
</programlisting>
		</example>
	</section>

</section>

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

</chapter>

