HTable Module

Elena-Ramona Modroiu

   asipto.com
   <ramona@rosdev.ro>

Edited by

Elena-Ramona Modroiu

   <ramona@rosdev.ro>

Alex Balashov

   <abalashov@evaristesys.com>

Ovidiu Sas

   <osas@voipembedded.com>

Tyler Moore

   <tmoore@dopensource.com>

   Copyright © 2008-2011 http://www.asipto.com

   Copyright © 2023 Tyler Moore (devopsec), dOpenSource
     __________________________________________________________________

   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_setxs(htname, itname, itval, exval)
              4.8. sht_setxi(htname, itname, itval, exval)
              4.9. sht_reset(htable)
              4.10. sht_lock(htable=>key)
              4.11. sht_unlock(htable=>key)
              4.12. sht_iterator_start(iname, hname)
              4.13. sht_iterator_end(iname)
              4.14. sht_iterator_next(iname)
              4.15. sht_iterator_rm(iname)
              4.16. sht_iterator_sets(iname, sval)
              4.17. sht_iterator_seti(iname, ival)
              4.18. sht_iterator_setex(iname, exval)
              4.19. sht_match_name(htable, op, mval)
              4.20. sht_has_name(htable, op, mval)
              4.21. sht_match_str_value(htable, op, mval)
              4.22. 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.setxs htable key value expire
              6.7. htable.setxi htable key value expire
              6.8. htable.dump htable
              6.9. htable.reload htable
              6.10. htable.store htable
              6.11. htable.flush htable
              6.12. htable.listTables
              6.13. htable.stats
              6.14. htable.dmqsync [htable]
              6.15. htable.dmqresync htable

        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_setxs usage
   1.27. sht_setxi usage
   1.28. sht_reset usage
   1.29. sht_lock usage
   1.30. sht_unlock usage
   1.31. sht_iterator_start usage
   1.32. sht_iterator_end usage
   1.33. sht_iterator_next usage
   1.34. sht_iterator_rm usage
   1.35. sht_iterator_sets usage
   1.36. sht_iterator_seti usage
   1.37. sht_iterator_setex usage
   1.38. sht_match_name usage
   1.39. 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_setxs(htname, itname, itval, exval)
        4.8. sht_setxi(htname, itname, itval, exval)
        4.9. sht_reset(htable)
        4.10. sht_lock(htable=>key)
        4.11. sht_unlock(htable=>key)
        4.12. sht_iterator_start(iname, hname)
        4.13. sht_iterator_end(iname)
        4.14. sht_iterator_next(iname)
        4.15. sht_iterator_rm(iname)
        4.16. sht_iterator_sets(iname, sval)
        4.17. sht_iterator_seti(iname, ival)
        4.18. sht_iterator_setex(iname, exval)
        4.19. sht_match_name(htable, op, mval)
        4.20. sht_has_name(htable, op, mval)
        4.21. sht_match_str_value(htable, op, mval)
        4.22. 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.setxs htable key value expire
        6.7. htable.setxi htable key value expire
        6.8. htable.dump htable
        6.9. htable.reload htable
        6.10. htable.store htable
        6.11. htable.flush htable
        6.12. htable.listTables
        6.13. htable.stats
        6.14. htable.dmqsync [htable]
        6.15. htable.dmqresync htable

   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 it 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).
     * coldelim - the character delimeter to use when packing the htable.
       When set, this parameter changes the column delimeter between
       columns in a multiple column hash table. This can be useful when
       loading JSON data types into a hash table as they conflict with the
       default “,” delimeter, allowing these values to be parsed in the
       routing config. See the example below on parsing a JSON array from
       an htable with “;” as the column delimeter.
...
modparam("htable", "htable", "customer=>size=8;dbtable=customer;cols='dids,descr
iption';coldelim=';'")
...
$avp(customer) = $sht(customer=>1);
$var(customer_dids) = $(avp(customer){s.select,0,;});
$var(customer_desc) = $(avp(customer){s.select,1,;});
...
     * colnull - the character to use when packing a NULL value into the
       htable from the database. This parameter can be set to the empty
       string or a single character. This can be used to simplify checking
       a single column in a row for emptiness, in the routing config. The
       example below shows how one would do that.
...
modparam("htable", "htable", "customer=>size=8;dbtable=customer;cols='name,descr
iption';colnull=''")
...
$avp(customer) = $sht(customer=>1);
$var(customer_name) = $(avp(customer){s.select,0,;});
if (!strempty($var(customer_name))) {
...
}

   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_setxs(htname, itname, itval, exval)
   4.8. sht_setxi(htname, itname, itval, exval)
   4.9. sht_reset(htable)
   4.10. sht_lock(htable=>key)
   4.11. sht_unlock(htable=>key)
   4.12. sht_iterator_start(iname, hname)
   4.13. sht_iterator_end(iname)
   4.14. sht_iterator_next(iname)
   4.15. sht_iterator_rm(iname)
   4.16. sht_iterator_sets(iname, sval)
   4.17. sht_iterator_seti(iname, ival)
   4.18. sht_iterator_setex(iname, exval)
   4.19. sht_match_name(htable, op, mval)
   4.20. sht_has_name(htable, op, mval)
   4.21. sht_match_str_value(htable, op, mval)
   4.22. 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 is equivalent 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'.
     * ew - match the val parameter as 'ends with'.
     * in - match the val parameter as 'includes'.

   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'.
     * ew - match the val parameter as 'ends with'.
     * in - match the val parameter as 'includes'.

   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_setxs(htname, itname, itval, exval)

   Set the item with the name 'itname' from hash table 'htname' to string
   value 'itval' and expire property to 'exval'.

   The parameters can be with variables.

   This function can be used from ANY_ROUTE.

   Example 1.26. sht_setxs usage
...
sht_setxs("ha", "test", "abc", "10");
...

4.8.  sht_setxi(htname, itname, itval, exval)

   Set the item with the name 'itname' from hash table 'htname' to integer
   value 'itval' and expire property to 'exval'.

   The parameters can be with variables.

   This function can be used from ANY_ROUTE.

   Example 1.27. sht_setxi usage
...
sht_setxs("ha", "test", "100", "10");
...

4.9.  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.28. sht_reset usage
...
sht_reset("ha$var(x)");
...

4.10.  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.29. sht_lock usage
...
sht_lock("ha=>test");
...

4.11.  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.30. sht_unlock usage
...
sht_lock("ha=>test");
$sht(ha=>test) = $sht(ha=>test) + 10;
sht_unlock("ha=>test");
...

4.12.  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.31. sht_iterator_start usage
...
sht_iterator_start("i1", "h1");
...

4.13.  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.32. sht_iterator_end usage
...
sht_iterator_end("i1");
...

4.14.  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.33. 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.15.  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.34. 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.16.  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.35. sht_iterator_sets usage
...
    sht_iterator_start("i1", "h1");
    sht_iterator_next("i1");
    sht_iterator_sets("i1", "$ci");
    sht_iterator_end("i1");
...

4.17.  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.36. sht_iterator_seti usage
...
    sht_iterator_start("i1", "h1");
    sht_iterator_next("i1");
    sht_iterator_seti("i1", "20");
    sht_iterator_end("i1");
...

4.18.  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.37. sht_iterator_setex usage
...
    sht_iterator_start("i1", "h1");
    sht_iterator_next("i1");
    sht_iterator_setex("i1", "120");
    sht_iterator_end("i1");
...

4.19.  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.38. sht_match_name usage
...
if(sht_match_name("ha", "eq", "alice")) {
  ...
}
...

4.20.  sht_has_name(htable, op, mval)

   Alias for sht_match_name().

4.21.  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.39. sht_match_name usage
...
if(sht_match_str_value("ha", "eq", "alice")) {
  ...
}
...

4.22.  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/wikidocs/.

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.setxs htable key value expire
   6.7. htable.setxi htable key value expire
   6.8. htable.dump htable
   6.9. htable.reload htable
   6.10. htable.store htable
   6.11. htable.flush htable
   6.12. htable.listTables
   6.13. htable.stats
   6.14. htable.dmqsync [htable]
   6.15. htable.dmqresync htable

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. Note: if key name
       is an integer value, it should be prefixed with s:

   Example:
...
# Dump $sht(students=>alice)
kamcmd htable.get students alice

# Dump $sht(students=>15)
kamcmd htable.get students s:15

# 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. Note: if key name
       is an integer value, it should be prefixed with s:

   Example:
...
# Delete $sht(students=>alice)
kamcmd htable.delete students alice

# Delete $sht(students=>15)
kamcmd htable.delete students s:15

# 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. Note: if key name is an integer
       value, it should be prefixed with s:
     * Value : String value for the item

   Example:
...
# Set $sht(test=>x) as string
kamcmd htable.sets test x abc

# Set $sht(test=>5) as string
kamcmd htable.sets test s:5 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. Note: if key name is an integer
       value, it should be prefixed with s:
     * Value : Integer value for the item

   Example:
...
# Set $sht(test=>x) as integer
kamcmd htable.seti test x 123

# Set $sht(test=>5) as integer
kamcmd htable.seti test s:5 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. Note: if key name is an integer
       value, it should be prefixed with s:
     * expire : integer value for the expire (seconds)

   Example:
...
# set expire for $sht(test=>x) to 120 secs
kamctl rpc htable.setex test x 120

# set expire for $sht(test=>10) to 120 secs
kamctl rpc htable.setex test s:10 120
...

6.6.  htable.setxs htable key value expire

   Set the string value and expire for an item in hash table.

   Name: htable.setxs

   Parameters:
     * htable : name of the hash table
     * key : key name in the hash table. Note: if key name is an integer
       value, it should be prefixed with s:
     * value : string value for the item
     * expire : integer value for the expire (seconds)

   Example:
...
# set value to 'abc' and expire for $sht(test=>x) to 120 secs
kamctl rpc htable.setxs test x abc 120

# set value to 'abc' and expire for $sht(test=>10) to 120 secs
kamctl rpc htable.setxs test s:10 abc 120
...

6.7.  htable.setxi htable key value expire

   Set the integer value and expire for an item in hash table.

   Name: htable.setxi

   Parameters:
     * htable : name of the hash table
     * key : key name in the hash table. Note: if key name is an integer
       value, it should be prefixed with s:
     * value : integer value for the item
     * expire : integer value for the expire (seconds)

   Example:
...
# set value to 10 and expire for $sht(test=>x) to 120 secs
kamctl rpc htable.setxi test x 10 120

# set value to 10 and expire for $sht(test=>5) to 120 secs
kamctl rpc htable.setxi test s:5 10 120
...

6.8.  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.9.  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.10.  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.11.  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.12.  htable.listTables

   Lists all defined tables

   Name: htable.listTables

   Parameters:
     * None

   Example:
...
kamcmd htable.listTables
...

6.13.  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
...

6.14.  htable.dmqsync [htable]

   Perform a DMQ sync action.

   Name: htable.dmqsync

   Parameters:
     * htable: name of the hash table to perform dmq sync for. If not
       provided, sync is performed for all hash tables that have dmq sync
       enabled.

   Example:
...
kamcmd htable.dmqsync
kamcmd htable.dmqsync ipban
...

6.15.  htable.dmqresync htable

   Perform a resync action (flush and dmq sync).

   Name: htable.dmqresync

   Parameters:
     * htable: name of the hash table to perform resync for.

   Example:
...
kamcmd htable.dmqresync ipban
...

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");
}
...
