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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module is a gateway for presence between SIP and XMPP.  
	</para>
	<para>
		It translates one format into another and uses xmpp, pua and presence
		modules to manage the transmition of presence state information. 
	</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>presence</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>pua</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xmpp</emphasis>.
			</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_server_address" xreflabel="server_address">
		<title><varname>server_address</varname>(str)</title>
		<para>
		The IP address of the server. 
		</para>
		<example>
		<title>Set <varname>server_address</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua_xmpp", "server_address", "sip:sa@opensips.org:5060")
...
</programlisting>
		</example>
	</section>

	<section id="param_presence_server" xreflabel="presence_server">
		<title><varname>presence_server</varname> (str)</title>
		<para>
		The the address of the presence server. If set, it will be
		used as outbound proxy when sending PUBLISH requests.
		</para>
		<example>
		<title>Set <varname>presence_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua_xmpp", "presence_server", "sip:pa@opensips.org:5075")
...
	</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<para>
	Functions exported to be used in configuration file.
	</para>
	<section id="func_pua_xmpp_notify" xreflabel="pua_xmpp_notify()">
		<title>
		<function moreinfo="none">pua_xmpp_notify()</function>
		</title>
		<para>
		Function that handles Notify messages addressed to a user from
		an xmpp domain. It requires filtering after method and domain in
		configuration file. If the function is successful, a 2xx reply must
		be sent.  
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>Notify2Xmpp</function> usage</title>
		<programlisting format="linespecific">
...
	if( is_method("NOTIFY") &amp;&amp; $ru=~"sip:.+@sip-xmpp.siphub.ro")
	{
		if(Notify2Xmpp())
			t_reply(200, "OK");
		exit;
	}
...
</programlisting>
		</example>
	</section>

	<section id="func_pua_xmpp_req_winfo" xreflabel="pua_xmpp_req_winfo()">
		<title>
		<function moreinfo="none">pua_xmpp_req_winfo(request_uri, expires)</function>
		</title>
		<para>
		Function called when a Subscribe addressed to a user from a
		xmpp domain is received. It calls sending a Subscribe for 
		winfo for the user, and the following Notify with dialog-info
		is translated into a subscription in xmpp. 
		It also requires filtering in configuration file, after method, 
		domain and event(only for presence).
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>request_uri</emphasis> (string)
			</para></listitem>
			<listitem><para>
				<emphasis>expires</emphasis> (int) - value of Expires header field 
				in received Subscribe.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>xmpp_send_winfo</function> usage</title>
		<programlisting format="linespecific">
...
	if( is_method("SUBSCRIBE"))
	{
		handle_subscribe();
		if($ru=~"sip:.+@sip-xmpp.siphub.ro" &amp;&amp; $hdr(Event)== "presence")
		{
			pua_xmpp_req_winfo($ruri, $hdr(Expires));
		}
		t_release();
	}

...
		</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title> Filtering </title>
	<para> 
	Instead of "sip-xmpp.siphub.ro"  in the example you should use the value
	set for the xmpp module parameter named 'gateway_domain'.
	</para>
	</section>


</chapter>

