# &adminguide;

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

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- presence*.

- pua.

- database driver module (db_mysql, ...).

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

## Database

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

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

### 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 |
    +----+------------------+-----------------+----------------+----------+
    ...

### 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)
    );
    ...

## Parameters

### `db_url` (str)

The URL to connect to database.

Default value is &defaultrodb;.

#### Set `db_url` parameter

    ...
    modparam("purple", "db_url", "&exampledb;")
    ...

### `db_table` (str)

Database table name.

Default value is purplemap.

#### Set `db_table` parameter

    ...
    modparam("purple", "db_table", "purplemap")
    ...

### `httpProxy_host` (str)

Address of HTTP proxy.

Default value is NULL.

#### Set `httpProxy_host` parameter

    ...
    modparam("purple", "httpProxy_host", "10.26.52.12")
    ...

### `httpProxy_port` (int)

Port of HTTP proxy.

Default value is 0.

#### Set `httpProxy_port` parameter

    ...
    modparam("purple", "httpProxy_port", 3128)
    ...

## Functions

### `purple_send_message()`

Send message to a purple destination.

This function can be used from REQUEST_ROUTE.

#### `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");
        }
    }
    ...

### `purple_handle_publish()`

Handle PUBLISH to a purple destination.

This function can be used from REQUEST_ROUTE.

#### `purple_handle_publish` usage

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

### `purple_handle_subscribe()`

Handle SUBSCRIBE to a purple destination.

This function can be used from REQUEST_ROUTE.

#### `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)");
    }
    ...