git.sip-router.org Git - sip-router/blob - 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