imc Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS 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.3.6. outbound_proxy (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. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

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. Usage of imc_manager() function
1.8. List of commands

Chapter 1. Admin 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. OpenSIPS 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 OpenSIPS with this module loaded:

  • None.

1.3. Exported Parameters

1.3.1. db_url (str)

The database url.

The default value is mysql://opensips:opensipsrw@localhost/opensips.

Example 1.1. Set db_url parameter

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

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.3.6. outbound_proxy (str)

The SIP address used as next hop when sending the message. Very useful when using OpenSIPS with a domain name not in DNS, or when using a separate OpenSIPS 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:opensips.org;transport=tcp")
...

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.7. Usage of imc_manager() function

...
# the rooms will be named chat-xyz to avoid overlapping
# with usernames
if(is_method("MESSAGE)
        && ($ru=~ "sip:chat-[0-9]+@" || ($ru=~ "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.8. 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@opensips.org,
      or just, #join, sent to sip:chat-000@opensips.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@opensips.org sip:chat-000@opensips.org
    or  #invite john@opensips.org sent to sip:chat-000@opensips.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@opensips.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@opensips.org, sent to sip:chat-000@opensips.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 OpenSIPS 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 opensips/scripts folder as template. You can also find the complete database documentation on the project webpage, https://opensips.org/docs/db/db-schema-devel.html.

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Daniel-Constantin Mierla (@miconda)441216041007
2. Bogdan-Andrei Iancu (@bogdan-iancu)4128306547
3. Anca Vamanu305301416
4. Razvan Crainea (@razvancrainea)15132835
5. Liviu Chircu (@liviuchircu)1293459
6. Henning Westerholt (@henningw)10776105
7. Elena-Ramona Modroiu42685
8. Vlad Patrascu (@rvlad-patrascu)4221
9. John Riordan31105
10. Sergio Gutierrez3152

All remaining contributors: Konstantin Bokarius, Edson Gellert Schubert, Walter Doekes (@wdoekes).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Oct 2006 - Jun 2020
2. Razvan Crainea (@razvancrainea)Sep 2011 - Sep 2019
3. Liviu Chircu (@liviuchircu)Mar 2014 - Jun 2018
4. Vlad Patrascu (@rvlad-patrascu)May 2017 - Jul 2017
5. Walter Doekes (@wdoekes)May 2014 - May 2014
6. John RiordanMay 2009 - May 2009
7. Sergio GutierrezNov 2008 - Nov 2008
8. Daniel-Constantin Mierla (@miconda)Nov 2006 - Mar 2008
9. Konstantin BokariusMar 2008 - Mar 2008
10. Edson Gellert SchubertFeb 2008 - Feb 2008

All remaining contributors: Henning Westerholt (@henningw), Anca Vamanu, Elena-Ramona Modroiu.

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Razvan Crainea (@razvancrainea), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Anca Vamanu, Henning Westerholt (@henningw), Elena-Ramona Modroiu.

doc copyrights:

Copyright © 2006-2008 Voice Sistem SRL