kamailio/modules/purple

Purple Module

Eric Ptak

   Atos Worldline
   <eric.ptak@atosorigin.com>

Edited by

Eric Ptak

   <eric.ptak@atosorigin.com>

   Copyright © 2008 Atos Worldline
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Database
        4. Parameters

              4.1. db_url (str)
              4.2. db_table (str)
              4.3. httpProxy_host (str)
              4.4. httpProxy_port (int)

        5. Functions

              5.1. purple_send_message()
              5.2. purple_handle_publish()
              5.3. purple_handle_subscribe()

   List of Examples

   1.1. Database table description
   1.2. Database sample records
   1.3. MySQL create script
   1.4. Set db_url parameter
   1.5. Set db_table parameter
   1.6. Set httpProxy_host parameter
   1.7. Set httpProxy_port parameter
   1.8. purple_send_message usage
   1.9. purple_handle_publish usage
   1.10. purple_handle_subscribe usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Database
   4. Parameters

        4.1. db_url (str)
        4.2. db_table (str)
        4.3. httpProxy_host (str)
        4.4. httpProxy_port (int)

   5. Functions

        5.1. purple_send_message()
        5.2. purple_handle_publish()
        5.3. purple_handle_subscribe()

1. Overview

   Purple module is a multi-protocol instant-messaging gateway module
   which use libpurple, the library that Pidgin (ex-gaim) is based on.

   This plugin was written as a proof of concept gateway between SIP and
   MSN/Live networks. As libpurple is written to code multi-protocol
   graphic IM clients, it provides a high level API in order to manipulate
   accounts, contacts, contacts lists, conversations and more.

   This module provides a multi-protocol IM/Presence client running inside
   Kamailio with an account for each protocol used by each SIP user.
   libpurple is designed for a graphic client for only one user.

   It's no really adapted to a production environment with a huge user
   count but can be used in order to demonstrate the concept or in a SOHO
   environment.

   By default, there's some undefined symbol errors with libpurple shared
   object when using it inside Kamailio. To solve it, you have to force
   preload of the library by setting up LD_PRELOAD environment variable.

   Before starting Kamailio use (adapt the path to your environment):
                export LD_PRELOAD=$LD_PRELOAD:/usr/local/lib/libpurple.so

   Limitations: doesn't implement authorization requests from external
   accounts to SIP.

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:
     * presence*.
     * pua.
     * database driver module (db_mysql, ...).

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libpurple, e.g. from pidgin 2.5.2.

3. Database

   The database is used to map SIP URIs with external accounts (eg. MSN).

   Example 1.1. Database table description
...
+----------+------------------+------+-----+---------+----------------+
| Field    | Type             | Null | Key | Default | Extra          |
+----------+------------------+------+-----+---------+----------------+
| id       | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| sip_user | varchar(128)     | NO   |     | NULL    |                |
| ext_user | varchar(128)     | NO   |     | NULL    |                |
| ext_prot | varchar(16)      | NO   |     | NULL    |                |
| ext_pass | varchar(64)      | YES  |     | NULL    |                |
+----------+------------------+------+-----+---------+----------------+
...

   The meaning of columns:
     * sip_user: user's SIP URI.
     * ext_user: user's external account login.
     * ext_prot: purple plugin id to use, except for gtalk.
     * ext_pass: user's external account password.

   Example 1.2. Database sample records
...
+----+------------------+-----------------+----------------+----------+
| id | sip_user         | ext_user        | ext_prot       | ext_pass |
+----+------------------+-----------------+----------------+----------+
|  1 | sip:alice@domain | alice@live.com  | prpl-msn-pecan | password |
|  2 | sip:bob@domain   | bob@live.com    | prpl-msn-pecan | password |
|  3 | sip:alice@domain | alice@gmail.com | gtalk          | password |
|  4 | sip:bob@domain   | bob@gmail.com   | gtalk          | password |
+----+------------------+-----------------+----------------+----------+
...

   Example 1.3. MySQL create script
...
CREATE TABLE purplemap (
  id INT UNSIGNED PRIMARY KEY NOT NULL AUTO_INCREMENT,
  sip_user VARCHAR(128) NOT NULL,
  ext_user VARCHAR(128) NOT NULL,
  ext_prot VARCHAR(16) NOT NULL,
  ext_pass VARCHAR(64)
);
...

4. Parameters

   4.1. db_url (str)
   4.2. db_table (str)
   4.3. httpProxy_host (str)
   4.4. httpProxy_port (int)

4.1. db_url (str)

   The URL to connect to database.

   Default value is “mysql://openserro:openserro@localhost/openser”.

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

4.2. db_table (str)

   Database table name.

   Default value is purplemap.

   Example 1.5. Set db_table parameter
...
modparam("purple", "db_table", "purplemap")
...

4.3. httpProxy_host (str)

   Address of HTTP proxy.

   Default value is NULL.

   Example 1.6. Set httpProxy_host parameter
...
modparam("purple", "httpProxy_host", "10.26.52.12")
...

4.4. httpProxy_port (int)

   Port of HTTP proxy.

   Default value is 0.

   Example 1.7. Set httpProxy_port parameter
...
modparam("purple", "httpProxy_port", 3128)
...

5. Functions

   5.1. purple_send_message()
   5.2. purple_handle_publish()
   5.3. purple_handle_subscribe()

5.1.  purple_send_message()

   Send message to a purple destination.

   This function can be used from REQUEST_ROUTE.

   Example 1.8. purple_send_message usage
...
if (is_method("MESSAGE")) {
    xlog("MESSAGE $ru from [$fu] to [$tu]\n");
    if (uri !~ "sip:.+@.+;proto=.+") {
        purple_send_message();
        sl_send_reply("202", "Accepted");
    }
}
...

5.2.  purple_handle_publish()

   Handle PUBLISH to a purple destination.

   This function can be used from REQUEST_ROUTE.

   Example 1.9. purple_handle_publish usage
...
if(is_method("PUBLISH")) {
    xlog("PUBLISH $ru from [$fu] to [$tu]\n");
    if (uri !~ "sip:.+@.+;proto=.+")
        purple_handle_publish();
}
...

5.3.  purple_handle_subscribe()

   Handle SUBSCRIBE to a purple destination.

   This function can be used from REQUEST_ROUTE.

   Example 1.10. purple_handle_subscribe usage
...
if(is_method("SUBSCRIBE")) {
    xlog("SUBSCRIBE $ru from [$fu] to [$tu]\n");
    if ($hdr(Event) == "presence")
        purple_handle_subscribe("$ruri", "$hdr(Expires)");
}
...