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