modules: readme files regenerated - htable ... [skip ci]

src/modules/htable/README

@@ -1,1284 +1 @@
-HTable Module
 
-Elena-Ramona Modroiu
-
-   asipto.com
-   <[email protected]>
-
-Edited by
-
-Elena-Ramona Modroiu
-
-   <[email protected]>
-
-Alex Balashov
-
-   <[email protected]>
-
-Ovidiu Sas
-
-   <[email protected]>
-
-   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.dump htable
-              6.6. htable.reload htable
-              6.7. htable.store htable
-              6.8. htable.flush htable
-              6.9. htable.listTables
-              6.10. htable.stats
-
-        7. Event routes
-
-              7.1. htable:mod-init
-              7.2. htable:expired:<table>
-
-   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.dump htable
-        6.6. htable.reload htable
-        6.7. htable.store htable
-        6.8. htable.flush htable
-        6.9. htable.listTables
-        6.10. htable.stats
-
-   7. Event routes
-
-        7.1. htable:mod-init
-        7.2. htable:expired:<table>
-
-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.dump htable
-   6.6. htable.reload htable
-   6.7. htable.store htable
-   6.8. htable.flush htable
-   6.9. htable.listTables
-   6.10. 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.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.6.  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.7.  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.8.  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.9.  htable.listTables
-
-   Lists all defined tables
-
-   Name: htable.listTables
-
-   Parameters:
-     * None
-
-   Example:
-...
-kamcmd htable.listTables
-...
-
-6.10.  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:<table>
-
-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:<table>
-
-   When defined, the module calls event_route[htable:expired:<table>] 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");
-}
-...