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