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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.3 $</revnumber>
		<date>$Date: 2004/08/24 08:58:30 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<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 &serhomelink;. 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 &ser;, load the dependent
		    modules, set up the routing rules for Jabber gateway.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Run &ser;.
		</para>
	    </listitem>
	</itemizedlist>
	<para>
	    The administrator of &ser;/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 &ser; and how local Jabber
	    server is setup.
	</para>
	<para>
	    Next is presented a use case. Prologue:
	</para>
	<itemizedlist>
	    <listitem>
		<para>&ser; 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 &ser; server.
	</para>
	<para>
	    *** Routing rules for Jabber gateway First step is to configure &ser; 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>User's Guide</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 &ser; 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 &ser; 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>
	<title>Dependencies</title>
	<section>
	    <title>&ser; 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
		&ser; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>Expat</emphasis> library.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Exported Parameters</title>
	<section>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
	    <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>
    <section>
	<title>Exported Functions</title>
	<section>
	    <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>
	    <example>
		<title><function>jab_send_message()</function> usage</title>
		<programlisting format="linespecific">
...
jab_send_message();
...
</programlisting>
	    </example>
	</section>
	<section>
	    <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>
	    <example>
		<title><function>jab_send_message()</function> usage</title>
		<programlisting format="linespecific">
...
jab_send_message();
...
</programlisting>
	    </example>
	</section>
	<section>
	    <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>
	    <example>
		<title><function>jab_join_jconf()</function> usage</title>
		<programlisting format="linespecific">
...
jab_join_jconf();
...
</programlisting>
	    </example>
	</section>
	<section>
	    <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>
	    <example>
		<title><function>jab_exit_jconf()</function> usage</title>
		<programlisting format="linespecific">
...
jab_exit_jconf();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <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>
	    <example>
		<title><function>jab_go_online()</function> usage</title>
		<programlisting format="linespecific">
...
jab_go_online();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <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>
	    <example>
		<title><function>jab_go_offline()</function> usage</title>
		<programlisting format="linespecific">
...
jab_go_offline();
...
</programlisting>
	    </example>
	</section>
    </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("jabber.sgml" "Book" "chapter")
End:
-->
