<?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 "../../../docbook/entities.xml">
%docentities;

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

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		Note: the module is not actively maintained and may be deprecated
		in the near future.
	</para>
	<para>
		Purple module is a multi-protocol instant-messaging gateway module
		which use <emphasis>libpurple</emphasis>, the library that Pidgin
		(ex-gaim) is based on.
	</para>
	<para>
		This plugin was written as a  proof of concept gateway between
		SIP and MSN/Live networks. As libpurple is written to code
		multi-protocol graphic IM clients, it provides a high level API in
		order to manipulate accounts, contacts, contacts lists,
		conversations and more.
	</para>
	<para>
		This module provides a multi-protocol IM/Presence client running
		inside &kamailio; with an account for each protocol used by each
		SIP user. libpurple is designed for a graphic client for
		only one user.
	</para>
	<para>
		It's no really adapted to a production environment with a huge user
		count but can be used in order to demonstrate the concept or in a
		SOHO environment.
	</para>
	<para>
		By default, there's some undefined symbol errors with libpurple
		shared object when using it inside &kamailio;. To solve it, you have to
		force preload of the library by setting up LD_PRELOAD environment
		variable.
	</para>
	<para>
		Before starting &kamailio; use (adapt the path to your environment):
	</para>
	<programlisting>
		export LD_PRELOAD=$LD_PRELOAD:/usr/local/lib/libpurple.so
	</programlisting>
	<para>
		Limitations: doesn't implement authorization requests from external
		accounts to SIP.
	</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>database driver module (db_mysql, ...)</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>libpurple, e.g. from pidgin 2.5.2</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Database</title>
		<para>
		The database is used to map SIP URIs with external accounts (eg. MSN).
		</para>
		<example>
		<title>Database table description</title>
		<programlisting format="linespecific">
...
+----------+------------------+------+-----+---------+----------------+
| Field    | Type             | Null | Key | Default | Extra          |
+----------+------------------+------+-----+---------+----------------+
| id       | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| sip_user | varchar(128)     | NO   |     | NULL    |                |
| ext_user | varchar(128)     | NO   |     | NULL    |                |
| ext_prot | varchar(16)      | NO   |     | NULL    |                |
| ext_pass | varchar(64)      | YES  |     | NULL    |                |
+----------+------------------+------+-----+---------+----------------+
...
</programlisting>
		</example>
		<para>
		The meaning of columns:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>sip_user</emphasis>: user's SIP URI.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>ext_user</emphasis>: user's external account login.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>ext_prot</emphasis>: purple plugin id to use, except
				for gtalk.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>ext_pass</emphasis>: user's external account password.
			</para>
			</listitem>
		</itemizedlist>
		<example>
		<title>Database sample records</title>
		<programlisting format="linespecific">
...
+----+------------------+-----------------+----------------+----------+
| id | sip_user         | ext_user        | ext_prot       | ext_pass |
+----+------------------+-----------------+----------------+----------+
|  1 | sip:alice@domain | alice@live.com  | prpl-msn-pecan | password |
|  2 | sip:bob@domain   | bob@live.com    | prpl-msn-pecan | password |
|  3 | sip:alice@domain | alice@gmail.com | gtalk          | password |
|  4 | sip:bob@domain   | bob@gmail.com   | gtalk          | password |
+----+------------------+-----------------+----------------+----------+
...
</programlisting>
		</example>
		<example>
		<title>MySQL create script</title>
		<programlisting format="linespecific">
...
CREATE TABLE purplemap (
  id INT UNSIGNED PRIMARY KEY NOT NULL AUTO_INCREMENT,
  sip_user VARCHAR(128) NOT NULL,
  ext_user VARCHAR(128) NOT NULL,
  ext_prot VARCHAR(16) NOT NULL,
  ext_pass VARCHAR(64)
);
...
</programlisting>
		</example>
	</section>

	<section>
	<title>Parameters</title>
	<section>
		<title><varname>db_url</varname> (str)</title>
		<para>
			The URL to connect to database.
		</para>
		<para>
		<emphasis>
			Default value is <quote>&defaultrodb;</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("purple", "db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>db_table</varname> (str)</title>
		<para>
			Database table name.
		</para>
		<para>
		<emphasis>
			Default value is purplemap.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("purple", "db_table", "purplemap")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>httpProxy_host</varname> (str)</title>
		<para>
			Address of HTTP proxy.
		</para>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>httpProxy_host</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("purple", "httpProxy_host", "10.26.52.12")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>httpProxy_port</varname> (int)</title>
		<para>
			Port of HTTP proxy.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>httpProxy_port</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("purple", "httpProxy_port", 3128)
...
</programlisting>
		</example>
	</section>
	</section>
	
	<section>
	<title>Functions</title>
	<section>
		<title>
		<function moreinfo="none">purple_send_message()</function>
		</title>
		<para>
			Send message to a purple destination.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>purple_send_message</function> usage</title>
		<programlisting format="linespecific">
...
if (is_method("MESSAGE")) {
    xlog("MESSAGE $ru from [$fu] to [$tu]\n");
    if (uri !~ "sip:.+@.+;proto=.+") {
        purple_send_message();
        sl_send_reply("202", "Accepted");
    }
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">purple_handle_publish()</function>
		</title>
		<para>
			Handle PUBLISH to a purple destination.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>purple_handle_publish</function> usage</title>
		<programlisting format="linespecific">
...
if(is_method("PUBLISH")) {
    xlog("PUBLISH $ru from [$fu] to [$tu]\n");
    if (uri !~ "sip:.+@.+;proto=.+")
        purple_handle_publish();
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">purple_handle_subscribe()</function>
		</title>
		<para>
			Handle SUBSCRIBE to a purple destination.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>purple_handle_subscribe</function> usage</title>
		<programlisting format="linespecific">
...
if(is_method("SUBSCRIBE")) {
    xlog("SUBSCRIBE $ru from [$fu] to [$tu]\n");
    if ($hdr(Event) == "presence")
        purple_handle_subscribe("$ruri", "$hdr(Expires)");
}
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

