name mode size
..
doc 040000
Makefile 100644 363B
README 100644 9.9kB
imc.c 100644 18.86kB
imc.h 100644 1.14kB
imc_cmd.c 100644 30.12kB
imc_cmd.h 100644 4.04kB
imc_mng.c 100644 9.07kB
imc_mng.h 100644 2.42kB
README
imc Module Anca-Maria Vamanu Voice Sistem SRL Daniel-Constantin Mierla <miconda@gmail.com> Stefan Popescu Edited by Anca-Maria Vamanu 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. rooms_table (str) 3.3. members_table (str) 3.4. hash_size (integer) 3.5. imc_cmd_start_char (str) 3.6. outbound_proxy (str) 3.7. extra_hdrs (str) 4. Functions 4.1. imc_manager() 5. MI 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 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. Set outbound_proxy parameter 1.7. Set extra_hdrs parameter 1.8. Usage of imc_manager() function 1.9. 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. rooms_table (str) 3.3. members_table (str) 3.4. hash_size (integer) 3.5. imc_cmd_start_char (str) 3.6. outbound_proxy (str) 3.7. extra_hdrs (str) 4. Functions 4.1. imc_manager() 5. MI 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. It follows the architecture of IRC channels, you can send commands embedded in MESSAGE body, because there are just a few 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 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. rooms_table (str) 3.3. members_table (str) 3.4. hash_size (integer) 3.5. imc_cmd_start_char (str) 3.6. outbound_proxy (str) 3.7. extra_hdrs (str) 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. 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") ... 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", "members_table", "members") ... 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) ... 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", "#") ... 3.6. 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.6. Set outbound_proxy parameter ... modparam("imc", "outbound_proxy", "sip:kamailio.org;transport=tcp") ... 3.7. 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.7. Set extra_hdrs parameter ... modparam("imc", "extra_hdrs", "P-Flags: 3\r\n") ... 4. Functions 4.1. imc_manager() 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. See command description for error codes returned by this function. Example 1.8. 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; } ... 5. MI 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 MI FIFO Command Format: :imc_list_rooms:_reply_fifo_file_ _empty_line_ 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_ 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.9. 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.deny -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.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 -error case: return codes: -90 -- -99 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 -error case: return codes: -110 -- -119 9.list -list members in a room -error case: return codes: -100 -- -109 ... 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, http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.