1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;
]>
<chapter>
<title>&adminguide;</title>
<section>
<title>Overview</title>
<para>
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.
</para>
</section>
<section>
<title>Dependencies</title>
<section>
<title>&kamailio; Modules</title>
<para>
The module depends on the following modules (in the other words
the listed modules must be loaded before this module):
</para>
<itemizedlist>
<listitem>
<para><emphasis>none</emphasis></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>External Libraries or Applications</title>
<para>
The following libraries or applications must be installed
before running &kamailio; with this module loaded:
</para>
<itemizedlist>
<listitem>
<para><emphasis>none</emphasis></para>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Parameters</title>
<section>
<title><varname>db_url</varname> (string)</title>
<para>
The URL for the database connection.
</para>
<para>
<emphasis>
Default value is <quote>&defaultrodb;</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>db_url</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("matrix", "db_url", "&defaultrodb;")
...
</programlisting>
</example>
</section>
<section>
<title><varname>matrix_table</varname> (string)</title>
<para>
The name of the table containing the matrix data.
</para>
<para>
<emphasis>
Default value is <quote>matrix</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>matrix_table</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("matrix", "matrix_table", "matrix")
...
</programlisting>
</example>
</section>
<section>
<title><varname>matrix_first_col</varname> (string)</title>
<para>
The name of the column containing the first row in the matrix.
</para>
<para>
<emphasis>
Default value is <quote>first</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>matrix_first_col</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("matrix", "matrix_first_col", "first")
...
</programlisting>
</example>
</section>
<section>
<title><varname>matrix_second_col</varname> (string)</title>
<para>
The name of the column containing the second row in the matrix.
</para>
<para>
<emphasis>
Default value is <quote>second</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>matrix_second_col</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("matrix", "matrix_second_col", "second")
...
</programlisting>
</example>
</section>
<section>
<title><varname>matrix_res_col</varname> (string)</title>
<para>
The name of the column containing the result ID to be used.
</para>
<para>
<emphasis>
Default value is <quote>res</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>matrix_res_col</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("matrix", "matrix_res_col", "res")
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Functions</title>
<section>
<title>
<function moreinfo="none">matrix (string first, string second, string dstavp)</function>
</title>
<para>
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.
</para>
<example>
<title><function>matrix</function> usage</title>
<programlisting format="linespecific">
...
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");
...
</programlisting>
</example>
</section>
</section>
<section>
<title><acronym>MI</acronym> Commands</title>
<section>
<title>
<function moreinfo="none">reload_matrix</function>
</title>
<para>
Reloads the internal matrix representation from the database.
This is necessary after entries in the database have been changed.
</para>
<example>
<title><function>reload_matrix</function> usage</title>
<programlisting format="linespecific">
...
kamctl fifo reload_matrix
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Installation and Running</title>
<section>
<title>Database setup</title>
<para>
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
<acronym>SQL</acronym> 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, &kamailiodbdocs;.
</para>
<example>
<title>Example database content - matrix table</title>
<programlisting format="linespecific">
...
+---------+--------------+---------+
| first | second | res |
+---------+--------------+---------+
| 1 | 9 | 2 |
| 2 | 69 | 1 |
| 2 | 13 | 3 |
+---------+--------------+---------+
...
</programlisting>
</example>
</section>
</section>
</chapter>
|
