mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
393 lines
9.7 KiB
393 lines
9.7 KiB
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.
|