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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>The modules is a Resource List Server implementation following the
	specification in RFC 4662 and RFC 4826. 
	</para>
	<para>
	The server is independent from local presence servers, retrieving presence
	information with Subscribe-Notify messages.
	</para>
	<para>
	The module uses the presence module as a library, as it requires a resembling
	mechanism for handling Subscribe. Therefore, in case the local presence server
	is not collocated on the same machine with the RL server, the presence module
	should be loaded in a library mode only (see doc for presence module).
	</para>

	<para>
	It handles subscription to lists in an event independent way.The default event
	is presence, but if some other events are to be handled by the server, they
	should be added using the module parameter "rls_events".
	</para>
	<para>
	It works with XCAP server for storage. There is also the possibility to
	configure it to work in an integrated_xcap server mode, when it only
	queries database for the resource lists documents. This is useful in a
	small architecture when all the clients use an integrated server and there
	are no references to exterior documents in their lists.
	</para>
	<para>
	The same as presence module, it has a caching mode with periodical update
	in database for subscribe information. The information retrieved with Notify
	messages is stored in database only. 
	</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>signaling</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>presence- in a library mode</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>pua</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xcap</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml-dev</emphasis>.
			</para>
			</listitem>
		</itemizedlist>

		</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_rlsubs_table" xreflabel="rlsubs_table">
		<title><varname>rlsubs_table</varname>(str)</title>
		<para>
		The name of the db table where resource lists subscription 
		information is stored. 
		</para>
		<para>
		<emphasis>	Default value is <quote>rls_watchers</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlsubs_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlsubs_table", "rls_subscriptions")
...
</programlisting>
		</example>
	</section>

	<section id="param_rlpres_table" xreflabel="rlpres_table">
		<title><varname>rlpres_table</varname>(str)</title>
		<para>
		The name of the db table where notified event specific
		information is stored. 
		</para>
		<para>
		<emphasis>	Default value is <quote>rls_presentity</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rlpres_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rlpres_table", "rls_notify")
...
</programlisting>
		</example>
	</section>

	<section id="param_clean_period" xreflabel="clean_period">
		<title><varname>clean_period</varname> (int)</title>
		<para>
		The period at which to check for expired information.
		</para>
		<para>
		<emphasis>Default value is <quote>100</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "clean_period", 100)
...
</programlisting>
		</example>
	</section>

	<section id="param_waitn_time" xreflabel="waitn_time">
		<title><varname>waitn_time</varname> (int)</title>
		<para>
	 The timer period at which the server should attempt to send
	 Notifies with the updated presence state of the subscribed list
	 or watcher information.
		</para>
		<para>
		<emphasis>Default value is <quote>50</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>waitn_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "waitn_time", 10)
...
</programlisting>
		</example>
	</section>

	<section id="param_max_expires" xreflabel="max_expires">
		<title><varname>max_expires</varname> (int)</title>
		<para>
		The maximum accepted expires for a subscription to a list. 
		</para>
		<para>
		<emphasis>Default value is <quote>7200</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "max_expires", 10800)
...
		</programlisting>
		</example>
	</section>
 	
	<section id="param_hash_size" xreflabel="hash_size">
		<title><varname>hash_size</varname> (int)</title>
		<para>
        The dimension of the hash table used to store subscription to a list.
        This parameter will be used as the power of 2 when computing table size.
		</para>
		<para>
		<emphasis>Default value is <quote>9 (512)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "hash_size", 11)
...
		</programlisting>
		</example>
	</section>

	<section id="param_xcap_root" xreflabel="xcap_root">
		<title><varname>xcap_root</varname> (str)</title>
		<para>
		The address of the xcap server.
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")
...
		</programlisting>
		</example>
	</section>

	<section id="param_to_presence_code" xreflabel="to_presence_code">
		<title><varname>to_presence_code</varname> (int)</title>
		<para>
		The code to be returned by rls_handle_subscribe function 
		if the processed Subscribe is not a resource list Subscribe.
		This code can be used in an architecture with presence and rls
		servers collocated on the same machine, to call handle_subscribe
		on the message causing this code.
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>to_presence_code</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "to_presence_code", 10)
...
		</programlisting>
		</example>
	</section>

	<section id="param_rls_event" xreflabel="rls_event">
		<title><varname>rls_event</varname> (str)</title>
		<para>
		The default event that RLS handles is presence. If some other
		events should also be handled by RLS they should be added using
		this parameter. It can be set more than once.
		</para>
		<para>
		<emphasis>Default value is <quote>"presence"</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rls_event</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "rls_event", "dialog;sla")
...
		</programlisting>
		</example>
	</section>

	<section id="param_presence_server" xreflabel="presence_server">
		<title><varname>presence_server</varname> (str)</title>
		<para>
		The address of the presence server. It will be used as outbound proxy for
		Subscribe requests sent by the RLS server to bouncing on and off the
		proxy and having to include special processing for this messages
		in the proxy's configuration file.
		</para>
		<example>
		<title>Set <varname>presence_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "presence_server", "sip:pres@opensips.org:5060")
...
		</programlisting>
		</example>
	</section>

	<section id="param_contact_user" xreflabel="contact_user">
		<title><varname>contact_user</varname> (str)</title>
		<para>
		This is the username that will be used in the Contact header for the 200 OK
		replies to SUBSCRIBE and in the following in-dialog NOTIFY requests, as well
		as for the SUBSCRIBE requests that are generated by the RLS server.
		The IP address, port and transport for the Contact will be automatically
		determined based on the interface where the SUBSCRIBE was received or sent
		from.
		</para>
		<para>
		If set to an empty string, no username will be added to the contact and
		the contact will be built just out of the IP, port and transport.
		</para>
		<para>
		<emphasis>Default value is <quote>rls</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>contact_user</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rls", "contact_user", "rls")
...
		</programlisting>
		</example>
	</section>

</section>

<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_rls_handle_subscribe" xreflabel="rls_handle_subscribe()">
		<title>
		<function moreinfo="none">rls_handle_subscribe()</function>
		</title>
		<para>
		This function detects if a Subscribe message should be
		handled by RLS. If not it replies with the configured 
		to_presence_code. If it is, it extracts the dialog info and sends
		aggregate Notify requests with information for the list.	
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>rls_handle_subscribe</function> usage</title>
		<programlisting format="linespecific">
...
For presence and rls on the same machine:
	modparam(rls, "to_presence_code", 10)

	if(is_method("SUBSCRIBE"))
	{	
		$var(ret_code)= rls_handle_subscribe();

		if($var(ret_code)== 10)
				handle_subscribe();

		t_release();
	}

For rls only:
	if(is_method("SUBSCRIBE"))
	{
		rls_handle_subscribe();
		t_release();
	}

...
</programlisting>
		</example>
	</section>

	<section id="func_rls_handle_notify" xreflabel="rls_handle_notify()">
		<title>
		<function moreinfo="none">rls_handle_notify()</function>
		</title>
		<para>
			This function has to be called for Notify messages sent by presence
			servers in reply to the Subscribe messages sent by RLS. 
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<para>
			It can return 3 codes:
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>1</emphasis> - the Notify was inside a dialog that was
				recognized by the RLS server and was processed successfully.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>2</emphasis> - the Notify did not belog to a dialog initiated
				by the RLS server.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>-1</emphasis> - an error occurred during processing.
			</para>
			</listitem>

		</itemizedlist>

		</para>
		<example>
		<title><function>rls_handle_notify</function> usage</title>
		<programlisting format="linespecific">
...
if($rm=="NOTIFY")
    rls_handle_notify();
...
</programlisting>
		</example>
	</section>
</section>

<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_rls_update_subscriptions" xreflabel="rls_update_subscriptions">
		<title>
		<function moreinfo="none">rls_update_subscriptions</function>
		</title>
		<para>
		Triggers updating backend subscriptions after a resources-list or rls-services document
		has been updated.
		</para>
		<para>
		Name: <emphasis>rls_update_subscriptions</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem>
				<para>presentity_uri : the uri of the user who made the change
				and whose subscriptions should be updated</para>
			</listitem>
                </itemizedlist>

        <para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
opensips-cli -x mi rls_update_subscriptions sip:alice@atlanta.com
	</programlisting>
	</section>

</section>

<section>
	<title>Installation</title>
	<para>
	The module requires 2 table in OpenSIPS database: rls_presentity
	and rls_watchers.The SQL syntax to create them can be found in
	rls-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>

