93586d13c666eb6b1eef2ffea0aad0ca07eba302
[sip-router] / src / modules / htable / README
1 HTable Module
2
3 Elena-Ramona Modroiu
4
5    asipto.com
6    <ramona@rosdev.ro>
7
8 Edited by
9
10 Elena-Ramona Modroiu
11
12    <ramona@rosdev.ro>
13
14 Edited by
15
16 Alex Balashov
17
18    <abalashov@evaristesys.com>
19
20 Edited by
21
22 Ovidiu Sas
23
24    <osas@voipembedded.com>
25
26    Copyright © 2008-2011 http://www.asipto.com
27      __________________________________________________________________
28
29    Table of Contents
30
31    1. Admin Guide
32
33         1. Overview
34         2. Dependencies
35
36               2.1. Kamailio Modules
37               2.2. External Libraries or Applications
38               2.3. Loading from database
39
40         3. Parameters
41
42               3.1. htable (str)
43               3.2. db_url (str)
44               3.3. key_name_column (str)
45               3.4. key_type_column (str)
46               3.5. value_type_column (str)
47               3.6. key_value_column (str)
48               3.7. expires_column (str)
49               3.8. array_size_suffix (str)
50               3.9. fetch_rows (integer)
51               3.10. timer_interval (integer)
52               3.11. db_expires (integer)
53               3.12. enable_dmq (integer)
54               3.13. timer_procs (integer)
55               3.14. event_callback (str)
56
57         4. Functions
58
59               4.1. sht_print()
60               4.2. sht_rm_name_re(htable=>regexp)
61               4.3. sht_rm_value_re(htable=>regexp)
62               4.4. sht_reset(htable)
63               4.5. sht_lock(htable=>key)
64               4.6. sht_unlock(htable=>key)
65               4.7. sht_iterator_start(iname, hname)
66               4.8. sht_iterator_end(iname)
67               4.9. sht_iterator_next(iname)
68
69         5. Exported pseudo-variables
70         6. RPC Commands
71
72               6.1. htable.get htable key
73               6.2. htable.delete htable key
74               6.3. htable.sets htable key value
75               6.4. htable.seti htable key value
76               6.5. htable.dump htable
77               6.6. htable.reload htable
78               6.7. htable.listTables
79               6.8. htable.stats
80
81         7. Event routes
82
83               7.1. htable:mod-init
84               7.2. htable:expired:<table>
85
86    List of Examples
87
88    1.1. Accessing $sht(htname=>key)
89    1.2. Dictionary attack limitation
90    1.3. Storing array values
91    1.4. Set hash_size parameter
92    1.5. Set db_url parameter
93    1.6. Set key_name_column parameter
94    1.7. Set key_type_column parameter
95    1.8. Set value_type_column parameter
96    1.9. Set key_value_column parameter
97    1.10. Set expires_column parameter
98    1.11. Set array_size_suffix parameter
99    1.12. Set fetch_rows parameter
100    1.13. Set timer_interval parameter
101    1.14. Set db_expires parameter
102    1.15. Set enable_dmq parameter
103    1.16. Set timer_procs parameter
104    1.17. Set event_callback parameter
105    1.18. sht_print usage
106    1.19. sht_rm_name_re usage
107    1.20. sht_rm_value_re usage
108    1.21. sht_reset usage
109    1.22. sht_lock usage
110    1.23. sht_unlock usage
111    1.24. sht_iterator_start usage
112    1.25. sht_iterator_end usage
113    1.26. sht_iterator_next usage
114
115 Chapter 1. Admin Guide
116
117    Table of Contents
118
119    1. Overview
120    2. Dependencies
121
122         2.1. Kamailio Modules
123         2.2. External Libraries or Applications
124         2.3. Loading from database
125
126    3. Parameters
127
128         3.1. htable (str)
129         3.2. db_url (str)
130         3.3. key_name_column (str)
131         3.4. key_type_column (str)
132         3.5. value_type_column (str)
133         3.6. key_value_column (str)
134         3.7. expires_column (str)
135         3.8. array_size_suffix (str)
136         3.9. fetch_rows (integer)
137         3.10. timer_interval (integer)
138         3.11. db_expires (integer)
139         3.12. enable_dmq (integer)
140         3.13. timer_procs (integer)
141         3.14. event_callback (str)
142
143    4. Functions
144
145         4.1. sht_print()
146         4.2. sht_rm_name_re(htable=>regexp)
147         4.3. sht_rm_value_re(htable=>regexp)
148         4.4. sht_reset(htable)
149         4.5. sht_lock(htable=>key)
150         4.6. sht_unlock(htable=>key)
151         4.7. sht_iterator_start(iname, hname)
152         4.8. sht_iterator_end(iname)
153         4.9. sht_iterator_next(iname)
154
155    5. Exported pseudo-variables
156    6. RPC Commands
157
158         6.1. htable.get htable key
159         6.2. htable.delete htable key
160         6.3. htable.sets htable key value
161         6.4. htable.seti htable key value
162         6.5. htable.dump htable
163         6.6. htable.reload htable
164         6.7. htable.listTables
165         6.8. htable.stats
166
167    7. Event routes
168
169         7.1. htable:mod-init
170         7.2. htable:expired:<table>
171
172 1. Overview
173
174    The module adds a hash table container to the configuration language.
175    The hash table is stored in shared memory and the access to it can be
176    done via pseudo-variables: $sht(htname=>name). The module supports
177    definition of many hash tables and can load values at startup from a
178    database table.
179
180    A typical use case for the SIP server is to implement a cache system in
181    configuration file - if a value is not found in hash table, load it
182    from database and store it in hash table so next time the access to it
183    is very fast. In the definition of the table you can define the default
184    expiration time of cached items. The expiration time can be adjusted
185    per item via assignment operation at runtime.
186
187    Replication between multiple servers is performed automatically (if
188    enabled) via the DMQ module.
189
190    You can read more about hash tables at:
191    http://en.wikipedia.org/wiki/Hash_table.
192
193    The “name” can be a static string or can include pseudo- variables that
194    will be replaced at runtime.
195
196    Example 1.1. Accessing $sht(htname=>key)
197 ...
198 modparam("htable", "htable", "a=>size=8;")
199 ...
200 $sht(a=>test) = 1;
201 $sht(a=>$ci::srcip) = $si;
202 ...
203
204    The next example shows a way to protect against dictionary attacks. If
205    someone fails to authenticate 3 times, it is forbidden for 15 minutes.
206    Authenticatiion against database is expensive as it does a select on
207    the “subscriber” table. By disabling the DB auth for 15 minutes,
208    resources on the server are saved and time to discover the password is
209    increased substantially. Additional alerting can be done by writing a
210    message to syslog or sending email, etc.
211
212    To implement the logic, two hash table variables are used: one counting
213    the failed authentications per user and one for storing the time of the
214    last authentication attempt. To ensure a unique name per user, the hash
215    table uses a combination of authentication username and text
216    “::auth_count” and “::last_auth”.
217
218    Example 1.2. Dictionary attack limitation
219 ...
220 modparam("htable", "htable", "a=>size=8;")
221 ...
222 if(is_present_hf("Authorization"))
223 {
224     if($sht(a=>$au::auth_count)==3)
225     {
226                 $var(exp) = $Ts - 900;
227         if($sht(a=>$au::last_auth) > $var(exp))
228         {
229             sl_send_reply("403", "Try later");
230             exit;
231         } else {
232             $sht(a=>$au::auth_count) = 0;
233         }
234     }
235     if(!www_authenticate("$td", "subscriber"))
236     {
237         switch ($retcode) {
238             case -1:
239                 sl_send_reply("403", "Forbidden");
240             exit;
241             case -2:
242                 if($sht(a=>$au::auth_count) == $null)
243                     $sht(a=>$au::auth_count) = 0;
244                 $sht(a=>$au::auth_count) = $sht(a=>$au::auth_count) + 1;
245                 if($sht(a=>$au::auth_count) == 3)
246                     xlog("auth failed 3rd time - src ip: $si\n");
247                 $sht(a=>$au::last_auth) = $Ts;
248             break;
249         }
250         www_challenge("$td"/*realm*/,"0"/*qop*/);
251         exit;
252     }
253     $sht(a=>$au::auth_count) = 0;
254 } else {
255     www_challenge("$td","0");
256     exit;
257 }
258 ...
259
260    The module also provides a way to store multiple values for a single
261    key. This is emulated by storing individual keys as 'key_name[n]',
262    where n is incremented for each key. The total number of keys is stored
263    in a dedicated key, by default: 'key_name::size'.
264
265    The array is built when the table is loaded in memory and afterwards
266    all the keys are treated as individual keys. If a particular entry in
267    the array is deleted, it is the administrator's responsibility to
268    update the size of the array and any other elements (if required).
269
270    Example 1.3. Storing array values
271 # Example of dbtext with multiple keys
272 $ cat /usr/local/etc/kamailio/dbtext/htable
273 1:key:1:0:value3:0
274 2:key:1:0:value2:0
275 3:key:1:0:value1:0
276
277 # The array key will be loaded in memory in the following format:
278 $ kamcmd htable.dump htable
279 {
280         entry: 35
281         size: 1
282         slot: {
283                 item: {
284                         name: key[0]
285                         value: value1
286                 }
287         }
288 }
289 {
290         entry: 50
291         size: 1
292         slot: {
293                 item: {
294                         name: key::size
295                         value: 3
296                 }
297         }
298 }
299 {
300         entry: 67
301         size: 1
302         slot: {
303                 item: {
304                         name: key[1]
305                         value: value2
306                 }
307         }
308 }
309 {
310         entry: 227
311         size: 1
312         slot: {
313                 item: {
314                         name: key[2]
315                         value: value3
316                 }
317         }
318 }
319
320 # Now let's delete a particular entry in the array: key[0].
321 $ kamcmd htable.delete htable key[0]
322
323 # The array key will look like this after a key was deleted:
324 $ kamcmd htable.dump htable
325 {
326         entry: 50
327         size: 1
328         slot: {
329                 item: {
330                         name: key::size
331                         value: 3
332                 }
333         }
334 }
335 {
336         entry: 67
337         size: 1
338         slot: {
339                 item: {
340                         name: key[1]
341                         value: value2
342                 }
343         }
344 }
345 {
346         entry: 227
347         size: 1
348         slot: {
349                 item: {
350                         name: key[2]
351                         value: value3
352                 }
353         }
354 }
355
356 2. Dependencies
357
358    2.1. Kamailio Modules
359    2.2. External Libraries or Applications
360    2.3. Loading from database
361
362 2.1. Kamailio Modules
363
364    The following modules must be loaded before this module:
365      * If DMQ replication is enabled, the DMQ module must be loaded
366        first..
367
368 2.2. External Libraries or Applications
369
370    The following libraries or applications must be installed before
371    running Kamailio with this module loaded:
372      * None.
373
374 2.3. Loading from database
375
376    The module is able to load values in a hash table at startup upon
377    providing a DB URL and table name.
378
379    The structure of the table must contain:
380      * key name - string containing the name of the key.
381      * key type - the type of the key
382           + 0 - simple key - the key is added as 'key_name'.
383           + 1 - array key - the key is added as 'key_name[n]' - n is
384             incremented for each key with this name to build an array in
385             hash table. In addition, an additional key is built to hold
386             the total number of key in the array, by default
387             key_name::size (see array_size_suffix parameter).
388      * value type - the type of the key value
389           + 0 - value is string.
390           + 1 - value is integer.
391      * key value - string containing the value of the key.
392
393 3. Parameters
394
395    3.1. htable (str)
396    3.2. db_url (str)
397    3.3. key_name_column (str)
398    3.4. key_type_column (str)
399    3.5. value_type_column (str)
400    3.6. key_value_column (str)
401    3.7. expires_column (str)
402    3.8. array_size_suffix (str)
403    3.9. fetch_rows (integer)
404    3.10. timer_interval (integer)
405    3.11. db_expires (integer)
406    3.12. enable_dmq (integer)
407    3.13. timer_procs (integer)
408    3.14. event_callback (str)
409
410 3.1. htable (str)
411
412    The definition of a hash table. The value of the parameter may have the
413    following format:
414      * "htname=>size=_number_;autoexpire=_number_;dbtable=_string_"
415
416    The parameter can be set multiple times to get more hash tables in same
417    configuration file.
418      * htname - string specifying the name of the hash table. This string
419        is used by $sht(...) to refer to the hash table.
420      * size - number specifying the size of hash table. Larger value means
421        less collisions. The number of entries (aka slots or buckets) in
422        the table is 2^size. The possible range for this value is from 2 to
423        31, smaller or larger values will be increased to 3 (8 slots) or
424        decreased to 14 (16384 slots).
425      * autoexpire -time in seconds to delete an item from a hash table if
426        no update was done to it. If is missing or set to 0, the items
427        won't expire.
428      * dbtable - name of database to be loaded at startup in hash table.
429        If empty or missing, no data will be loaded.
430      * cols - the column names of the database table. They must be
431        enclosed in quotes in order to form a valid SIP parameter value and
432        be separated by comma. The first column corresponds to key_name.
433        When specified, there must be at least two columns. If this
434        attribute is not specified, then the global module parameters for
435        column names are used. If more than one value columns are
436        specified, the hash table will pack the column values in a comma
437        separated string, which will be associated with the key (string
438        transformation {s.select,...} can be used in configuration file to
439        extract a specific column value). When cols attribute is present,
440        writing back to database table is disabled.
441      * dbmode - if set to 1, the content of hash table is written to
442        database table when the SIP server is stopped (i.e., ensure
443        persistency over restarts). Default value is 0 (no write back to db
444        table).
445      * initval - the integer value to be returned instead of $null when a
446        requested key is not set.
447      * updateexpire - if set to 1 (default), the time until expiration of
448        an item is reset when that item is updated. Certain uses of htable
449        may dictate that updates should not reset the expiration timeout,
450        however, in which case this attribute can be set to 0.
451      * dmqreplicate - if set to 1, any actions (set, update, delete etc.)
452        performed upon entries in this table will be replicated to other
453        nodes (htable peers). Please note, module parameter “enable_dmq”
454        must also be set in order for this to apply (see below). Default is
455        0 (no replication).
456
457    Default value is NULL.
458
459    Example 1.4. Set hash_size parameter
460 ...
461 modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
462 modparam("htable", "htable", "b=>size=5;")
463 modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;dmqreplicate=1
464 ;")
465 ...
466
467 3.2. db_url (str)
468
469    The URL to connect to database for loading values in hash table at
470    start up.
471
472    Default value is NULL (do not connect).
473
474    Example 1.5. Set db_url parameter
475 ...
476 modparam("htable", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio")
477 ...
478
479 3.3. key_name_column (str)
480
481    The name of the column containing the hash table key name.
482
483    Default value is 'key_name'.
484
485    Example 1.6. Set key_name_column parameter
486 ...
487 modparam("htable", "key_name_column", "kname")
488 ...
489
490 3.4. key_type_column (str)
491
492    The name of the column containing the hash table key type.
493
494    Default value is 'key_type'.
495
496    Example 1.7. Set key_type_column parameter
497 ...
498 modparam("htable", "key_type_column", "ktype")
499 ...
500
501 3.5. value_type_column (str)
502
503    The name of the column containing the hash table value type.
504
505    Default value is 'value_type'.
506
507    Example 1.8. Set value_type_column parameter
508 ...
509 modparam("htable", "value_type_column", "vtype")
510 ...
511
512 3.6. key_value_column (str)
513
514    The name of the column containing hash table key value.
515
516    Default value is 'key_value'.
517
518    Example 1.9. Set key_value_column parameter
519 ...
520 modparam("htable", "key_value_column", "kvalue")
521 ...
522
523 3.7. expires_column (str)
524
525    The name of the column containing the expires value.
526
527    Default value is 'expires'.
528
529    Example 1.10. Set expires_column parameter
530 ...
531 modparam("htable", "expires_column", "expiry")
532 ...
533
534 3.8. array_size_suffix (str)
535
536    The suffix to be added to store the number of items in an array (see
537    key type).
538
539    Default value is '::size'.
540
541    Example 1.11. Set array_size_suffix parameter
542 ...
543 modparam("htable", "array_size_suffix", "-count")
544 ...
545
546 3.9. fetch_rows (integer)
547
548    How many rows to fetch at once from database.
549
550    Default value is 100.
551
552    Example 1.12. Set fetch_rows parameter
553 ...
554 modparam("htable", "fetch_rows", 1000)
555 ...
556
557 3.10. timer_interval (integer)
558
559    Interval in seconds to check for expired htable values.
560
561    Default value is 20.
562
563    Example 1.13. Set timer_interval parameter
564 ...
565 modparam("htable", "timer_interval", 10)
566 ...
567
568 3.11. db_expires (integer)
569
570    If set to 1, the module will load/save the expires values of the items
571    in hash table from/to database. It applies only to hash tables that
572    have the auto-expires attribute defined.
573
574    Default value is 0.
575
576    Example 1.14. Set db_expires parameter
577 ...
578 modparam("htable", "db_expires", 1)
579 ...
580
581 3.12. enable_dmq (integer)
582
583    If set to 1, will enable DMQ replication of actions performed upon
584    entries in all tables having "dmqreplicate" parameter set. Any update
585    action performed via pseudo-variables and RPC commands will be repeated
586    on all other nodes. Therefore, it is important to ensure the table
587    definition (size, autoexpire etc.) is identical across all instances.
588
589    Important: If this parameter is enabled, the DMQ module must be loaded
590    first - otherwise, startup will fail.
591
592    Currently, values are not replicated on load from DB as it is expected
593    that in these cases, all servers will load their values from the same
594    DB.
595
596    Default value is 0.
597
598    Example 1.15. Set enable_dmq parameter
599 ...
600 modparam("htable", "enable_dmq", 1)
601 ...
602
603 3.13. timer_procs (integer)
604
605    If set to 1 or greater, the module will create its own timer processes
606    to scan for expired items in hash tables. If set to zero, it will use
607    the core timer for this task. Set it to 1 if you store a lot of items
608    with autoexpire property.
609
610    Default value is 0.
611
612    Example 1.16. Set timer_procs parameter
613 ...
614 modparam("htable", "timer_procs", 4)
615 ...
616
617 3.14. event_callback (str)
618
619    The name of the function in the kemi configuration file (embedded
620    scripting language such as Lua, Python, ...) to be executed instead of
621    event_route[...] blocks.
622
623    The function receives a string parameter with the name of the event,
624    the values can be: 'htable:mod-init', 'htable:expired:htname' ('htname'
625    being the name of hash table).
626
627    Default value is 'empty' (no function is executed for events).
628
629    Example 1.17. Set event_callback parameter
630 ...
631 modparam("htable", "event_callback", "ksr_htable_event")
632 ...
633 -- event callback function implemented in Lua
634 function ksr_htable_event(evname)
635         KSR.info("===== htable module triggered event: " .. evname .. "\n");
636         return 1;
637 end
638 ...
639
640 4. Functions
641
642    4.1. sht_print()
643    4.2. sht_rm_name_re(htable=>regexp)
644    4.3. sht_rm_value_re(htable=>regexp)
645    4.4. sht_reset(htable)
646    4.5. sht_lock(htable=>key)
647    4.6. sht_unlock(htable=>key)
648    4.7. sht_iterator_start(iname, hname)
649    4.8. sht_iterator_end(iname)
650    4.9. sht_iterator_next(iname)
651
652 4.1.  sht_print()
653
654    Dump content of hash table to L_ERR log level. Intended for debug
655    purposes.
656
657    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
658    ONREPLY_ROUTE, BRANCH_ROUTE.
659
660    Example 1.18. sht_print usage
661 ...
662 sht_print();
663 ...
664
665 4.2.  sht_rm_name_re(htable=>regexp)
666
667    Delete all entries in the htable that match the name against regular
668    expression.
669
670    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
671    ONREPLY_ROUTE, BRANCH_ROUTE.
672
673    Example 1.19. sht_rm_name_re usage
674 ...
675 sht_rm_name_re("ha=>.*");
676 ...
677
678 4.3.  sht_rm_value_re(htable=>regexp)
679
680    Delete all entries in the htable that match the value against regular
681    expression.
682
683    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
684    ONREPLY_ROUTE, BRANCH_ROUTE.
685
686    Example 1.20. sht_rm_value_re usage
687 ...
688 sht_rm_value_re("ha=>.*");
689 ...
690
691 4.4.  sht_reset(htable)
692
693    Delete all entries in the htable. The name of the hash table can be a
694    dynamic string with variables.
695
696    This function can be used from ANY_ROUTE.
697
698    Example 1.21. sht_reset usage
699 ...
700 sht_reset("ha$var(x)");
701 ...
702
703 4.5.  sht_lock(htable=>key)
704
705    Lock the slot in htable corresponding to the key item. Note that the
706    locking is re-entrant for the process, therefore the lock and unlock
707    should be done by the same process.
708
709    This function can be used from ANY_ROUTE.
710
711    Example 1.22. sht_lock usage
712 ...
713 sht_lock("ha=>test");
714 ...
715
716 4.6.  sht_unlock(htable=>key)
717
718    Unlock the slot in htable corespoding to the key item. Note that the
719    locking is re-entrant for the process, therefore the lock and unlock
720    should be done by the same process.
721
722    This function can be used from ANY_ROUTE.
723
724    Example 1.23. sht_unlock usage
725 ...
726 sht_lock("ha=>test");
727 $sht(ha=>test) = $sht(ha=>test) + 10;
728 sht_unlock("ha=>test");
729 ...
730
731 4.7.  sht_iterator_start(iname, hname)
732
733    Start an iterator for hash table named by the value of parameter hname.
734    The parameter iname is used to identify the iterator. There can be up
735    to 4 iterators at the same time, with different name.
736
737    Both parameters can be dynamic strings with variables.
738
739    IMPORTANT: the slot of the hash table is left locked when retrieving in
740    item. Therefore be sure you do not update the content of the hash table
741    in between sht_iterator_start() and sht_iterator_end(), because it may
742    end up in dead lock.
743
744    This function can be used from ANY_ROUTE.
745
746    Example 1.24. sht_iterator_start usage
747 ...
748 sht_iterator_start("i1", "h1");
749 ...
750
751 4.8.  sht_iterator_end(iname)
752
753    Close the iterator identified by iname parameter and release the hash
754    table slot aquired by the iterator. The iname value must be the same
755    used for sht_iterator_start().
756
757    The parameter can be dynamic string with variables.
758
759    This function can be used from ANY_ROUTE.
760
761    Example 1.25. sht_iterator_end usage
762 ...
763 sht_iterator_end("i1");
764 ...
765
766 4.9.  sht_iterator_next(iname)
767
768    Move the iterator to the next item in hash table. It must be called
769    also after sht_iterator_start() to get the first item in the hash
770    table. Items are returned as they are found in the hash table slot,
771    starting with the first slot.
772
773    The return code is false when there is no (more) item in the hash
774    table.
775
776    The item name and value are accessible via variables: $shtitkey(iname)
777    and $shtitval(iname).
778
779    The parameter can be dynamic string with variables.
780
781    This function can be used from ANY_ROUTE.
782
783    Example 1.26. sht_iterator_next usage
784 ...
785     sht_iterator_start("i1", "h1");
786     while(sht_iterator_next("i1")) {
787         xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
788     }
789     sht_iterator_end("i1");
790 ...
791
792 5. Exported pseudo-variables
793
794      * $sht(htable=>key)
795      * $shtex(htable=>key)
796      * $shtcn(htable=>key)
797      * $shtcv(htable=>key)
798      * $shtinc(htable=>key)
799      * $shtitkey(iname)
800      * $shtitval(iname)
801      * $shtrecord(attribute)
802
803    Exported pseudo-variables are documented at
804    https://www.kamailio.org/wiki/.
805
806 6. RPC Commands
807
808    6.1. htable.get htable key
809    6.2. htable.delete htable key
810    6.3. htable.sets htable key value
811    6.4. htable.seti htable key value
812    6.5. htable.dump htable
813    6.6. htable.reload htable
814    6.7. htable.listTables
815    6.8. htable.stats
816
817 6.1.  htable.get htable key
818
819    Lists one value in a hash table
820
821    Name: htable.get
822
823    Parameters:
824      * htable : Name of the hash table to dump
825      * key : Key name of the hash table value to dump
826
827    Example:
828 ...
829 # Dump $sht(students=>alice)
830 kamcmd htable.get students alice
831
832 # Dump first entry in array key course $sht(students=>course[0])
833 kamcmd htable.get students course[0]
834 ...
835
836 6.2.  htable.delete htable key
837
838    Delete one value in a hash table
839
840    Name: htable.delete
841
842    Parameters:
843      * htable : Name of the hash table to delete
844      * key : Key name of the hash table value to delete
845
846    Example:
847 ...
848 # Delete $sht(students=>alice)
849 kamcmd htable.delete students alice
850
851 # Delete first entry in array key course $sht(students=>course[0])
852 kamcmd htable.delete students course[0]
853 ...
854
855 6.3.  htable.sets htable key value
856
857    Set an item in hash table to string value.
858
859    Name: htable.sets
860
861    Parameters:
862      * htable : Name of the hash table
863      * key : Key name in the hash table
864      * Value : String value for the item
865
866    Example:
867 ...
868 # Set $sht(test=>x) as string
869 kamcmd htable.sets test x abc
870
871 # Set firsti entry in array key x $sht(test=>x[0]) as string
872 kamcmd htable.sets test x[0] abc
873 ...
874
875 6.4.  htable.seti htable key value
876
877    Set an item in hash table to integer value.
878
879    Name: htable.seti
880
881    Parameters:
882      * htable : Name of the hash table
883      * key : Key name in the hash table
884      * Value : Integer value for the item
885
886    Example:
887 ...
888 # Set $sht(test=>x) as integer
889 kamcmd htable.seti test x 123
890
891 # Set firsti entry in array key x $sht(test=>x[0]) as integer
892 kamcmd htable.sets test x[0] 123
893 ...
894
895 6.5.  htable.dump htable
896
897    Lists all the values in a hash table
898
899    Name: dhtable.dump
900
901    Parameters:
902      * htable : Name of the hash table to dump
903
904    Example:
905 ...
906 kamcmd htable.dump ipban
907 ...
908
909 6.6.  htable.reload htable
910
911    Reload hash table from database.
912
913    Name: dhtable.reload
914
915    Parameters:
916      * htable : Name of the hash table to reload
917
918    Example:
919 ...
920 kamcmd htable.reload ipban
921 ...
922
923 6.7.  htable.listTables
924
925    Lists all defined tables
926
927    Name: htable.listTables
928
929    Parameters:
930      * None
931
932    Example:
933 ...
934 kamcmd htable.listTables
935 ...
936
937 6.8.  htable.stats
938
939    Get statistics for hash tables - name, number of slots, number of
940    items, max number of items per slot, min number of items per slot.
941
942    Name: htable.stats
943
944    Parameters:
945      * None
946
947    Example:
948 ...
949 kamcmd htable.stats
950 ...
951
952 7. Event routes
953
954    7.1. htable:mod-init
955    7.2. htable:expired:<table>
956
957 7.1.  htable:mod-init
958
959    When defined, the module calls event_route[htable:mod-init] after all
960    modules have been initialized. A typical use case is to initialise
961    items in hash tables. The event route is executed only once, after core
962    and module initialization, but before Kamailio forks any child
963    processes.
964 ...
965 event_route[htable:mod-init] {
966     $sht(a=>x) = 1;
967 }
968 ...
969
970 7.2.  htable:expired:<table>
971
972    When defined, the module calls event_route[htable:expired:<table>] when
973    an entry in the given table expires. In this event route, the key and
974    value of the expired record are available with the $shtrecord(key) and
975    $shtrecord(value) pseudo-variables.
976 ...
977
978 event_route[htable:expired:mytable] {
979     xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
980 }
981 ...