Debian Codegraph @

src/modules/mtree/README

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