<?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 offers support for instant message conference using
		SIP MESSAGE requests. It follows the architecture of IRC channels.
		The conferences are managed by commands that can be sent embedded
		in the MESSAGE body, because there are just a few SIP UA implementations
		which have GUI for IM conferencing.
	</para>
	<para>
	By sending a SIP MESSAGE a configured SIP URI to the IM conferencing manager,
	the user can send commands to manage conference rooms. Once the conference
	room is created, users can send commands directly to conference's URI.
	</para>
	<para>
	To ease the integration in the configuration file, the interpreter of
	the IMC commands are embedded in the module. From a configuration point of
	view, there is only one function which has to be executed for both
	messages and commands.
	</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>db_mysql</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</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>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="imc.p.db_url">
		<title><varname>db_url</varname> (str)</title>
		<para>
		The database url.
		</para>
		<para>
		<emphasis>
		The default value is <quote>&defaultdb;</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.db_mode">
		<title><varname>db_mode</varname>(integer)</title>
		<para>
		The module supports 2 modes of operation, high speed memory
		based storage (mode 0), and database only (mode 2) where all
		data is stored in a database, allowing scalability at the
		expense of speed. Mode 1 is reserved.
		</para>
		<para>
		<emphasis>	Default value is <quote>0</quote>
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "db_mode", 2)
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.rooms_table">
		<title><varname>rooms_table</varname> (str)</title>
		<para>
		The name of the table storing IMC rooms.
		</para>
		<para>
		<emphasis>
		The default value is "imc_rooms".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rooms_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "rooms_table", "rooms")
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.members_table">
		<title><varname>members_table</varname> (str)</title>
		<para>
		The name of the table storing IMC members.
		</para>
		<para>
		<emphasis>
		The default value is "imc_members".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>members_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "members_table", "members")
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.hash_size">
		<title><varname>hash_size</varname> (integer)</title>
		<para>
		The power of 2 to get the size of the hash table used for storing
		members and rooms.
		</para>
		<para>
		<emphasis>
		The default value is 4 (resulting in hash size 16).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "hash_size", 8)
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.imc_cmd_start_char">
		<title><varname>imc_cmd_start_char</varname> (str)</title>
		<para>
		The character which indicates that the body of the message is
		a command.
		</para>
		<para>
		<emphasis>
		The default value is "#".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>imc_cmd_start_char</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "imc_cmd_start_char", "#")
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.outbound_proxy">
		<title><varname>outbound_proxy</varname> (str)</title>
		<para>
			The SIP address used as next hop when sending the message. Very
			useful when using &kamailio; with a domain name not in DNS, or
			when using a separate &kamailio; instance for imc processing. If
			not set, the message will be sent to the address in destination
			URI.
		</para>
		<para>
		<emphasis>
		Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>outbound_proxy</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "outbound_proxy", "sip:kamailio.org;transport=tcp")
...
</programlisting>
		</example>
	</section>

	<section id="imc.p.extra_hdrs">
		<title><varname>extra_hdrs</varname> (str)</title>
		<para>
		Extra headers (each ending with \r\n) to be added in
		messages sent out from imc server.
		</para>
		<para>
		<emphasis>
		Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>extra_hdrs</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "extra_hdrs", "P-Flags: 3\r\n")
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.create_on_join">
		<title><varname>create_on_join</varname> (integer)</title>
		<para>
		If set to 1 and user requests to join a non-existing
		room, the room will be automatically created. If set
		to 0, joining a non-existing room returns an error.
		</para>
		<para>
		<emphasis>
		The default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>create_on_join</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "create_on_join", 0)
...
</programlisting>
		</example>
	</section>
	<section id="imc.p.check_on_create">
		<title><varname>check_on_create</varname> (integer)</title>
		<para>
		  If set to 1, the chat server will report an error if
		  the user attempts to create a room that already
		  exists.
		</para>
		<para>
		<emphasis>
		The default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>check_on_create</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("imc", "check_on_create", 1)
...
</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title>Functions</title>
	<section>
		<title id="imc.p.imc_manager">
		<function moreinfo="none">imc_manager()</function>
		</title>
		<para>
		THis function handles incoming MESSAGE requests.
		If detects if the body of the message is a
		conference command it executes it, otherwise it sends the
		message to all the members in the room.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE. See command description
		for error codes returned by this function.
		</para>
		<example>
		<title>Usage of <varname>imc_manager()</varname> function</title>
		<programlisting format="linespecific">
...
# the rooms will be named chat-xyz to avoid overlapping
# with usernames
if(is_method("MESSAGE)
    &amp;&amp; (uri=~ "sip:chat-[0-9]+@" || (uri=~ "sip:chat-manager@"))
{
    if(imc_manager())
        sl_send_reply("200", "ok");
    else
        sl_send_reply("500", "command error");
    exit;
}
...
</programlisting>
		</example>
	</section>
	<section>
		<title id="imc.p.imc_room_active">
		<function moreinfo="none">imc_room_active(room)</function>
		</title>
		<para>
		Return 1 (true) if the room is active, -1 (false) if the room is not
		found. The parameter is the SIP URI to identify the room, it can contain
		variables.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title>Usage of <varname>imc_room_active()</varname> function</title>
		<programlisting format="linespecific">
...
    if(imc_room_active("sip:chat-sip@$fd")) {
        ...
    }
...
</programlisting>
		</example>
	</section>
	<section>
		<title id="imc.p.imc_room_member">
		<function moreinfo="none">imc_room_member(room, user)</function>
		</title>
		<para>
		Return 1 (true) if the user is member of the room, -1 (false) if the
		user is not member of the room. The parameters are the SIP URIs to
		identify the room and the user, they can contain variables.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title>Usage of <varname>imc_room_member()</varname> function</title>
		<programlisting format="linespecific">
...
    if(imc_room_member("sip:chat-sip@$fd", "sip:$rU@$rd")) {
        ...
    }
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>RPC Commands</title>
	<section id="imc.r.list_rooms">
		<title>imc.list_rooms</title>
		<para>
		Lists of the IM Conferencing rooms.
		</para>
		<para>
		Name: <emphasis>imc.list_rooms</emphasis>
		</para>
		<para>Parameters: none</para>

		<para>
		RPC Command Format:
		</para>
		<programlisting  format="linespecific">
...
&kamcmd; imc_list_rooms
...
		</programlisting>
	</section>

	<section id="imc.r.list_members">
		<title>imc.list_members</title>
		<para>
		Listing of the members in IM Conferencing rooms.
		</para>
		<para>
		Name: <emphasis>imc.list_members</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_room_ : the room for which you want to list the members</para></listitem>
		</itemizedlist>

		<para>
		RPC Command Format:
		</para>
		<programlisting  format="linespecific">
...
&kamcmd; imc_list_members _room_
...
	</programlisting>
	</section>
</section>


<section>
	<title>Statistics</title>
	<section>
		<title>
		<function moreinfo="none">active_rooms</function>
		</title>
		<para>
		Number of active IM Conferencing rooms.
		</para>
	</section>
</section>


<section>
	<title>IMC Commands</title>
		<para>
		A command is identified by the starting character. A command must be
		written in one line. By default, the starting character is '#'. You
		can change it via "imc_cmd_start_char" parameter.
		</para>
		<para>
		Next picture presents the list of commands and their parameters.
		</para>

		<example>
		<title>List of commands</title>
		<programlisting format="linespecific">
...

1.create
  -creates a conference room
  -takes 2 parameters:
     1) the name of the room
     2)optional- "private" -if present the created room is private
	   and new members can be added only though invitations
  -the user is added as the first member and owner of the room
  -eg:  #create chat-000 private
  -error case: return codes: -30 -- -39

2.join
  -makes the user member of a room
  -takes one optional parameter - the address of the room -if not
    present it will be considered to be the address in the To
    header of the message
  -if the room does not exist the command is treated as create
  -eg:join sip:chat-000@kamailio.org,
      or just, #join, sent to sip:chat-000@kamailio.org
  -error case: return codes: -40 -- -49

3.invite
  -invites a user to become a member of a room
  -takes 2 parameters:
     1)the complete address of the user
     2)the address of the room -if not present it will be considered
	   to be the address in the To header of the message
  -only certain users have the right to invite other user: the owner
    and the administrators
  -eg: #invite sip:john@kamailio.org sip:chat-000@kamailio.org
    or  #invite john@kamailio.org sent to sip:chat-000@kamailio.org
  -error case: return codes: -50 -- -59

4.accept
  -accepting an invitation
  -takes one optional parameter - the address of the room - if not
    present it will be considered to be the address in the To header
    of the message
  -eg: #accept sip:john@kamailio.org
  -error case: return codes: -60 -- -69

5.reject
  -rejects an invitation
  -the parameter is the same as for accept
  -error case: return codes: -70 -- -79

6.remove
  -deletes a member from a room
  -takes 2 parameters:
    1)the complete address of the member
    2)the address of the room -if not present it will be considered
	  to be the address in the To header of the message
  -only certain members have the right to remove other members
  -eg: #remove sip:john@kamailio.org, sent to sip:chat-000@kamailio.org
  -error case: return codes: -80 -- -89

7.leave
  -leaving a room
  -takes one optional parameter - the address of the room - if not
    present it will be considered to be the address in the To header
    of the message
  -if the user is the owner of the room, the room will be destroyed
  -error case: return codes: -90 -- -99

8.destroy
  -removing a room
  -the parameter is the same as for leave
  -only the owner of a room has the right to destroy it
  -error case: return codes: -110 -- -119

9.members
  -list members in a room
  -error case: return codes: -100 -- -109

10.add
  -adds a user to a room
  -takes 2 parameters:
     1)the complete address of the user
     2)the address of the room -if not present it will be considered
	   to be the address in the To header of the message
  -only certain users have the right to add other users: the owner
    and the administrators
  -eg: #add sip:john@kamailio.org sip:chat-000@kamailio.org
    or  #add john@kamailio.org sent to sip:chat-000@kamailio.org
  -error case: return codes: -50 -- -59

11.modify
  -modify user role in a room
  -takes 3 parameters:
     1)the complete address of the user
	 2)the role of the user
     3)the address of the room -if not present it will be considered
	   to be the address in the To header of the message
  -only certain users have the right to invite other user: the owner
    and the administrators
  -roles: owner, admin, member
  -eg: #invite sip:john@kamailio.org admin sip:chat-000@kamailio.org
    or  #invite john@kamailio.org admin sent to sip:chat-000@kamailio.org
  -error case: return codes: -120 -- -129
...
</programlisting>
		</example>
	</section>
	<section>
	<title>Installation</title>
		<para>
		Before running &kamailio; with IMC, you have to setup the database
		tables where the module will store the data. For that, if the
		tables were not created by the installation script or you choose
		to install everything by yourself you can use the imc-create.sql
		<acronym>SQL</acronym> script in the database directories in the
		kamailio/scripts folder as template.
		You can also find the complete database documentation on the
		project webpage, &kamailiodbdocslink;.
		</para>
	</section>

</chapter>

