From 399c95171db003dc56b0f870c8dacd3922ac45c3 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Sun, 23 Jan 2022 20:01:22 +0100 Subject: [PATCH] modules: readme files regenerated - htable ... [skip ci] --- src/modules/htable/README | 1303 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1303 insertions(+) diff --git a/src/modules/htable/README b/src/modules/htable/README index 8b137891791..0675d64fe67 100644 --- a/src/modules/htable/README +++ b/src/modules/htable/README @@ -1 +1,1304 @@ +HTable Module +Elena-Ramona Modroiu + + asipto.com + + +Edited by + +Elena-Ramona Modroiu + + + +Alex Balashov + + + +Ovidiu Sas + + + + Copyright © 2008-2011 http://www.asipto.com + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + 2.3. Loading from database + + 3. Parameters + + 3.1. htable (str) + 3.2. db_url (str) + 3.3. key_name_column (str) + 3.4. key_type_column (str) + 3.5. value_type_column (str) + 3.6. key_value_column (str) + 3.7. expires_column (str) + 3.8. array_size_suffix (str) + 3.9. fetch_rows (integer) + 3.10. timer_interval (integer) + 3.11. db_expires (integer) + 3.12. enable_dmq (integer) + 3.13. dmq_init_sync (integer) + 3.14. timer_procs (integer) + 3.15. event_callback (str) + 3.16. event_callback_mode (int) + + 4. Functions + + 4.1. sht_print() + 4.2. sht_rm(htname, itname) + 4.3. sht_rm_name_re(htable=>regexp) + 4.4. sht_rm_value_re(htable=>regexp) + 4.5. sht_rm_name(htable, op, val) + 4.6. sht_rm_value(htable, op, val) + 4.7. sht_reset(htable) + 4.8. sht_lock(htable=>key) + 4.9. sht_unlock(htable=>key) + 4.10. sht_iterator_start(iname, hname) + 4.11. sht_iterator_end(iname) + 4.12. sht_iterator_next(iname) + 4.13. sht_iterator_rm(iname) + 4.14. sht_iterator_sets(iname, sval) + 4.15. sht_iterator_seti(iname, ival) + 4.16. sht_iterator_setex(iname, exval) + 4.17. sht_match_name(htable, op, mval) + 4.18. sht_has_name(htable, op, mval) + 4.19. sht_match_str_value(htable, op, mval) + 4.20. sht_has_str_value(htable, op, mval) + + 5. Exported pseudo-variables + 6. RPC Commands + + 6.1. htable.get htable key + 6.2. htable.delete htable key + 6.3. htable.sets htable key value + 6.4. htable.seti htable key value + 6.5. htable.setex htable key expire + 6.6. htable.dump htable + 6.7. htable.reload htable + 6.8. htable.store htable + 6.9. htable.flush htable + 6.10. htable.listTables + 6.11. htable.stats + + 7. Event routes + + 7.1. htable:mod-init + 7.2. htable:expired: + + List of Examples + + 1.1. Accessing $sht(htname=>key) + 1.2. Dictionary attack limitation + 1.3. Storing array values + 1.4. Set htable parameter + 1.5. Set db_url parameter + 1.6. Set key_name_column parameter + 1.7. Set key_type_column parameter + 1.8. Set value_type_column parameter + 1.9. Set key_value_column parameter + 1.10. Set expires_column parameter + 1.11. Set array_size_suffix parameter + 1.12. Set fetch_rows parameter + 1.13. Set timer_interval parameter + 1.14. Set db_expires parameter + 1.15. Set enable_dmq parameter + 1.16. Set dmq_init_sync parameter + 1.17. Set timer_procs parameter + 1.18. Set event_callback parameter + 1.19. Set event_callback_mode parameter + 1.20. sht_print usage + 1.21. sht_rm usage + 1.22. sht_rm_name_re usage + 1.23. sht_rm_value_re usage + 1.24. sht_rm_name usage + 1.25. sht_rm_value usage + 1.26. sht_reset usage + 1.27. sht_lock usage + 1.28. sht_unlock usage + 1.29. sht_iterator_start usage + 1.30. sht_iterator_end usage + 1.31. sht_iterator_next usage + 1.32. sht_iterator_rm usage + 1.33. sht_iterator_sets usage + 1.34. sht_iterator_seti usage + 1.35. sht_iterator_setex usage + 1.36. sht_match_name usage + 1.37. sht_match_name usage + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + 2.3. Loading from database + + 3. Parameters + + 3.1. htable (str) + 3.2. db_url (str) + 3.3. key_name_column (str) + 3.4. key_type_column (str) + 3.5. value_type_column (str) + 3.6. key_value_column (str) + 3.7. expires_column (str) + 3.8. array_size_suffix (str) + 3.9. fetch_rows (integer) + 3.10. timer_interval (integer) + 3.11. db_expires (integer) + 3.12. enable_dmq (integer) + 3.13. dmq_init_sync (integer) + 3.14. timer_procs (integer) + 3.15. event_callback (str) + 3.16. event_callback_mode (int) + + 4. Functions + + 4.1. sht_print() + 4.2. sht_rm(htname, itname) + 4.3. sht_rm_name_re(htable=>regexp) + 4.4. sht_rm_value_re(htable=>regexp) + 4.5. sht_rm_name(htable, op, val) + 4.6. sht_rm_value(htable, op, val) + 4.7. sht_reset(htable) + 4.8. sht_lock(htable=>key) + 4.9. sht_unlock(htable=>key) + 4.10. sht_iterator_start(iname, hname) + 4.11. sht_iterator_end(iname) + 4.12. sht_iterator_next(iname) + 4.13. sht_iterator_rm(iname) + 4.14. sht_iterator_sets(iname, sval) + 4.15. sht_iterator_seti(iname, ival) + 4.16. sht_iterator_setex(iname, exval) + 4.17. sht_match_name(htable, op, mval) + 4.18. sht_has_name(htable, op, mval) + 4.19. sht_match_str_value(htable, op, mval) + 4.20. sht_has_str_value(htable, op, mval) + + 5. Exported pseudo-variables + 6. RPC Commands + + 6.1. htable.get htable key + 6.2. htable.delete htable key + 6.3. htable.sets htable key value + 6.4. htable.seti htable key value + 6.5. htable.setex htable key expire + 6.6. htable.dump htable + 6.7. htable.reload htable + 6.8. htable.store htable + 6.9. htable.flush htable + 6.10. htable.listTables + 6.11. htable.stats + + 7. Event routes + + 7.1. htable:mod-init + 7.2. htable:expired:
+ +1. Overview + + The module adds a hash table container to the configuration language. + The hash table is stored in shared memory and the access to it can be + done via pseudo-variables: $sht(htname=>name). The module supports + definition of many hash tables and can load values at startup from a + database table. + + A typical use case for the SIP server is to implement a cache system in + configuration file - if a value is not found in hash table, load it + from database and store it in hash table so next time the access to it + is very fast. In the definition of the table you can define the default + expiration time of cached items. The expiration time can be adjusted + per item via assignment operation at runtime. + + Replication between multiple servers is performed automatically (if + enabled) via the DMQ module. + + You can read more about hash tables at: + http://en.wikipedia.org/wiki/Hash_table. + + The “name” can be a static string or can include pseudo- variables that + will be replaced at runtime. + + Example 1.1. Accessing $sht(htname=>key) +... +modparam("htable", "htable", "a=>size=8;") +... +$sht(a=>test) = 1; +$sht(a=>$ci::srcip) = $si; +... + + The next example shows a way to protect against dictionary attacks. If + someone fails to authenticate 3 times, it is forbidden for 15 minutes. + Authentication against database is expensive as it does a select on the + “subscriber” table. By disabling the DB auth for 15 minutes, resources + on the server are saved and time to discover the password is increased + substantially. Additional alerting can be done by writing a message to + syslog or sending email, etc. + + To implement the logic, two hash table variables are used: one counting + the failed authentications per user and one for storing the time of the + last authentication attempt. To ensure a unique name per user, the hash + table uses a combination of authentication username and text + “::auth_count” and “::last_auth”. + + Example 1.2. Dictionary attack limitation +... +modparam("htable", "htable", "a=>size=8;") +... +if(is_present_hf("Authorization")) +{ + if($sht(a=>$au::auth_count)==3) + { + $var(exp) = $Ts - 900; + if($sht(a=>$au::last_auth) > $var(exp)) + { + sl_send_reply("403", "Try later"); + exit; + } else { + $sht(a=>$au::auth_count) = 0; + } + } + if(!www_authenticate("$td", "subscriber")) + { + switch ($retcode) { + case -1: + sl_send_reply("403", "Forbidden"); + exit; + case -2: + if($sht(a=>$au::auth_count) == $null) + $sht(a=>$au::auth_count) = 0; + $sht(a=>$au::auth_count) = $sht(a=>$au::auth_count) + 1; + if($sht(a=>$au::auth_count) == 3) + xlog("auth failed 3rd time - src ip: $si\n"); + $sht(a=>$au::last_auth) = $Ts; + break; + } + www_challenge("$td"/*realm*/,"0"/*qop*/); + exit; + } + $sht(a=>$au::auth_count) = 0; +} else { + www_challenge("$td","0"); + exit; +} +... + + The module also provides a way to store multiple values for a single + key. This is emulated by storing individual keys as 'key_name[n]', + where n is incremented for each key. The total number of keys is stored + in a dedicated key, by default: 'key_name::size'. + + The array is built when the table is loaded in memory and afterwards + all the keys are treated as individual keys. If a particular entry in + the array is deleted, it is the administrator's responsibility to + update the size of the array and any other elements (if required). + + Example 1.3. Storing array values +# Example of dbtext with multiple keys +$ cat /usr/local/etc/kamailio/dbtext/htable +1:key:1:0:value3:0 +2:key:1:0:value2:0 +3:key:1:0:value1:0 + +# The array key will be loaded in memory in the following format: +$ kamcmd htable.dump htable +{ + entry: 35 + size: 1 + slot: { + item: { + name: key[0] + value: value1 + } + } +} +{ + entry: 50 + size: 1 + slot: { + item: { + name: key::size + value: 3 + } + } +} +{ + entry: 67 + size: 1 + slot: { + item: { + name: key[1] + value: value2 + } + } +} +{ + entry: 227 + size: 1 + slot: { + item: { + name: key[2] + value: value3 + } + } +} + +# Now let's delete a particular entry in the array: key[0]. +$ kamcmd htable.delete htable key[0] + +# The array key will look like this after a key was deleted: +$ kamcmd htable.dump htable +{ + entry: 50 + size: 1 + slot: { + item: { + name: key::size + value: 3 + } + } +} +{ + entry: 67 + size: 1 + slot: { + item: { + name: key[1] + value: value2 + } + } +} +{ + entry: 227 + size: 1 + slot: { + item: { + name: key[2] + value: value3 + } + } +} + +2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + 2.3. Loading from database + +2.1. Kamailio Modules + + The following modules must be loaded before this module: + * If DMQ replication is enabled, the DMQ module must be loaded + first.. + +2.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None. + +2.3. Loading from database + + The module is able to load values in a hash table at startup upon + providing a DB URL and table name. + + The structure of the table must contain: + * key name - string containing the name of the key. + * key type - the type of the key + + 0 - simple key - the key is added as 'key_name'. + + 1 - array key - the key is added as 'key_name[n]' - n is + incremented for each key with this name to build an array in + hash table. In addition, an additional key is built to hold + the total number of key in the array, by default + key_name::size (see array_size_suffix parameter). + * value type - the type of the key value + + 0 - value is string. + + 1 - value is integer. + * key value - string containing the value of the key. + +3. Parameters + + 3.1. htable (str) + 3.2. db_url (str) + 3.3. key_name_column (str) + 3.4. key_type_column (str) + 3.5. value_type_column (str) + 3.6. key_value_column (str) + 3.7. expires_column (str) + 3.8. array_size_suffix (str) + 3.9. fetch_rows (integer) + 3.10. timer_interval (integer) + 3.11. db_expires (integer) + 3.12. enable_dmq (integer) + 3.13. dmq_init_sync (integer) + 3.14. timer_procs (integer) + 3.15. event_callback (str) + 3.16. event_callback_mode (int) + +3.1. htable (str) + + The definition of a hash table. The value of the parameter may have the + following format: + * "htname=>size=_number_;autoexpire=_number_;dbtable=_string_" + + The parameter can be set multiple times to get more hash tables in same + configuration file. + * htname - string specifying the name of the hash table. This string + is used by $sht(...) to refer to the hash table. + * size - number to control how many slots (buckets) to create for the + hash table. Larger value means more slots with higher probability + for less collisions. The actual number slots (or buckets) created + for the table is 2^size. The possible range for this value is from + 2 to 31, smaller or larger values will be increased to 3 (8 slots) + or decreased to 14 (16384 slots). Note that each slot can store + more than one item, when there are collisions of hash ids computed + for keys. The items in the same slot are stored in a linked list. + In other words, the size is not setting a limit of how many items + can be stored in a hash table, as long as there is enough free + shared memory, new items can be added. + * autoexpire -time in seconds to delete an item from a hash table if + no update was done to it. If is missing or set to 0, the items + won't expire. + * dbtable - name of database to be loaded at startup in hash table. + If empty or missing, no data will be loaded. + * cols - the column names of the database table. They must be + enclosed in quotes in order to form a valid SIP parameter value and + be separated by comma. The first column corresponds to key_name. + When specified, there must be at least two columns. If this + attribute is not specified, then the global module parameters for + column names are used. If more than one value columns are + specified, the hash table will pack the column values in a comma + separated string, which will be associated with the key (string + transformation {s.select,...} can be used in configuration file to + extract a specific column value). When cols attribute is present, + writing back to database table is disabled. + * dbmode - if set to 1, the content of hash table is written to + database table when the SIP server is stopped (i.e., ensure + persistency over restarts). Default value is 0 (no write back to db + table). + * initval - the integer value to be returned instead of $null when a + requested key is not set. + * updateexpire - if set to 1 (default), the time until expiration of + an item is reset when that item is updated. Certain uses of htable + may dictate that updates should not reset the expiration timeout, + however, in which case this attribute can be set to 0. + * dmqreplicate - if set to 1, any actions (set, update, delete etc.) + performed upon entries in this table will be replicated to other + nodes (htable peers). Please note, module parameter “enable_dmq” + must also be set in order for this to apply (see below). Default is + 0 (no replication). + + Default value is NULL. + + Example 1.4. Set htable parameter +... +modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;") +modparam("htable", "htable", "b=>size=5;") +modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;dmqreplicate=1 +;") +... + +3.2. db_url (str) + + The URL to connect to database for loading values in hash table at + start up. + + Default value is NULL (do not connect). + + Example 1.5. Set db_url parameter +... +modparam("htable", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio") +... + +3.3. key_name_column (str) + + The name of the column containing the hash table key name. + + Default value is 'key_name'. + + Example 1.6. Set key_name_column parameter +... +modparam("htable", "key_name_column", "kname") +... + +3.4. key_type_column (str) + + The name of the column containing the hash table key type. + + Default value is 'key_type'. + + Example 1.7. Set key_type_column parameter +... +modparam("htable", "key_type_column", "ktype") +... + +3.5. value_type_column (str) + + The name of the column containing the hash table value type. + + Default value is 'value_type'. + + Example 1.8. Set value_type_column parameter +... +modparam("htable", "value_type_column", "vtype") +... + +3.6. key_value_column (str) + + The name of the column containing hash table key value. + + Default value is 'key_value'. + + Example 1.9. Set key_value_column parameter +... +modparam("htable", "key_value_column", "kvalue") +... + +3.7. expires_column (str) + + The name of the column containing the expires value. + + Default value is 'expires'. + + Example 1.10. Set expires_column parameter +... +modparam("htable", "expires_column", "expiry") +... + +3.8. array_size_suffix (str) + + The suffix to be added to store the number of items in an array (see + key type). + + Default value is '::size'. + + Example 1.11. Set array_size_suffix parameter +... +modparam("htable", "array_size_suffix", "-count") +... + +3.9. fetch_rows (integer) + + How many rows to fetch at once from database. + + Default value is 100. + + Example 1.12. Set fetch_rows parameter +... +modparam("htable", "fetch_rows", 1000) +... + +3.10. timer_interval (integer) + + Interval in seconds to check for expired htable values. + + Default value is 20. + + Example 1.13. Set timer_interval parameter +... +modparam("htable", "timer_interval", 10) +... + +3.11. db_expires (integer) + + If set to 1, the module loads/saves the value for expire of the items + in hash table from/to database. It applies only to hash tables that + have the auto-expires attribute defined. If set to 0, only the key name + and the value are loaded, the expires for each item being set to 0. + + Note that the module is not reloading automatically the items from + database when they expire, the reloading can be done only via RPC + command. + + Default value is 0. + + Example 1.14. Set db_expires parameter +... +modparam("htable", "db_expires", 1) +... + +3.12. enable_dmq (integer) + + If set to 1, will enable DMQ replication of actions performed upon + entries in all tables having "dmqreplicate" parameter set. Any update + action performed via pseudo-variables and RPC commands will be repeated + on all other nodes. Therefore, it is important to ensure the table + definition (size, autoexpire etc.) is identical across all instances. + + Important: If this parameter is enabled, the DMQ module must be loaded + first - otherwise, startup will fail. + + Currently, values are not replicated on load from DB as it is expected + that in these cases, all servers will load their values from the same + DB. + + Default value is 0. + + Example 1.15. Set enable_dmq parameter +... +modparam("htable", "enable_dmq", 1) +... + +3.13. dmq_init_sync (integer) + + If set to 1, will request synchronization from other nodes at startup. + It applies to all tables having the "dmqreplicate" parameter set. As + above, it is important to ensure the definition (size, autoexpire etc.) + of replicated tables is identical across all instances. + + Default value is 0. + + Example 1.16. Set dmq_init_sync parameter +... +modparam("htable", "dmq_init_sync", 1) +... + +3.14. timer_procs (integer) + + If set to 1 or greater, the module will create its own timer processes + to scan for expired items in hash tables. If set to zero, it will use + the core timer for this task. Set it to 1 if you store a lot of items + with autoexpire property. + + Default value is 0. + + Example 1.17. Set timer_procs parameter +... +modparam("htable", "timer_procs", 4) +... + +3.15. event_callback (str) + + The name of the function in the kemi configuration file (embedded + scripting language such as Lua, Python, ...) to be executed instead of + event_route[...] blocks. + + The function receives a string parameter with the name of the event, + the values can be: 'htable:mod-init', 'htable:expired:htname' ('htname' + being the name of hash table). + + Default value is 'empty' (no function is executed for events). + + Example 1.18. Set event_callback parameter +... +modparam("htable", "event_callback", "ksr_htable_event") +... +-- event callback function implemented in Lua +function ksr_htable_event(evname) + KSR.info("===== htable module triggered event: " .. evname .. "\n"); + return 1; +end +... + +3.16. event_callback_mode (int) + + Control when event_route[htable:init] is executed: 0 - after all + modules were initialized; 1 - in first worker process. + + Set it to 1 if used in a KEMI script or when needing to use database + (e.g., via sqlops) inside event_route[htable:init]. + + Default value is 0. + + Example 1.19. Set event_callback_mode parameter +... +modparam("htable", "event_callback_mode", 1) +... + +4. Functions + + 4.1. sht_print() + 4.2. sht_rm(htname, itname) + 4.3. sht_rm_name_re(htable=>regexp) + 4.4. sht_rm_value_re(htable=>regexp) + 4.5. sht_rm_name(htable, op, val) + 4.6. sht_rm_value(htable, op, val) + 4.7. sht_reset(htable) + 4.8. sht_lock(htable=>key) + 4.9. sht_unlock(htable=>key) + 4.10. sht_iterator_start(iname, hname) + 4.11. sht_iterator_end(iname) + 4.12. sht_iterator_next(iname) + 4.13. sht_iterator_rm(iname) + 4.14. sht_iterator_sets(iname, sval) + 4.15. sht_iterator_seti(iname, ival) + 4.16. sht_iterator_setex(iname, exval) + 4.17. sht_match_name(htable, op, mval) + 4.18. sht_has_name(htable, op, mval) + 4.19. sht_match_str_value(htable, op, mval) + 4.20. sht_has_str_value(htable, op, mval) + +4.1. sht_print() + + Dump content of hash table to L_ERR log level. Intended for debug + purposes. + + This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, + ONREPLY_ROUTE, BRANCH_ROUTE. + + Example 1.20. sht_print usage +... +sht_print(); +... + +4.2. sht_rm(htname, itname) + + Delete the item with the name 'itname' from hash table 'htname'. This + API function equivaluent to '$sht(htname=>itname) = $null'. + + This function can be used from ANY_ROUTE. + + Example 1.21. sht_rm usage +... +sht_rm("ha", "test""); +... + +4.3. sht_rm_name_re(htable=>regexp) + + Delete all entries in the htable that match the name against regular + expression. + + This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, + ONREPLY_ROUTE, BRANCH_ROUTE. + + Example 1.22. sht_rm_name_re usage +... +sht_rm_name_re("ha=>.*"); +... + +4.4. sht_rm_value_re(htable=>regexp) + + Delete all entries in the htable that match the value against regular + expression. + + This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, + ONREPLY_ROUTE, BRANCH_ROUTE. + + Example 1.23. sht_rm_value_re usage +... +sht_rm_value_re("ha=>.*"); +... + +4.5. sht_rm_name(htable, op, val) + + Delete all entries in the htable that match the name against the val + parameter. + + The op parameter can be: + * re - match the val parameter as regular expression. + * sw - match the val parameter as 'starts with'. + + All parameters can be static strings or contain variables. + + This function can be used from ANY_ROUTE. + + Example 1.24. sht_rm_name usage +... +sht_rm_name("ha", "re", ".*"); +... + +4.6. sht_rm_value(htable, op, val) + + Delete all entries in the htable that match the value against the val + parameter. + + The op parameter can be: + * re - match the val parameter as regular expression. + * sw - match the val parameter as 'starts with'. + + All parameters can be static strings or contain variables. + + This function can be used from ANY_ROUTE. + + Example 1.25. sht_rm_value usage +... +sht_rm_value("ha", "re", ".*"); +... + +4.7. sht_reset(htable) + + Delete all entries in the htable. The name of the hash table can be a + dynamic string with variables. + + This function can be used from ANY_ROUTE. + + Example 1.26. sht_reset usage +... +sht_reset("ha$var(x)"); +... + +4.8. sht_lock(htable=>key) + + Lock the slot in htable corresponding to the key item. Note that the + locking is re-entrant for the process, therefore the lock and unlock + should be done by the same process. + + This function can be used from ANY_ROUTE. + + Example 1.27. sht_lock usage +... +sht_lock("ha=>test"); +... + +4.9. sht_unlock(htable=>key) + + Unlock the slot in htable corresponding to the key item. Note that the + locking is re-entrant for the process, therefore the lock and unlock + should be done by the same process. + + This function can be used from ANY_ROUTE. + + Example 1.28. sht_unlock usage +... +sht_lock("ha=>test"); +$sht(ha=>test) = $sht(ha=>test) + 10; +sht_unlock("ha=>test"); +... + +4.10. sht_iterator_start(iname, hname) + + Start an iterator for hash table named by the value of parameter hname. + The parameter iname is used to identify the iterator. There can be up + to 4 iterators at the same time, with different name. + + Both parameters can be dynamic strings with variables. + + IMPORTANT: the slot of the hash table is left locked when retrieving in + item. Therefore be sure you do not update the content of the hash table + in between sht_iterator_start() and sht_iterator_end(), because it may + end up in dead lock. + + This function can be used from ANY_ROUTE. + + Example 1.29. sht_iterator_start usage +... +sht_iterator_start("i1", "h1"); +... + +4.11. sht_iterator_end(iname) + + Close the iterator identified by iname parameter and release the hash + table slot acquired by the iterator. The iname value must be the same + used for sht_iterator_start(). + + The parameter can be dynamic string with variables. + + This function can be used from ANY_ROUTE. + + Example 1.30. sht_iterator_end usage +... +sht_iterator_end("i1"); +... + +4.12. sht_iterator_next(iname) + + Move the iterator to the next item in hash table. It must be called + also after sht_iterator_start() to get the first item in the hash + table. Items are returned as they are found in the hash table slot, + starting with the first slot. + + The return code is false when there is no (more) item in the hash + table. + + The item name and value are accessible via variables: $shtitkey(iname) + and $shtitval(iname). + + The parameter can be dynamic string with variables. + + This function can be used from ANY_ROUTE. + + Example 1.31. sht_iterator_next usage +... + sht_iterator_start("i1", "h1"); + while(sht_iterator_next("i1")) { + xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n"); + } + sht_iterator_end("i1"); +... + +4.13. sht_iterator_rm(iname) + + Remove the current item in the iterator and move the iterator to the + next one. + + The return code is 1 (true) if the item was removed and next item + exists; -2 (false) if the item was removed and there is no next item + (end of items); other negative value (false) can be returned on error + (e.g., iterator or item not found). + + The parameter can be dynamic string with variables. + + This function can be used from ANY_ROUTE. + + Example 1.32. sht_iterator_rm usage +... + sht_iterator_start("i1", "h1"); + while(sht_iterator_next("i1")) { + while($shtitkey(i1) =~ "xyz" and sht_iterator_rm("i1")) { + xdbg("item removed\n"); + } + } + sht_iterator_end("i1"); +... + +4.14. sht_iterator_sets(iname, sval) + + Set the value of the current item to the string in the sval. + + The parameters can be dynamic strings with variables. + + This function can be used from ANY_ROUTE. + + Example 1.33. sht_iterator_sets usage +... + sht_iterator_start("i1", "h1"); + sht_iterator_next("i1"); + sht_iterator_sets("i1", "$ci"); + sht_iterator_end("i1"); +... + +4.15. sht_iterator_seti(iname, ival) + + Set the value of the current item to the integer in the ival. + + The parameters can be dynamic strings or integers with variables. + + This function can be used from ANY_ROUTE. + + Example 1.34. sht_iterator_seti usage +... + sht_iterator_start("i1", "h1"); + sht_iterator_next("i1"); + sht_iterator_seti("i1", "20"); + sht_iterator_end("i1"); +... + +4.16. sht_iterator_setex(iname, exval) + + Set the expire of the current item to the integer in the exval. + + The parameters can be dynamic strings or integers with variables. + + This function can be used from ANY_ROUTE. + + Example 1.35. sht_iterator_setex usage +... + sht_iterator_start("i1", "h1"); + sht_iterator_next("i1"); + sht_iterator_setex("i1", "120"); + sht_iterator_end("i1"); +... + +4.17. sht_match_name(htable, op, mval) + + Return greater than 0 (true) if the htable has an item that matches the + name against the mval parameter. + + The op parameter can be: + * eq - match the val parameter as string equal expression. + * ne - match the val parameter as string not-equal expression. + * re - match the val parameter as regular expression. + * sw - match the val parameter as 'starts with' expression. + + All parameters can be static strings or contain variables. + + This function can be used from ANY_ROUTE. + + Example 1.36. sht_match_name usage +... +if(sht_match_name("ha", "eq", "alice")) { + ... +} +... + +4.18. sht_has_name(htable, op, mval) + + Alias for sht_match_name(). + +4.19. sht_match_str_value(htable, op, mval) + + Return greater than 0 (true) if the htable has an item that matches the + string value against the mval parameter. + + The op parameter can be: + * eq - match the val parameter as string equal expression. + * ne - match the val parameter as string not-equal expression. + * re - match the val parameter as regular expression. + * sw - match the val parameter as 'starts with' expression. + + All parameters can be static strings or contain variables. + + This function can be used from ANY_ROUTE. + + Example 1.37. sht_match_name usage +... +if(sht_match_str_value("ha", "eq", "alice")) { + ... +} +... + +4.20. sht_has_str_value(htable, op, mval) + + Alias for sht_match_str_value(). + +5. Exported pseudo-variables + + * $sht(htable=>key) + * $shtex(htable=>key) + * $shtcn(htable=>key) + * $shtcv(htable=>key) + * $shtinc(htable=>key) + * $shtitkey(iname) + * $shtitval(iname) + * $shtrecord(attribute) + + Exported pseudo-variables are documented at + https://www.kamailio.org/wiki/. + +6. RPC Commands + + 6.1. htable.get htable key + 6.2. htable.delete htable key + 6.3. htable.sets htable key value + 6.4. htable.seti htable key value + 6.5. htable.setex htable key expire + 6.6. htable.dump htable + 6.7. htable.reload htable + 6.8. htable.store htable + 6.9. htable.flush htable + 6.10. htable.listTables + 6.11. htable.stats + +6.1. htable.get htable key + + Lists one value in a hash table + + Name: htable.get + + Parameters: + * htable : Name of the hash table to dump + * key : Key name of the hash table value to dump + + Example: +... +# Dump $sht(students=>alice) +kamcmd htable.get students alice + +# Dump first entry in array key course $sht(students=>course[0]) +kamcmd htable.get students course[0] +... + +6.2. htable.delete htable key + + Delete one value in a hash table + + Name: htable.delete + + Parameters: + * htable : Name of the hash table to delete + * key : Key name of the hash table value to delete + + Example: +... +# Delete $sht(students=>alice) +kamcmd htable.delete students alice + +# Delete first entry in array key course $sht(students=>course[0]) +kamcmd htable.delete students course[0] +... + +6.3. htable.sets htable key value + + Set an item in hash table to string value. + + Name: htable.sets + + Parameters: + * htable : Name of the hash table + * key : Key name in the hash table + * Value : String value for the item + + Example: +... +# Set $sht(test=>x) as string +kamcmd htable.sets test x abc + +# Set firsti entry in array key x $sht(test=>x[0]) as string +kamcmd htable.sets test x[0] abc +... + +6.4. htable.seti htable key value + + Set an item in hash table to integer value. + + Name: htable.seti + + Parameters: + * htable : Name of the hash table + * key : Key name in the hash table + * Value : Integer value for the item + + Example: +... +# Set $sht(test=>x) as integer +kamcmd htable.seti test x 123 + +# Set first entry in array key x $sht(test=>x[0]) as integer +kamcmd htable.seti test x[0] 123 +... + +6.5. htable.setex htable key expire + + Set the expire for an item in hash table. + + Name: htable.setex + + Parameters: + * htable : name of the hash table + * key : key name in the hash table + * expire : integer value for the expire (seconds) + + Example: +... +# set expire for $sht(test=>x) to 120 secs +kamctl rpc htable.seti test x 120 +... + +6.6. htable.dump htable + + Lists all the values in a hash table + + Name: htable.dump + + Parameters: + * htable : Name of the hash table to dump + + Example: +... +kamcmd htable.dump ipban +... + +6.7. htable.reload htable + + Reload hash table from database. + + Name: htable.reload + + Parameters: + * htable : Name of the hash table to reload + + Example: +... +kamcmd htable.reload ipban +... + +6.8. htable.store htable + + Store hash table to database. + + Name: htable.store + + Parameters: + * htable : Name of the hash table to store + + Example: +... +kamcmd htable.store ipban +... + +6.9. htable.flush htable + + Empty the hash table + + Name: htable.flush + + Parameters: + * htable : Name of the hash table to flush + + Example: +... +kamcmd htable.flush ipban +... + +6.10. htable.listTables + + Lists all defined tables + + Name: htable.listTables + + Parameters: + * None + + Example: +... +kamcmd htable.listTables +... + +6.11. htable.stats + + Get statistics for hash tables - name, number of slots, number of + items, max number of items per slot, min number of items per slot. + + Name: htable.stats + + Parameters: + * None + + Example: +... +kamcmd htable.stats +... + +7. Event routes + + 7.1. htable:mod-init + 7.2. htable:expired:
+ +7.1. htable:mod-init + + When defined, the module calls event_route[htable:mod-init] after all + modules have been initialized. A typical use case is to initialise + items in hash tables. The event route is executed only once, after core + and module initialization, but before Kamailio forks any child + processes. + + Note: do not expect to use functions from all other modules here, even + if they are loaded before the htable module, because many of them + initialize their runtime structures inside child init callbacks, which + are executed after this moment, when forking child processes. For + example, sqlops cannot be used, connections to database are initialized + in child init. Even more, it is recommended not to use functions from + other modules, because it can mess up what they created in mod init + callback and expect in child init callback. It should be ok to use + functions from htable module or assignment operations. +... +event_route[htable:mod-init] { + $sht(a=>x) = 1; +} +... + +7.2. htable:expired:
+ + When defined, the module calls event_route[htable:expired:
] when + an entry in the given table expires. In this event route, the key and + value of the expired record are available with the $shtrecord(key) and + $shtrecord(value) pseudo-variables. +... + +event_route[htable:expired:mytable] { + xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n"); +} +...