pua_xmpp_admin.xml

<?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>
		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 transmission of presence state information. 
	</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>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
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libxml</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
		<section id="pua_xmpp.p.server_address">
		<title><varname>server_address</varname>(str)</title>
		<para>
		The SIP URI specifying the address of the SIP server. 
		</para>
		<example>
		<title>Set <varname>server_address</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua_xmpp", "server_address", "sip:160.23.23.10")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<para>
	Functions exported to be used in configuration file.
	</para>
	<section id="pua_xmpp.f.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>pua_xmpp_notify</function> usage</title>
		<programlisting format="linespecific">
...
	if( is_method("NOTIFY") &amp;&amp; uri=~"sip:.+@sip-xmpp.kamailio.org")
	{
		if(pua_xmpp_notify())
			t_reply("200", "OK");
		exit;
	}
...
</programlisting>
		</example>
	</section>

	<section id="pua_xmpp.f.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 an
		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>
		It takes 2 parameters: request_uri and the value of Expires header field 
		in received Subscribe.
		</para>
		<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(uri=~"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>