kamailio/modules/matrix

matrix Module

Hardy Kahl

   1&1 Internet AG

Edited by

Henning Westerholt

   1&1 Internet AG
   <henning.westerholt@1und1.de>

   Copyright © 2008 1&1 Internet AG
   Revision History
   Revision $Revision: 4863 $ $Date: 2008-09-05 13:11:33 +0200 (Fri, 05
                              Sep 2008) $
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Exported Parameters

              3.1. db_url (string)
              3.2. matrix_table (string)
              3.3. matrix_first_col (string)
              3.4. matrix_second_col (string)
              3.5. matrix_res_col (string)

        4. Exported Functions

              4.1. matrix (string first, string second, string dstavp)

        5. MI Commands

              5.1. reload_matrix

        6. Installation and Running

              6.1. Database setup

   2. Module parameter for database access.

        1. db_url (String)
        2. matrix_table (String)
        3. matrix_first_col (string)
        4. matrix_second_col (string)
        5. matrix_res_col (string)

   List of Examples

   1.1. Set db_url parameter
   1.2. Set matrix_table parameter
   1.3. Set matrix_first_col parameter
   1.4. Set matrix_second_col parameter
   1.5. Set matrix_res_col parameter
   1.6. matrix usage
   1.7. reload_matrix usage
   1.8. Example database content - matrix table
   2.1. Set db_url parameter
   2.2. Set matrix_table parameter
   2.3. Set matrix_first_col parameter
   2.4. Set matrix_second_col parameter
   2.5. Set matrix_res_col parameter

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Exported Parameters

        3.1. db_url (string)
        3.2. matrix_table (string)
        3.3. matrix_first_col (string)
        3.4. matrix_second_col (string)
        3.5. matrix_res_col (string)

   4. Exported Functions

        4.1. matrix (string first, string second, string dstavp)

   5. MI Commands

        5.1. reload_matrix

   6. Installation and Running

        6.1. Database setup

1. Overview

   The matrix module can be used to arbitrary lookup operations over an
   array. One possible usecase is to define which routing tree should be
   used depending on the preferred carrier of the source number and the
   carrier id of the destination number. The matrix cells are read from a
   database and can be reloaded using a FIFO command. You do not have to
   define all matrix cells. The matrix can be sparse. Currently, the
   implementation is designed for a small number of columns (they are
   stored in a linked list). This does not scale well and has to be
   replaced by more an efficient data data structure when needed.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The module depends on the following modules (in the other words the
   listed modules must be loaded before this module):
     * none

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * none

3. Exported Parameters

   3.1. db_url (string)
   3.2. matrix_table (string)
   3.3. matrix_first_col (string)
   3.4. matrix_second_col (string)
   3.5. matrix_res_col (string)

3.1. db_url (string)

   The URL for the database connection.

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

   Example 1.1. Set db_url parameter
...
modparam("matrix", "db_url", "mysql://openserro:openserro@localhost/openser")
...

3.2. matrix_table (string)

   The name of the table containing the matrix data.

   Default value is “matrix”.

   Example 1.2. Set matrix_table parameter
...
modparam("matrix", "matrix_table", "matrix")
...

3.3. matrix_first_col (string)

   The name of the column containing the first row in the matrix.

   Default value is “first”.

   Example 1.3. Set matrix_first_col parameter
...
modparam("matrix", "matrix_first_col", "first")
...

3.4. matrix_second_col (string)

   The name of the column containing the second row in the matrix.

   Default value is “second”.

   Example 1.4. Set matrix_second_col parameter
...
modparam("matrix", "matrix_second_col", "second")
...

3.5. matrix_res_col (string)

   The name of the column containing the result ID to be used.

   Default value is “res”.

   Example 1.5. Set matrix_res_col parameter
...
modparam("matrix", "matrix_res_col", "res")
...

4. Exported Functions

   4.1. matrix (string first, string second, string dstavp)

4.1.  matrix (string first, string second, string dstavp)

   Looks up the desired result ID in the matrix for the given column and
   value and saves the result in dstavp. Returns false if the cell is not
   defined or when an error occured. Pseudo-variables or AVPs can be used
   for first and second.

   Example 1.6. matrix usage
...
if (!matrix("$avp(first)", "$avp(second)", "$avp(route_tree)"))
  $avp(route_tree) = $avp(frst); # default routing as defined for source number
}
cr_route("$avp(route_tree)", "$rd", "$rU", "$rU", "call_id");
...

5. MI Commands

   5.1. reload_matrix

5.1.  reload_matrix

   Reloads the internal matrix representation from the database. This is
   necessary after entries in the database have been changed.

   Example 1.7. reload_matrix usage
...
kamctl fifo reload_matrix
...

6. Installation and Running

   6.1. Database setup

6.1. Database setup

   Before running Kamailio with matrix, you have to setup the database
   table where the module will read the matrix data. For that, if the
   table was not created by the installation script or you choose to
   install everything by yourself you can use the matrix-create.sql SQL
   script in the database directories in the kamailio/scripts folder as
   template. Database, table, and column names can be set with module
   parameters so they can be changed. You can also find the complete
   database documentation on the project webpage,
   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

   Example 1.8. Example database content - matrix table
...
+---------+--------------+---------+
|  first  |    second    |   res   |
+---------+--------------+---------+
|       1 |            9 |       2 |
|       2 |           69 |       1 |
|       2 |           13 |       3 |
+---------+--------------+---------+
...

Chapter 2. Module parameter for database access.

   Table of Contents

   1. db_url (String)
   2. matrix_table (String)
   3. matrix_first_col (string)
   4. matrix_second_col (string)
   5. matrix_res_col (string)

1. db_url (String)

   URL to the database containing the data.

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

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

2. matrix_table (String)

   Name of the matrix table for the matrix module.

   Default value is “matrix”.

   Example 2.2. Set matrix_table parameter
...
modparam("matrix", "matrix_table", "matrix")
...

3. matrix_first_col (string)

   The row index in the matrix

   Example 2.3. Set matrix_first_col parameter
...
modparam("matrix", "matrix_first_col", "first")
...

4. matrix_second_col (string)

   The column index in the matrix

   Example 2.4. Set matrix_second_col parameter
...
modparam("matrix", "matrix_second_col", "second")
...

5. matrix_res_col (string)

   The resource contained in the matrix

   Example 2.5. Set matrix_res_col parameter
...
modparam("matrix", "matrix_res_col", "res")
...