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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This is new version of Jabber module that integrates XODE 
		<acronym>XML</acronym> parser for parsing Jabber messages. That 
		introduces a new module dependency: expat library.
	</para>
	<para>
		Expat is a common <acronym>XML</acronym> library and is the fastest 
		available for Linux/Unix, the second over all, after msxml library. It 
		is integrated in most of well known Linux distributions.
	</para>
	<section>
		<title>New Features</title>
		<itemizedlist>
		<listitem>
			<para>
			Presence support (see doc/xxjab.cfg for a sample cfg file) 
			(January 2003).
			</para>
		</listitem>
		<listitem>
			<para>
			SIP to Jabber conference support (December 2003).
			</para>
		</listitem>
		<listitem>
			<para>
			Possibility to manage all kinds of Jabber messages 
			(message/presence/iq) (December 2003).
			</para>
		</listitem>
		<listitem>
			<para>
			Aliases -- Possibility to set host aliases for addresses 
			(see parameter's desc.) (December 2003).
			</para>
		</listitem>
		<listitem>
			<para>
			Send received &sip; MESSAGE messages to different &im; networks 
			(Jabber, ICQ,MSN, AIM, Yahoo) using a Jabber server (December 2003).
			</para>
		</listitem>
		<listitem>
			<para>
			Send incoming Jabber instant messages as &sip; MESSAGE messages.
			</para>
		</listitem>
		<listitem>
			<para>
			Gateways detection -- Ability to see whether an &im; gateway is up 
			or down.
			</para>
		</listitem>
		</itemizedlist>
	</section>
	</section>


	<section>
	<title>Admin's Guide</title>
	<note>
		<para>
		A more complete guide about SIMPLE2Jabber gateway can be found 
		at &osipshomelink;. The part below will be removed soon, only the manual 
		from web will be updated.
		</para>
	</note>
	<para>
		The Jabber server setup is not a subject of this guide. Check <ulink
		url="http://www.jabber.org">http://www.jabber.org</ulink> for that.
	</para>
	<para>
		Useful scripts, for creating Jabber Gateway database, or for managing 
		the Jabber accounts form web are located in 'doc' subdirectory of the 
		module.
	</para>
	<para>
		Main steps of using the Jabber gateway:
	</para>
	<itemizedlist>
		<listitem>
		<para>
			Create the MySQL database.
		</para>
		</listitem>
		<listitem>
		<para>
			Setup the local Jabber server.
		</para>
		</listitem>
		<listitem>
		<para>
			Set the module parameter values in cfg file of &osips;, load the 
			dependent modules, set up the routing rules for Jabber gateway.
		</para>
		</listitem>
		<listitem>
		<para>
			Run &osips;.
		</para>
		</listitem>
	</itemizedlist>
	<para>
		The administrator of &osips;/Jabber gateway <emphasis>must</emphasis> 
		inform the users what are the aliases for Jabber/Other &im; networks. 
		Other &im;s could be <acronym>AIM</acronym>, <acronym>ICQ</acronym>, 
		<acronym>MSN</acronym>, Yahoo, and so on.
	</para>
	<para>
		These aliases depend on the server hostname where runs &osips; and 
		how local Jabber server is setup.
	</para>
	<para>
		Next is presented a use case. Prologue:
	</para>
	<itemizedlist>
		<listitem>
		<para>&osips; is running on <quote>server.org</quote>.</para>
		</listitem>
		<listitem>
		<para>
			Local Jabber server is running on <quote>jabsrv.server.org</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			Jabber network alias (first part of <quote>jdomain</quote>) is
			<quote>jabber.server.org</quote>
		</para>
		</listitem>
	</itemizedlist>
	<para>
		The aliases for other &im; networks <emphasis>must</emphasis> be the 
		same as <acronym>JID</acronym> set in Jabber configuration file for 
		each &im; transport.
	</para>
	<para>
		The <acronym>JIDs</acronym> of Jabber transports 
		<emphasis>must</emphasis> start with the name of the network. 
		For <acronym>AIM</acronym>, <acronym>JID</acronym> must start
		with <quote>aim.</quote>, for <acronym>ICQ</acronym> with 
		<quote>icq</quote> (that because I use icqv7-t), for 
		<acronym>MSN</acronym> with <quote>msn.</quote> and for
		Yahoo with <quote>yahoo.</quote>. The gateway needs these to find 
		out what transport is working and which not. For our use case these 
		could be like <quote>aim.server.org</quote>, 
		<quote>icq.server.org</quote>,
		<quote>msn.server.org</quote>, <quote>yahoo.server.org</quote>.
	</para>
	<para>
		It is indicated to have these aliases in <acronym>DNS</acronym>, thus 
		the client application can resolve the <acronym>DNS</acronym> name. 
		Otherwise there must be set the outbound proxy to &osips; server.
	</para>
	<para>
		*** Routing rules for Jabber gateway First step is to configure &osips; 
		to recognize messages for Jabber gateway. Look at 
		<quote>doc/xjab.cfg</quote> to see a sample. The idea is to look in 
		messages for destination address and if it contains Jabber alias or
		other &im; alias, that means the message is for Jabber gateway.
	</para>
	<para>
		Next step is to find out what means that message for Jabber gateway. 
		It could be a special message what triggers the gateway to take an 
		action or is a simple message which should be delivered to Jabber 
		network (using the method <quote>jab_send_message</quote>).
	</para>
	<para>
		The special messages are for: 
	</para>
	<itemizedlist>
		<listitem>
		<para>
			Registering to Jabber server (go online in Jabber network)--here 
			must be called <quote>jab_go_online</quote> method.
		</para>
		</listitem>
		<listitem>
		<para>
			Leaving the Jabber network (go offline in Jabber network)--here 
			must be called <quote>jab_go_offline</quote> method.
		</para>
		</listitem>
		<listitem>
		<para>
			Joining a Jabber conference room--here must be called 
			<quote>jab_join_jconf</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			Leaving a Jabber conference room--here must be called 
			<quote>jab_exit_jconf</quote>.
		</para>
		</listitem>
	</itemizedlist>
	<para>
		The destination address <emphasis>must</emphasis> follow the 
		following patterns:
	</para>
	<itemizedlist>
		<listitem>
		<para>
			For Jabber network: 
			<quote>username&lt;delim&gt;jabber_server@jabber_alias</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			For Jabber conference: <quote>nickname&lt;delim&gt;room&lt;delim&gt;conference_server@jabber_alias</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			For <acronym>AIM</acronym> network: 
			<quote>aim_username@aim_alias</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			For <acronym>ICQ</acronym> network: 
			<quote>icq_number@icq_alias</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			For <acronym>MSN</acronym> network:
			<quote>msn_username&lt;delim&gt;msn_server@msn_alias</quote>.
			msn_server can be <quote>msn.com</quote> or 
			<quote>hotmail.com</quote>.
		</para>
		</listitem>
		<listitem>
		<para>
			For YAHOO network: <quote>yahoo_username@yahoo_alias</quote>.
		</para>
		</listitem>
	</itemizedlist>
	<note>
		<para>
		<quote>jabber_alias</quote> is the first part of <quote>jdomain</quote>.
		</para>
	</note>
	</section>
	<section>
	<title>&adminguide;</title>
	<para>
		The user must activate his Jabber account associated with his &sip; id. For each other
		&im; network on which he wants to send messages, he must set an account for that &im;
		network. The gateway is not able to create new account in foreign networks, excepting
		local Jabber server.
	</para>
	<para>
		When you want to send a message to someone in other &im; network, you must set the
		destination of the message according with the pattern corresponding to that &im; network
		(see last part of <quote>Admin guide</quote> chapter).
	</para>
	<para>
		Sending a message to user@jabber.xxx.org which is in Jabber network, the
		destination must be: user&lt;delim&gt;jabber.xxx.org@jabber_alias.
	</para>
	<para>
		For someone who is in Yahoo network the destination must be:
		user@yahoo_alias
	</para>
	<note>
		<para>
		The &osips; administrator have to set the Jabber transports for each &im; network in
		order to be able to send messages to those networks. The alias of each &im; network
		can be found out from &osips; admin.
		</para>
		<para>
		You cannot send messages from your &sip; client to your associated Jabber
		account--is something like sending messages to yourself.
		</para>
	</note>
	</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>
				A database module.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>pa</emphasis> (Optionally) - Presence Agent.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis> - Transaction Manager.
			</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>Expat</emphasis> library.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		<acronym>SQL</acronym> &url; of database.
		</para>
		<para>
		<emphasis>
			Default value is <quote>mysql://root@127.0.0.1/sip_jab</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "db_url", "mysql://username:password@host/sip_jab")
...
</programlisting>
		</example>
	</section>

	<section id="param_jaddress" xreflabel="jaddress">
		<title><varname>jaddress</varname> (string)</title>
		<para>
		&ip; or hostname of Jabber server -- it must be the same as the value from &lt;host&gt;
		tag of Jabber server config file.
		</para>
		<para>
		<emphasis>
			Default value is <quote>127.0.0.1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>jaddress</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "jaddress", "1.2.3.4")
...
</programlisting>
		</example>
	</section>

	<section id="param_jport" xreflabel="jport">
		<title><varname>jport</varname> (integer)</title>
		<para>
		Port number of Jabber server.
		</para>
		<para>
		<emphasis>
			Default value is <quote>5222</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>jport</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "jport", 1234)
...
</programlisting>
		</example>
	</section>

	<section id="param_jdomain" xreflabel="jdomain">
		<title><varname>jdomain</varname> (string)</title>
		<para>
		Format: jabber.sipserver.com=&lt;delim&gt;. If the destination is for Jabber network
		the &uri; should be like: username&lt;delim&gt;jabber_server@jdomain or
		nickname&lt;delim&gt;roomname&lt;delim&gt;conference_server@jdomain
		</para>
		<para>
		&lt;delim&gt; must be a un-reserved character. By default this character is * .  The
		destination will be transformed to username@jabber_server or
		roomname@conference_server/nickname before the message is sent to Jabber server.
		</para>
		<para>
		<emphasis>
			Default value is none.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>jdomain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "jdomain", "jabber.sipserver.com=*")
...
</programlisting>
		</example>
	</section>

	<section id="param_aliases" xreflabel="aliases">
		<title><varname>aliases</varname> (string)</title>
		<para>
		Aliases for &im; networks.
		</para>
		<para>
		Format: <quote>N;alias1=&lt;delim1&gt;;...;aliasN=&lt;delimN&gt;;</quote>
		Destinations like '*@aliasX' could have other format than those specified for Jabber
		network.  All &lt;delim&gt; from user part of the destination address will be
		changed to &lt;delimX&gt; if the destination address contains &lt;aliasX&gt;.
		</para>
		<para>
		(Ex: jdomain is 'jabber.x.com=*' and msn_alias is 'msn.x.com=%'. The destination
		address forM <acronym>MSN</acronym> Network, on &sip; side, is like
		'username*hotmail.com@msn.x.com'. The destination address will be transformed to
		'username%hotmail.com@msn.x.com'.  'msn.x.com' must be the same as the
		<acronym>JID</acronym> associated with <acronym>MSN</acronym> transport in Jabber
		configuration file (usually is 'jabberd.xml'))
		</para>
		<para>
		<emphasis>
			Default value is none.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>jdomain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "aliases", "1;msn.x.com=%")
...
</programlisting>
		</example>
	</section>

	<section id="param_proxy" xreflabel="proxy">
		<title><varname>proxy</varname> (string)</title>
		<para>
		Outbound proxy address.
		</para>
		<para>
		Format: ip_address:port hostname:port
		</para>
		<para>
		All &sip; messages generated by gateway will be sent to that address. If is
		missing, the message will be delivered to the hostname of the destination address
		</para>
		<para>
		Default value is none.
		</para>
		<example>
		<title>Set <varname>proxy</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "proxy", "10.0.0.1:5060 sipserver.com:5060")
...
</programlisting>
		</example>
	</section>

	<section id="param_registrar" xreflabel="registrar">
		<title><varname>registrar</varname> (string)</title>
		<para>
		The address in whose behalf the INFO and ERROR messages are sent.
		</para>
		<para>
		<emphasis>
			Default value is <quote>jabber_gateway@127.0.0.1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>registrar</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "registrar", "jabber_gateway@127.0.0.1")
...
</programlisting>
		</example>
	</section>

	<section id="param_workers" xreflabel="workers">
		<title><varname>workers</varname> (integer)</title>
		<para>
		Number of workers.
		</para>
		<para>
		<emphasis>
			Default value is 2.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>workers</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "workers", 2)
...
</programlisting>
		</example>
	</section>

	<section id="param_max_jobs" xreflabel="max_jobs">
		<title><varname>max_jobs</varname> (integer)</title>
		<para>
		Maximum jobs per worker.
		</para>
		<para>
		<emphasis>
			Default value is 10.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_jobs</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "max_jobs", 10)
...
</programlisting>
		</example>
	</section>

	<section id="param_cache_time" xreflabel="cache_time">
		<title><varname>cache_time</varname> (integer)</title>
		<para>
		Cache time of a Jabber connection.
		</para>
		<para>
		<emphasis>
			Default value is 600.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cache_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "cache_time", 600)
...
</programlisting>
		</example>
	</section>

	<section id="param_delay_time" xreflabel="delay_time">
		<title><varname>delay_time</varname> (integer)</title>
		<para>
		Time to keep a &sip; message (in seconds).
		</para>
		<para>
		<emphasis>
			Default value is 90 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>delay_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "delay_time", 90)
...
</programlisting>
		</example>
	</section>

	<section id="param_sleep_time" xreflabel="sleep_time">
		<title><varname>sleep_time</varname> (integer)</title>
		<para>
		Time between expired Jabber connections checking (in seconds).
		</para>
		<para>
		<emphasis>
			Default value is 20 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sleep_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "sleep_time", 20)
...
</programlisting>
		</example>
	</section>

	<section id="param_check_time" xreflabel="check_time">
		<title><varname>check_time</varname> (integer)</title>
		<para>
		Time between checking the status of JabberGW workers (in seconds).
		</para>
		<para>
		<emphasis>
			Default value is 20 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>check_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "check_time", 20)
...
</programlisting>
		</example>
	</section>

	<section id="param_priority" xreflabel="priority">
		<title><varname>priority</varname> (str)</title>
		<para>
		Presence priority for Jabber gateway.
		</para>
		<para>
		<emphasis>
			Default value is <quote>9</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>priority</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "priority", "3")
...
</programlisting>
		</example>
	</section>

	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_jab_send_message" xreflabel="jab_send_message()">
		<title>
		<function moreinfo="none">jab_send_message()</function>
		</title>
		<para>
		Converts &sip; MESSAGE message to a Jabber message and sends it to Jabber server.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>jab_send_message()</function> usage</title>
		<programlisting format="linespecific">
...
jab_send_message();
...
</programlisting>
		</example>
	</section>
	<section id="func_jab_join_jconf" xreflabel="jab_join_jconf()">
		<title>
		<function moreinfo="none">jab_join_jconf()</function>
		</title>
		<para>
		Join a Jabber conference--the nickname, room name and conference server address
		should be included in To header as: nickname%roomname%conference_server@jdomain . If
		the nickname is missing, then the &sip; username is used.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>jab_join_jconf()</function> usage</title>
		<programlisting format="linespecific">
...
jab_join_jconf();
...
</programlisting>
		</example>
	</section>
	<section id="func_jab_exit_jconf" xreflabel="jab_exit_jconf()">
		<title>
		<function moreinfo="none">jab_exit_jconf()</function>
		</title>
		<para>
		Leave a Jabber conference--the nickname, room name and conference server address
		should be included in To header as: nickname%roomname%conference_server@jdomain .
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>jab_exit_jconf()</function> usage</title>
		<programlisting format="linespecific">
...
jab_exit_jconf();
...
</programlisting>
		</example>
	</section>

	<section id="func_jab_go_online" xreflabel="jab_go_online()">
		<title>
		<function moreinfo="none">jab_go_online()</function>
		</title>
		<para>
		Register to the Jabber server with associated Jabber <abbrev>ID</abbrev> of the &sip; user.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>jab_go_online()</function> usage</title>
		<programlisting format="linespecific">
...
jab_go_online();
...
</programlisting>
		</example>
	</section>

	<section id="func_jab_go_offline" xreflabel="jab_go_offline()">
		<title>
		<function moreinfo="none">jab_go_offline()</function>
		</title>
		<para>
		Log off from Jabber server the associated Jabber <abbrev>ID</abbrev> of the &sip; user.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>jab_go_offline()</function> usage</title>
		<programlisting format="linespecific">
...
jab_go_offline();
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

