<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		The module adds a hash table container to configuration language. The
		hash table is stored in shared memory and the access to it can be
		done via pseudo-variables: $sht(htname=&gt;name). The module supports
		definition of many hash tables and can load values at startup from
		a database table.
	</para>
	<para>
		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 itme via assignment operation at runtime.
	</para>
	<para>
		Replication between multiple servers is performed automatically (if 
		enabled) via the DMQ module.
	</para>
	<para>
		You can read more about hash tables at:
		http://en.wikipedia.org/wiki/Hash_table.
	</para>
	<para>
		The <quote>name</quote> can be a static string or can include pseudo-
		variables that will be replaced at runtime.
	</para>
	<example>
		<title>Accessing $sht(htname=&gt;key)</title>
	<programlisting format="linespecific">
...
modparam("htable", "htable", "a=&gt;size=8;")
...
$sht(a=&gt;test) = 1;
$sht(a=&gt;$ci::srcip) = $si;
...
</programlisting>
	</example>
	<para>
		Next example shows a way to protect against dictionary attacks. If
		someone fails to authenticate 3 times, it is forbidden for 15min.
		Authenticatin against database is expensive as it does a select
		on subscriber table. By disabling the DB auth for 15min, resources
		on server as 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.
	</para>
	<para>
		To implement the logic, two hash table variables are user: one counting
		the failed authentications per user and one for storing the time of 
		last authentication attempt. To ensure unique name per user, the
		hash table uses a combination of authentication username and text
		<quote>::auth_count</quote> and <quote>::last_auth</quote>.
	</para>
	<example>
	<title>Dictionary attack limitation</title>
	<programlisting format="linespecific">
...
modparam("htable", "htable", "a=&gt;size=8;")
...
if(is_present_hf("Authorization"))
{
    if($sht(a=&gt;$au::auth_count)==3)
    {
		$var(exp) = $Ts - 900;
        if($sht(a=&gt;$au::last_auth) &gt; $var(exp))
        {
            sl_send_reply("403", "Try later");
            exit;
        } else {
            $sht(a=&gt;$au::auth_count) = 0;
        }
    }
    if(!www_authenticate("$td", "subscriber"))
    {
        switch ($retcode) {
            case -1:
                sl_send_reply("403", "Forbidden");
            exit;
            case -2:
                if($sht(a=&gt;$au::auth_count) == $null)
                    $sht(a=&gt;$au::auth_count) = 0;
                $sht(a=&gt;$au::auth_count) = $sht(a=&gt;$au::auth_count) + 1;
                if($sht(a=&gt;$au::auth_count) == 3)
                    xlog("auth failed 3rd time - src ip: $si\n");
                $sht(a=&gt;$au::last_auth) = $Ts;
            break;
        }
        www_challenge("$td"/*realm*/,"0"/*qop*/);
        exit;
    }
    $sht(a=&gt;$au::auth_count) = 0;
} else {
    www_challenge("$td","0");
    exit;
}
...
</programlisting>
	</example>
	<para>
		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'.
	</para>
	<para>
		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 administarator's
		responsability to update the size of the array and any other elements
		(if required).
	</para>
	<example>
	<title>Storring array values</title>
	<programlisting format="linespecific">
# 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
                }
        }
}
</programlisting>
	</example>

	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>If DMQ replication is enabled, the DMQ module must be loaded first.</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>Loading from database</title>
		<para>
		The module is able to load values in hash table at startup upon
		providing a DB URL and table name.
		</para>
		<para>
			The structure of the table must contain:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>key name</emphasis> - string containing the name of
				the key.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>key type</emphasis> - the type of the key
			</para>
			<itemizedlist>
				<listitem>
				<para>
					<emphasis>0</emphasis> - simple key - the key is added
					as 'key_name'.
				</para>
				</listitem>
				<listitem>
				<para>
					<emphasis>1</emphasis> - 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).
				</para>
				</listitem>
			</itemizedlist>
			</listitem>
			<listitem>
			<para>
				<emphasis>value type</emphasis> - the type of the key value
			</para>
			<itemizedlist>
				<listitem>
				<para>
					<emphasis>0</emphasis> - value is string.
				</para>
				</listitem>
				<listitem>
				<para>
					<emphasis>1</emphasis> - value is integer.
				</para>
				</listitem>
			</itemizedlist>
			</listitem>
			<listitem>
			<para>
				<emphasis>key value</emphasis> - string containing the value of
				the key.
			</para>
			</listitem>
			</itemizedlist>
	</section>

	</section>
	<section>
	<title>Parameters</title>
	<section id="htable.p.htable">
		<title><varname>htable</varname> (str)</title>
		<para>
		The definition of a hash table. The value of the parameter must have the
		following format:
		</para>
		<itemizedlist>
		<listitem>
		<para>
		"htname=&gt;size=_number_;autoexpire=_number_;dbtable=_string_"
		</para>
		</listitem>
		</itemizedlist>
		<para>
			The parameter can be set multiple times to get more hash tables in
			same configuration file.
		</para>
		<itemizedlist>
		<listitem>
		<para>
			<emphasis>htname</emphasis> - string specifying the name of
			the hash table. This string is used by $sht(...) to refer to the
			hash table.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>size</emphasis> - number specifying the size of hash
			table.  Larger value means less collisions. The number of entries
			(aka slots or buckets) in 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).
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>autoexpire</emphasis> -time in seconds to delete an item
			from hash table if no update was done to it. If is missing or set
			to 0, the items won't expire.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>dbtable</emphasis> - name of database to be loaded at
			startup in hash table. If empty or missing, no data will be loaded.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>dbmode</emphasis> - 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).
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>initval</emphasis> - the integer value to be returned
			instead of $null when a requested key is not set.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>updateexpire</emphasis> - 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.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>dmqreplicate</emphasis> - 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).
		</para>
		</listitem>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "htable", "a=&gt;size=4;autoexpire=7200;dbtable=htable_a;")
modparam("htable", "htable", "b=&gt;size=5;")
modparam("htable", "htable", "c=&gt;size=4;autoexpire=7200;initval=1;dmqreplicate=1;")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.db_url">
		<title><varname>db_url</varname> (str)</title>
		<para>
			The URL to connect to database for loading values in hash
			table at start up.
		</para>
		<para>
		<emphasis>
			Default value is NULL (do not connect).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "db_url", "&defaultdb;")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.key_name_column">
		<title><varname>key_name_column</varname> (str)</title>
		<para>
			The name of the column containing hash table key name.
		</para>
		<para>
		<emphasis>
			Default value is 'key_name'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>key_name_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "key_name_column", "kname")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.key_type_column">
		<title><varname>key_type_column</varname> (str)</title>
		<para>
			The name of the column containing hash table key type.
		</para>
		<para>
		<emphasis>
			Default value is 'key_type'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>key_type_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "key_type_column", "ktype")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.value_type_column">
		<title><varname>value_type_column</varname> (str)</title>
		<para>
			The name of the column containing hash table value type.
		</para>
		<para>
		<emphasis>
			Default value is 'value_type'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>value_type_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "value_type_column", "vtype")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.key_value_column">
		<title><varname>key_value_column</varname> (str)</title>
		<para>
			The name of the column containing hash table key value.
		</para>
		<para>
		<emphasis>
			Default value is 'key_value'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>key_value_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "key_value_column", "kvalue")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.expires_column">
		<title><varname>expires_column</varname> (str)</title>
		<para>
			The name of the column containing expires type.
		</para>
		<para>
		<emphasis>
			Default value is 'expires'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>expires_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "expires", "expiry")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.array_size_suffix">
		<title><varname>array_size_suffix</varname> (str)</title>
		<para>
			The suffix to be added to store the number of items in an
			array (see key type).
		</para>
		<para>
		<emphasis>
			Default value is '::size'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>array_size_suffix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "array_size_suffix", "-count")
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.fetch_rows">
		<title><varname>fetch_rows</varname> (integer)</title>
		<para>
		How many rows to fetch at once from database.
		</para>
		<para>
		<emphasis>
			Default value is 100.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fetch_rows</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "fetch_rows", 1000)
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.timer_interval">
		<title><varname>timer_interval</varname> (integer)</title>
		<para>
		Interval in seconds to check for expired htable values.
		</para>
		<para>
		<emphasis>
			Default value is 20.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timer_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "timer_interval", 10)
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.timer_mode">
		<title><varname>timer_mode</varname> (integer)</title>
		<para>
		If set to 1, will start a new timer process. If set to 0
		will use default timer process to check for expired htable
		values.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timer_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "timer_mode", 1)
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.db_expires">
		<title><varname>db_expires</varname> (integer)</title>
		<para>
			If set to 1, will load/save the expires values of the items in
			hash table fromm/to database. It applies only to hash tables that
			have auto-expires attribute defined.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "db_expires", 1)
...
</programlisting>
		</example>
	</section>
	<section id="htable.p.enable_dmq">
		<title><varname>enable_dmq</varname> (integer)</title>
		<para>
			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, MI 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.
		</para>
		<para>
			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.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable_dmq</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("htable", "enable_dmq", 1)
...
</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title>Functions</title>
	<section id="htable.f.sht_print">
		<title>
		<function moreinfo="none">sht_print()</function>
		</title>
		<para>
			Dump content of hash table to L_ERR log level. Intended for debug
			purposes.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			ONREPLY_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>sht_print</function> usage</title>
		<programlisting format="linespecific">
...
sht_print();
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_rm_name_re">
		<title>
		<function moreinfo="none">sht_rm_name_re(htable=>regexp)</function>
		</title>
		<para>
			Delete all entries in the htable that match the name against
			regular expression.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			ONREPLY_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>sht_rm_name_re</function> usage</title>
		<programlisting format="linespecific">
...
sht_rm_name_re("ha=>.*");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_rm_value_re">
		<title>
		<function moreinfo="none">sht_rm_value_re(htable=>regexp)</function>
		</title>
		<para>
			Delete all entries in the htable that match the value against
			regular expression.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			ONREPLY_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>sht_rm_value_re</function> usage</title>
		<programlisting format="linespecific">
...
sht_rm_value_re("ha=>.*");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_reset">
		<title>
		<function moreinfo="none">sht_reset(htable)</function>
		</title>
		<para>
			Delete all entries in the htable. The name of the hash table
			can be a dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_reset</function> usage</title>
		<programlisting format="linespecific">
...
sht_reset("ha$var(x)");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_lock">
		<title>
		<function moreinfo="none">sht_lock(htable=>key)</function>
		</title>
		<para>
			Lock the slot in htable corespoding to the key item.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_lock</function> usage</title>
		<programlisting format="linespecific">
...
sht_lock("ha=>test");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_unlock">
		<title>
		<function moreinfo="none">sht_unlock(htable=>key)</function>
		</title>
		<para>
			Unlock the slot in htable corespoding to the key item.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_unlock</function> usage</title>
		<programlisting format="linespecific">
...
sht_lock("ha=>test");
$sht(ha=>test) = $sht(ha=>test) + 10;
sht_unlock("ha=>test");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_iterator_start">
		<title>
		<function moreinfo="none">sht_iterator_start(iname, hname)</function>
		</title>
		<para>
			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.
		</para>
		<para>
			Both parameters can be dynamic strings with variables.
		</para>
		<para>
			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.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_iterator_start</function> usage</title>
		<programlisting format="linespecific">
...
sht_iterator_start("i1", "h1");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_iterator_end">
		<title>
		<function moreinfo="none">sht_iterator_end(iname)</function>
		</title>
		<para>
			Close the iterator identified by iname parameter and release
			the hash table slot aquired by the iterator. The iname value
			must be the same used for sht_iterator_start().
		</para>
		<para>
			The parameter can be dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_iterator_end</function> usage</title>
		<programlisting format="linespecific">
...
sht_iterator_end("i1");
...
</programlisting>
		</example>
	</section>
	<section id="htable.f.sht_iterator_next">
		<title>
		<function moreinfo="none">sht_iterator_next(iname)</function>
		</title>
		<para>
			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.
		</para>
		<para>
			The return code is false when there is no (more) item in the
			hash table.
		</para>
		<para>
			The item name and value are accessible via variables:
			$shtitkey(iname) and $shtitval(iname).
		</para>
		<para>
			The parameter can be dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sht_iterator_next</function> usage</title>
		<programlisting format="linespecific">
...
    sht_iterator_start("i1", "h1");
    while(sht_iterator_next("i1")) {
        xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
    }
    sht_iterator_end("i1");
...
</programlisting>
		</example>
	</section>
	</section>
		<section>
		<title>Exported pseudo-variables</title>
		<itemizedlist>
			<listitem><para>
				<emphasis>$sht(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtex(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtcn(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtcv(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtinc(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtval(htable=>key)</emphasis>
			</para></listitem>
			<listitem><para>
				<emphasis>$shtrecord(attribute)</emphasis>
			</para></listitem>
		</itemizedlist>
		<para>
		Exported pseudo-variables are documented at &kamwikilink;.
		</para>
	</section>
	<section>
	<title>MI Commands</title>
	<section>
		<title>
		<function moreinfo="none">sht_reload</function>
		</title>
		<para>
		Reload a hash table from database.
		</para>
		<para>
		Name: <emphasis>sht_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>_hash_table_name_</emphasis> - the name
		of hash table to reload.</para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:sht_reload:_reply_fifo_file_
		_hash_table_name_
		_empty_line_
		</programlisting>
    </section>
    <section>
		<title>
		<function moreinfo="none">sht_dump</function>
		</title>
		<para>
		Dump content of a hash table via MI.
		</para>
		<para>
		Name: <emphasis>sht_dump</emphasis>
		</para>
		<para>Parameters: <emphasis>_hash_table_name_</emphasis> - the name
		of hash table to dump.</para>
 		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		:sht_dump:_reply_fifo_file_
		_hash_table_name_
		_empty_line_
		</programlisting>
    </section>
    <section>
		<title>
		<function moreinfo="none">sht_delete</function>
		</title>
		<para>
		Delete a key from a hash table via MI.
		</para>
		<para>
		Name: <emphasis>sht_delete</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para><emphasis>_hash_table_name: </emphasis>The table name to delete the key from</para></listitem>
			<listitem><para><emphasis>_key_name: </emphasis>The key to delete from the htable</para></listitem>
		</itemizedlist>

 		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		:sht_delete:_reply_fifo_file_
		_hash_table_name_
		_key_name_
		_empty_line_
		</programlisting>

 		<para>
		Example (note the quoting when executing it via FIFO):
		</para>
		<programlisting  format="linespecific">
		kamctl fifo sht_delete auth '"user@example.org::last_auth"'
		</programlisting>
    </section>
    </section>
	<section>
        <title>Exported RPC Commands</title>
        <section>
                <title>
                <function moreinfo="none">htable.get htable key</function>
                </title>
                <para>
		Lists one value in a hash table
                </para>
                <para>
                Name: <emphasis>htable.get</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table to dump</para>
                        </listitem>
                        <listitem><para>key : Key name of the hash table value to dump</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
# Dump $sht(students=>daniel)
kamcmd htable.get students daniel

# Dump first entry in array key course $sht(students=>course[0])
kamcmd htable.get students course[0]
...
</programlisting>
	</section>
        <section>
                <title>
                <function moreinfo="none">htable.delete htable key</function>
                </title>
                <para>
		Delete one value in a hash table
                </para>
                <para>
                Name: <emphasis>htable.delete</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table to delete</para>
                        </listitem>
                        <listitem><para>key : Key name of the hash table value to delete</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
# Delete $sht(students=>anna)
kamcmd htable.delete students anna

# Delete first entry in array key course $sht(students=>course[0])
kamcmd htable.delete students course[0]
...
</programlisting>
	</section>
       <section>
                <title>
                <function moreinfo="none">htable.sets htable key value</function>
                </title>
                <para>
					Set an item in hash table to string value.
                </para>
                <para>
                Name: <emphasis>htable.sets</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table</para>
                        </listitem>
                        <listitem><para>key : Key name in the hash table</para>
                        </listitem>
                        <listitem><para>Value : String value for the item</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
# 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
...
</programlisting>
	</section>
       <section>
                <title>
                <function moreinfo="none">htable.seti htable key value</function>
                </title>
                <para>
					Set an item in hash table to integer value.
                </para>
                <para>
                Name: <emphasis>htable.seti</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table</para>
                        </listitem>
                        <listitem><para>key : Key name in the hash table</para>
                        </listitem>
                        <listitem><para>Value : Integer value for the item</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
# Set $sht(test=>x) as integer
kamcmd htable.seti test x 123

# Set firsti entry in array key x $sht(test=>x[0]) as integer
kamcmd htable.sets test x[0] 123
...
</programlisting>
	</section>
        <section>
                <title>
                <function moreinfo="none">htable.dump htable</function>
                </title>
                <para>
		Lists all the values in a hash table
                </para>
                <para>
                Name: <emphasis>dhtable.dump</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table to dump</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
kamcmd htable.dump ipban
...
</programlisting>
	</section>
        <section>
                <title>
                <function moreinfo="none">htable.reload htable</function>
                </title>
                <para>
		Reload hash table from database.
                </para>
                <para>
                Name: <emphasis>dhtable.reload</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>htable : Name of the hash table to reload</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
kamcmd htable.reload ipban
...
</programlisting>
	</section>
        <section>
                <title>
                <function moreinfo="none">htable.listTables</function>
                </title>
                <para>
		Lists all defined tables
                </para>
                <para>
                Name: <emphasis>htable.listTables</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>None</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
kamcmd htable.listTables
...
</programlisting>
	</section>
    <section>
          <title>
                <function moreinfo="none">htable.stats</function>
          </title>
          <para>
			  Get statistics for hash tables - name, number of slots,
			  number of items, max number of items per slot, min number
			  of items per slot.
          </para>
                <para>
                Name: <emphasis>htable.stats</emphasis>
                </para>
                <para>Parameters:</para>
                <itemizedlist>
                        <listitem><para>None</para>
                        </listitem>

                </itemizedlist>
                <para>
                Example:
                </para>
<programlisting  format="linespecific">
...
kamcmd htable.stats
...
</programlisting>
	</section>

	</section><!-- RPC commands -->

	<section>
	<title>Event routes</title>
	<section>
		<title>
		<function moreinfo="none">htable:mod-init</function>
		</title>
		<para>
			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.
		</para>
<programlisting  format="linespecific">
...
event_route[htable:mod-init] {
    $sht(a=>x) = 1;
}
...
</programlisting>
	</section>
	<section>
		<title>
		<function moreinfo="none">htable:expired:&lt;table&gt;</function>
		</title>
		<para>
			When defined, the module calls event_route[htable:expired:&lt;table&gt;]
			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.
		</para>
<programlisting  format="linespecific">
...

event_route[htable:expired:mytable] {
    xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
}
...
</programlisting>
	</section>
	</section>

</chapter>