imc Module

Anca-Maria Vamanu

   Voice Sistem SRL

Daniel-Constantin Mierla

   <miconda@gmail.com>

Stefan Popescu

Edited by

Anca-Maria Vamanu

Joey Golan

   Copyright © 2006 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url (str)
              3.2. db_mode(integer)
              3.3. rooms_table (str)
              3.4. members_table (str)
              3.5. hash_size (integer)
              3.6. imc_cmd_start_char (str)
              3.7. outbound_proxy (str)
              3.8. extra_hdrs (str)
              3.9. create_on_join (integer)
              3.10. check_on_create (integer)

        4. Functions

              4.1. imc_manager()
              4.2. imc_room_active(room)
              4.3. imc_room_member(room, user)

        5. RPC Commands

              5.1. imc.list_rooms
              5.2. imc.list_members

        6. Statistics

              6.1. active_rooms

        7. IMC Commands
        8. Installation

   List of Examples

   1.1. Set db_url parameter
   1.2. Set db_mode parameter
   1.3. Set rooms_table parameter
   1.4. Set members_table parameter
   1.5. Set hash_size parameter
   1.6. Set imc_cmd_start_char parameter
   1.7. Set outbound_proxy parameter
   1.8. Set extra_hdrs parameter
   1.9. Set create_on_join parameter
   1.10. Set check_on_create parameter
   1.11. Usage of imc_manager() function
   1.12. Usage of imc_room_active() function
   1.13. Usage of imc_room_member() function
   1.14. List of commands

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url (str)
        3.2. db_mode(integer)
        3.3. rooms_table (str)
        3.4. members_table (str)
        3.5. hash_size (integer)
        3.6. imc_cmd_start_char (str)
        3.7. outbound_proxy (str)
        3.8. extra_hdrs (str)
        3.9. create_on_join (integer)
        3.10. check_on_create (integer)

   4. Functions

        4.1. imc_manager()
        4.2. imc_room_active(room)
        4.3. imc_room_member(room, user)

   5. RPC Commands

        5.1. imc.list_rooms
        5.2. imc.list_members

   6. Statistics

        6.1. active_rooms

   7. IMC Commands
   8. Installation

1. Overview

   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.

   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.

   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.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * db_mysql.
     * tm.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. db_url (str)
   3.2. db_mode(integer)
   3.3. rooms_table (str)
   3.4. members_table (str)
   3.5. hash_size (integer)
   3.6. imc_cmd_start_char (str)
   3.7. outbound_proxy (str)
   3.8. extra_hdrs (str)
   3.9. create_on_join (integer)
   3.10. check_on_create (integer)

3.1. db_url (str)

   The database url.

   The default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.

   Example 1.1. Set db_url parameter
...
modparam("imc", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. db_mode(integer)

   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.

   Default value is “0”

   Example 1.2. Set db_mode parameter
...
modparam("imc", "db_mode", 2)
...

3.3. rooms_table (str)

   The name of the table storing IMC rooms.

   The default value is "imc_rooms".

   Example 1.3. Set rooms_table parameter
...
modparam("imc", "rooms_table", "rooms")
...

3.4. members_table (str)

   The name of the table storing IMC members.

   The default value is "imc_members".

   Example 1.4. Set members_table parameter
...
modparam("imc", "members_table", "members")
...

3.5. 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 (resulting in hash size 16).

   Example 1.5. Set hash_size parameter
...
modparam("imc", "hash_size", 8)
...

3.6. imc_cmd_start_char (str)

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

   The default value is "#".

   Example 1.6. Set imc_cmd_start_char parameter
...
modparam("imc", "imc_cmd_start_char", "#")
...

3.7. outbound_proxy (str)

   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.

   Default value is NULL.

   Example 1.7. Set outbound_proxy parameter
...
modparam("imc", "outbound_proxy", "sip:kamailio.org;transport=tcp")
...

3.8. extra_hdrs (str)

   Extra headers (each ending with \r\n) to be added in messages sent out
   from imc server.

   Default value is NULL.

   Example 1.8. Set extra_hdrs parameter
...
modparam("imc", "extra_hdrs", "P-Flags: 3\r\n")
...

3.9. create_on_join (integer)

   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.

   The default value is 1.

   Example 1.9. Set create_on_join parameter
...
modparam("imc", "create_on_join", 0)
...

3.10. check_on_create (integer)

   If set to 1, the chat server will report an error if the user attempts
   to create a room that already exists.

   The default value is 0.

   Example 1.10. Set check_on_create parameter
...
modparam("imc", "check_on_create", 1)
...

4. Functions

   4.1. imc_manager()
   4.2. imc_room_active(room)
   4.3. imc_room_member(room, user)

4.1.  imc_manager()

   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.

   This function can be used from REQUEST_ROUTE. See command description
   for error codes returned by this function.

   Example 1.11. 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@"))
{
    if(imc_manager())
        sl_send_reply("200", "ok");
    else
        sl_send_reply("500", "command error");
    exit;
}
...

4.2.  imc_room_active(room)

   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.

   This function can be used from ANY_ROUTE.

   Example 1.12. Usage of imc_room_active() function
...
    if(imc_room_active("sip:chat-sip@$fd")) {
        ...
    }
...

4.3.  imc_room_member(room, user)

   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.

   This function can be used from ANY_ROUTE.

   Example 1.13. Usage of imc_room_member() function
...
    if(imc_room_member("sip:chat-sip@$fd", "sip:$rU@$rd")) {
        ...
    }
...

5. RPC Commands

   5.1. imc.list_rooms
   5.2. imc.list_members

5.1. imc.list_rooms

   Lists of the IM Conferencing rooms.

   Name: imc.list_rooms

   Parameters: none

   RPC Command Format:
...
kamcmd imc_list_rooms
...

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

   RPC Command Format:
...
kamcmd imc_list_members _room_
...

6. Statistics

   6.1. active_rooms

6.1.  active_rooms

   Number of active IM Conferencing rooms.

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

8. Installation

   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 SQL script in the database
   directories in the kamailio/scripts folder as template. You can also
   find the complete database documentation on the project webpage,
   https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
