modules: readme files regenerated - mtree ... [skip ci]
[sip-router] / src / modules / mtree / README
1 mtree Module
2
3 Daniel-Constantin Mierla
4
5    asipto.com
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13 Juha Heinanen
14
15    tutpro.com
16
17 Edited by
18
19 Juha Heinanen
20
21    <jh@tutpro.com>
22
23    Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
24
25    Copyright © 2011 Juha Heinanen
26      __________________________________________________________________
27
28    Table of Contents
29
30    1. Admin Guide
31
32         1. Overview
33         2. Dependencies
34
35               2.1. Kamailio Modules
36               2.2. External Libraries or Applications
37
38         3. Parameters
39
40               3.1. db_url (string)
41               3.2. db_table (string)
42               3.3. mtree (string)
43               3.4. tname_column (string)
44               3.5. tprefix_column (string)
45               3.6. tvalue_column (string)
46               3.7. fetch_rows (integer)
47               3.8. char_list (string)
48               3.9. pv_value (string)
49               3.10. pv_values (string)
50               3.11. mt_tree_type (integer)
51               3.12. mt_ignore_duplicates (integer)
52               3.13. mt_allow_duplicates (integer)
53
54         4. Functions
55
56               4.1. mt_match(mtree, pv, mode)
57
58         5. RPC Commands
59
60               5.1. mtree.list
61               5.2. mtree.summary
62               5.3. mtree.reload
63               5.4. mtree.match
64
65    2. Developer Guide
66
67         1. Available Functions
68
69               1.1. mt_load_api(api)
70               1.2. mt_match(msg, mtree, value, mode)
71
72    List of Examples
73
74    1.1. Set db_url parameter
75    1.2. Set db_table parameter
76    1.3. Set mtree parameter
77    1.4. Set tname_column parameter
78    1.5. Set tprefix_column parameter
79    1.6. Set tvalue_column parameter
80    1.7. Set fetch_rows parameter
81    1.8. Set char_list parameter
82    1.9. Set pv_value parameter
83    1.10. Set pv_values parameter
84    1.11. Set mt_tree_type parameter
85    1.12. Set mt_ignore_duplicates parameter
86    1.13. Set mt_allow_duplicates parameter
87    1.14. mt_match usage
88    1.15. mtree.list rpc usage
89
90 Chapter 1. Admin Guide
91
92    Table of Contents
93
94    1. Overview
95    2. Dependencies
96
97         2.1. Kamailio Modules
98         2.2. External Libraries or Applications
99
100    3. Parameters
101
102         3.1. db_url (string)
103         3.2. db_table (string)
104         3.3. mtree (string)
105         3.4. tname_column (string)
106         3.5. tprefix_column (string)
107         3.6. tvalue_column (string)
108         3.7. fetch_rows (integer)
109         3.8. char_list (string)
110         3.9. pv_value (string)
111         3.10. pv_values (string)
112         3.11. mt_tree_type (integer)
113         3.12. mt_ignore_duplicates (integer)
114         3.13. mt_allow_duplicates (integer)
115
116    4. Functions
117
118         4.1. mt_match(mtree, pv, mode)
119
120    5. RPC Commands
121
122         5.1. mtree.list
123         5.2. mtree.summary
124         5.3. mtree.reload
125         5.4. mtree.match
126
127 1. Overview
128
129    This module loads (prefix, value) records from database and indexes
130    them in a named memory tree. Name of the tree is specified for each
131    record or as module parameter.
132
133    It exports to configuration file functions to match against in-memory
134    trees and return the values (raw or precompiled) associated with
135    matched prefixes.
136
137    The maximum size of the prefix is limited internally to 63, database
138    table definition may enforce lower maximum size.
139
140 2. Dependencies
141
142    2.1. Kamailio Modules
143    2.2. External Libraries or Applications
144
145 2.1. Kamailio Modules
146
147    The following modules must be loaded before this module:
148      * A Kamailio database module (e.g., mysql).
149
150 2.2. External Libraries or Applications
151
152    The following libraries or applications must be installed before
153    running Kamailio with this module loaded:
154      * None.
155
156 3. Parameters
157
158    3.1. db_url (string)
159    3.2. db_table (string)
160    3.3. mtree (string)
161    3.4. tname_column (string)
162    3.5. tprefix_column (string)
163    3.6. tvalue_column (string)
164    3.7. fetch_rows (integer)
165    3.8. char_list (string)
166    3.9. pv_value (string)
167    3.10. pv_values (string)
168    3.11. mt_tree_type (integer)
169    3.12. mt_ignore_duplicates (integer)
170    3.13. mt_allow_duplicates (integer)
171
172 3.1. db_url (string)
173
174    URL of the database server to be used.
175
176    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
177
178    Example 1.1. Set db_url parameter
179 ...
180 modparam("mtree", "db_url", "dbdriver://username:password@dbhost/dbname")
181 ...
182
183 3.2. db_table (string)
184
185    Name of database table where data for many trees is stored. It is
186    ignored if a 'mtree' parameter is defined. The SQL scripts creates a
187    table named 'mtrees' that can be used for this parameter.
188
189    Default value is “” (no table name).
190
191    Example 1.2. Set db_table parameter
192 ...
193 modparam("mtree", "db_table", "mtrees")
194 ...
195
196 3.3. mtree (string)
197
198    Definition of memory tree with using a prameters format string. The
199    parameter names can be:
200      * name - the name of the tree to be used for referencing inside
201        configuration file.
202      * dbtable - the name of the database table from where to load the
203        records stored in the tree.
204      * cols - the column names of the database table. They must be
205        enclosed in quotes in order to form a valid SIP parameter value and
206        be separated by comma. The first column corresponds to tprefix.
207        When specified, there must be at least two columns. If this
208        attribute is not specified, then the global module parameters for
209        tprefix and tvalue are used. If more than one value columns are
210        specified, the tree will pack the column values in a comma
211        separated string, which will be associated with the prefix (string
212        transformation {s.select,...) can be used in configuration file to
213        extract a specific column value).
214      * type - the type of tree elements (0 = string, 2 = integer). It is
215        valid only when the (tprefix, tvalue) pairs are loaded (not for
216        muti-column values).
217      * multi - tells if dbtable can contain more than one tree (0 = one
218        tree, 1 = more than one tree identified by tname column). It is
219        valid only when the (tprefix, tvalue) pairs are loaded (not for
220        muti-column values).
221
222    This parameter can be set many times to add more trees in memory.
223
224    Default value is “none”.
225
226    Example 1.3. Set mtree parameter
227 ...
228 modparam("mtree", "mtree", "name=mytree1;dbtable=routes1;type=0")
229 modparam("mtree", "mtree", "name=mytree2;dbtable=routes2;type=0;multi=1")
230 modparam("mtree", "mtree",
231     "name=mytree1;dbtable=routes1;cols='key1,val1,val2,val3'")
232 ...
233
234 3.4. tname_column (string)
235
236    Name of 'tname' column.
237
238    Default value is “tname”.
239
240    Example 1.4. Set tname_column parameter
241 ...
242 modparam("mtree", "tname_column", "name")
243 ...
244
245 3.5. tprefix_column (string)
246
247    Name of 'tprefix' column.
248
249    Default value is “tprefix”.
250
251    Example 1.5. Set tprefix_column parameter
252 ...
253 modparam("mtree", "tprefix_column", "prefix")
254 ...
255
256 3.6. tvalue_column (string)
257
258    Name of 'tvalue' column.
259
260    Default value is “tvalue”.
261
262    Example 1.6. Set tvalue_column parameter
263 ...
264 modparam("mtree", "tvalue_column", "ipaddr")
265 ...
266
267 3.7. fetch_rows (integer)
268
269    Number of rows to be loaded in one step from database.
270
271    Default value is 1000.
272
273    Example 1.7. Set fetch_rows parameter
274 ...
275 modparam("mtree", "fetch_rows", 4000)
276 ...
277
278 3.8. char_list (string)
279
280    The list with characters allowed in prefix.
281
282    Default value is “0123456789”.
283
284    Example 1.8. Set char_list parameter
285 ...
286 modparam("mtree", "char_list", "0123456789*+")
287 ...
288
289 3.9. pv_value (string)
290
291    The PV spec where to store the matched value. It can be any writable
292    PV.
293
294    Default value is “$avp(s:tvalue)”.
295
296    Example 1.9. Set pv_value parameter
297 ...
298 modparam("mtree", "pv_value", "$var(mtval)")
299 ...
300
301 3.10. pv_values (string)
302
303    The AVP where to store the matched values when mtree is of type 0 or 2
304    and mode of mt_match() call has value 2.
305
306    Default value is “$avp(s:tvalues)”.
307
308    Example 1.10. Set pv_values parameter
309 ...
310 modparam("mtree", "pv_values", "$avp(mtvals)")
311 ...
312
313 3.11. mt_tree_type (integer)
314
315    Default payload type for trees data stored in 'db_table'. Documented
316    values are 0 for string payloads and 2 for integer payloads.
317
318    Default value is 0.
319
320    Example 1.11. Set mt_tree_type parameter
321 ...
322 modparam("mtree", "mt_tree_type", 2)
323 ...
324
325 3.12. mt_ignore_duplicates (integer)
326
327    Ignore duplicated prefixes when loading data.
328
329    Default value is 0.
330
331    Example 1.12. Set mt_ignore_duplicates parameter
332 ...
333 modparam("mtree", "mt_ignore_duplicates", 1)
334 ...
335
336 3.13. mt_allow_duplicates (integer)
337
338    Allow duplicate prefixes when loading data.
339
340    Default value is 0.
341
342    Example 1.13. Set mt_allow_duplicates parameter
343 ...
344 modparam("mtree", "mt_allow_duplicates", 1)
345 ...
346
347 4. Functions
348
349    4.1. mt_match(mtree, pv, mode)
350
351 4.1.  mt_match(mtree, pv, mode)
352
353    Match 'pv' value against 'mtree'. If 'mtree' type is 0 or 2 and value
354    of 'mode' is NOT 2, sets a value of the longest matching prefix to
355    pseudo variable specified by pv_value parameter. If 'mtree' type is 0
356    or 2 and value of 'mode' is 2, sets values of all matching prefixes to
357    avp specified by pv_values parameter so that a value of longest
358    matching prefix is in avp index 0. Parameter 'mode' can be an integer
359    constant or a pseudo variable with integer value.
360
361    Returns 1 if match succeeded and -1 otherwise.
362
363    Example 1.14. mt_match usage
364 ...
365 mt_match("mytree", "$rU", "0");
366 ...
367
368 5. RPC Commands
369
370    5.1. mtree.list
371    5.2. mtree.summary
372    5.3. mtree.reload
373    5.4. mtree.match
374
375 5.1.  mtree.list
376
377    List content of one or all trees.
378
379    Name: mtree.list
380
381    Parameters:
382      * _mtree_ : name of tree to list (optional).
383
384    Example 1.15. mtree.list rpc usage
385 ...
386 kamcmd mtree.list
387 kamcmd mtree.list mytree
388 ...
389
390 5.2.  mtree.summary
391
392    List usage summary for all trees or for the tree whose name is given as
393    parameter.
394
395    Parameters:
396      * _mtree_ - (optional) the name of the tree.
397
398 5.3.  mtree.reload
399
400    Reload mtree from database to memory.
401
402    Parameters:
403      * _mtree_
404        - name of mtree or empty string meaning all mtrees
405
406 5.4.  mtree.match
407
408    Match prefix value against mtree
409
410    Parameters:
411      * _mtree_
412        - name of mtree
413      * _prefix_
414        - match prefix
415      * _mode_
416        - matching mode
417
418 Chapter 2. Developer Guide
419
420    Table of Contents
421
422    1. Available Functions
423
424         1.1. mt_load_api(api)
425         1.2. mt_match(msg, mtree, value, mode)
426
427 1. Available Functions
428
429    1.1. mt_load_api(api)
430    1.2. mt_match(msg, mtree, value, mode)
431
432 1.1.  mt_load_api(api)
433
434    The function imports all API functions that are exported by the mtree
435    module (see sections below).
436
437    Meaning of the parameters is as follows:
438      * mtree_api_t* api - mtree API
439
440 1.2.  mt_match(msg, mtree, value, mode)
441
442    Match 'value' against 'mtree' using 'mode' (see mt_match function Admin
443    Guide documentation).
444
445    Meaning of the parameters is as follows:
446      * sip_msg_t *msg - SIP Request
447      * str *mtree - Name of mtree
448      * str *value - Value to match
449      * int mode - Match mode