
imc Module

Anca-Maria Vamanu

   voice-system.ro

Daniel-Constantin Mierla

Stefan Popescu

Edited by

Anca-Maria Vamanu

   Copyright © 2006 voice-system.ro
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (str)
              1.3.2. rooms_table (str)
              1.3.3. members_table (str)
              1.3.4. hash_size (integer)
              1.3.5. imc_cmd_start_char (str)

        1.4. Exported Functions

              1.4.1. imc_manager()

        1.5. Exported MI Functions

              1.5.1. imc_list_rooms
              1.5.2. imc_list_members

        1.6. Exported Statistics

              1.6.1. active_rooms

        1.7. IMC Commands
        1.8. Installation

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set db_url parameter
   1-2. Set rooms_table parameter
   1-3. Set members_table parameter
   1-4. Set hash_size parameter
   1-5. Set imc_cmd_start_char parameter
   1-6. Usage of imc_manager() function
   1-7. List of commands
   1-8. IMC tables
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This module offers support for instant message conference. It
   follows the architecture of IRC channels, you can send
   commands embedded in MESSAGE body, because there are no SIP UA
   clients which have GUI for IM conferencing.

   You have to define an URI corresponding to im conferencing
   manager, where user can send commands to create a new
   conference room. Once the conference room is created, users
   can send commands directly to conferece's URI.

   To ease the integration in the configuration file, the
   interpreter of the IMC commands are embeded in the module,
   from configuration poin of view, there is only one function
   which has to be executed for both messages and commands.
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * mysql.
     * tm.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. db_url (str)

   The database url.

   The default value is NULL. 

   Example 1-1. Set db_url parameter
...
modparam("imc", "db_url",
           "mysql://openser:openserrw@192.168.2.132/openser")
...
     _________________________________________________________

1.3.2. rooms_table (str)

   The name of the table storing IMC rooms.

   The default value is "imc_rooms". 

   Example 1-2. Set rooms_table parameter
...
modparam("imc", "rooms_table", "rooms")
...
     _________________________________________________________

1.3.3. members_table (str)

   The name of the table storing IMC members.

   The default value is "imc_members". 

   Example 1-3. Set members_table parameter
...
modparam("imc", "rooms_table", "members")
...
     _________________________________________________________

1.3.4. hash_size (integer)

   The power of 2 to get the size of the hash table used for
   storing members and rooms.

   The default value is 4 (resultimg in hash size 16). 

   Example 1-4. Set hash_size parameter
...
modparam("imc", "hash_size", 8)
...
     _________________________________________________________

1.3.5. imc_cmd_start_char (str)

   The character which indicates that the body of the message is
   a command.

   The default value is "#". 

   Example 1-5. Set imc_cmd_start_char parameter
...
modparam("imc", "imc_cmd_start_char", "#")
...
     _________________________________________________________

1.4. Exported Functions

1.4.1. imc_manager()

   Handles Message method.It detects if the body of the message
   is a conference command.If so it executes it, otherwise it
   sends the message to all the members in the room.

   This function can be used from REQUEST_ROUTE.

   Example 1-6. Usage of imc_manager() function
...
# the rooms will be named chat-xyz to avoid overlapping
# with usernames
if(is_method("MESSAGE)
        && (uri=~ "sip:chat-[0-9]+@" || (uri=~ "sip:chat-manager@")
    imc_manager();
...
     _________________________________________________________

1.5. Exported MI Functions

1.5.1. imc_list_rooms

   Lists of the IM Conferencing rooms.

   Name: imc_list_rooms

   Parameters: none

   MI FIFO Command Format:
                :imc_list_rooms:_reply_fifo_file_
                _empty_line_
     _________________________________________________________

1.5.2. imc_list_members

   Listing of the members in IM Conferencing rooms.

   Name: imc_list_members

   Parameters:

     * _room_ : the room for which you want to list the members

   MI FIFO Command Format:
                :imc_list_members:_reply_fifo_file_
                _room_
                _empty_line_
     _________________________________________________________

1.6. Exported Statistics

1.6.1. active_rooms

   Number of active IM Conferencing rooms.
     _________________________________________________________

1.7. IMC Commands

   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.

   Next picture presents the list of commands and their
   parameters.

   Example 1-7. List of commands
...

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

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@openser.org,
      or just, #join, sent to sip:chat-000@openser.org

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@openser.org sip:chat-000@openser.org
    or  #invite john@openser.org sent to sip:chat-000@openser.org

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@openser.org

5.deny
  -rejects an invitation
  -the parameter is the same as for accept

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@openser.org, sent to sip:chat-000@openser.org

7.exit
  -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

8.destroy
  -removing a room
  -the parameter is the same as for exit
  -only the owner of a room has the right to destroy it

9.list
  -list members in a room

...
     _________________________________________________________

1.8. Installation

   Before running IMC you have to create two new tables in
   database. Use the next SQL statements for that.

   Example 1-8. IMC tables
...
use openser;

CREATE TABLE `imc_members` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `username` varchar(128) NOT NULL,
  `domain` varchar(128) NOT NULL,
  `room` varchar(64) NOT NULL,
  `flag` int(11) NOT NULL,
  UNIQUE KEY ndr_imc (`username`,`domain`,`room`),
  PRIMARY KEY (id)
) ENGINE=MyISAM;

CREATE TABLE `imc_rooms` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `name` varchar(128) NOT NULL,
  `domain` varchar(128) NOT NULL,
  `flag` int(11) NOT NULL,
  UNIQUE KEY nd_imc (`name`,`domain`),
  PRIMARY KEY (id)
) ENGINE=MyISAM;

...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
